Table of Contents
The DrawingArea widget wraps a
gtk.gdk.Window which is a subclass of
gtk.gdk.Drawable (as is a
gtk.gdk.Pixmap). In effect the
DrawingArea provides a simple 'canvas' area (the
wrapped gtk.gdk.Window) that can be drawn on using
the methods of the gtk.gdk.Drawable class.
A DrawingArea is created using the
constructor:
drawing_area = gtk.DrawingArea()
A DrawingArea is initially created with a
size of (0, 0) so you should use the following method to make the
drawing_area visible by setting its width and height
to useful values greater than zero:
drawing_area.set_size_request(width,height)
To draw on a DrawingArea you must retrieve
the wrapped gtk.gdk.Window using the
window attribute of the
DrawingArea as follows:
drawable = drawing_area.window
Then you can draw on drawable using the
gtk.gdk.Drawable methods described in Section 12.2, “Drawing Methods”.
The DrawingArea must be realized (i.e. the
Widget methods realize() or
show() have been called) to have an associated
gtk.gdk.Window that can be used for drawing.
A variety of methods are available to draw onto the
gtk.gdk.Window of a
DrawingArea. All these methods require a graphics
context (gtk.gdk.GC) to encapsulate, as attributes,
the information required for drawing. The attributes of a
gtk.gdk.GC are:
background cap_style clip_mask clip_x_origin clip_y_origin fill font foreground function graphics_exposures join_style line_style line_width stipple sub_window tile ts_x_origin ts_y_origin
background specifies an allocated
gtk.gdk.Color that is used to draw the background
color.
foreground specifies an allocated
gtk.gdk.Color that is used to draw the foreground
color.
A gtk.gdk.Color represents a color that
may be allocated or unallocated. An unallocated color can be created
using the constructor:
color = gtk.gdk.Color(red=0,green=0,blue=0,pixel=0)
where red, green and
blue are integers in the range of 0 to
65535. pixel is not usually specified because it is
overwritten when the color is allocated.
Alternatively, an unallocated gtk.gdk.Color
can be created using the function:
color = gtk.gdk.color_parse(spec)
where spec is a color specification string
that can be either:
rgb.txt), orA gtk.gdk.Color representing an allocated
color is created using the gtk.gdk.Colormap
alloc_color() method which has three
signatures:
color = colormap.alloc_color(color,writeable=FALSE,best_match=TRUE) color = colormap.alloc_color(spec,writeable=FALSE,best_match=TRUE) color = colormap.alloc_color(red,green,blue,writeable=FALSE,best_match=TRUE)
color is an unallocated
gtk.gdk.Color. spec is a color
specification string as described above for the
gtk.gdk.color_parse()
function. red, green and
blue are integer color values as described for the
gtk.gdk.Color() constructor. You can optionally specify
whether the allocated color should be writeable (i.e. can be changed later
but cannot be shared) or whether a best match with existing colors should be
made if the exact color is not available.
For example:
navajowhite = colormap.alloc('navajo white')
cyan = colormap.alloc(0, 65535, 65535)
red = colormap.alloc_color('#FF0000', True, True)
The colormap associated with a widget can be retrieved using the method:
colormap = widget.get_colormap()
cap_style specifies the line ending style
that is used when drawing the end of a line that is not joined to another
line. The available cap styles are:
CAP_NOT_LAST | draws line ends the same as CAP_BUTT
for lines of non-zero width. For zero width lines, the final point on the
line will not be drawn. |
CAP_BUTT | the ends of the lines are drawn squared off and extending to the coordinates of the end point. |
CAP_ROUND | the ends of the lines are drawn as semicircles with the diameter equal to the line width and centered at the end point. |
CAP_PROJECTING | the ends of the lines are drawn squared off and extending half the width of the line beyond the end point. |
clip_mask specifies a
gtk.gdk.Pixmap that is used to clip the drawing in
the drawing_area.
clip_x_origin and
clip_y_origin specify the origin x and y values relative
to the upper left corner of the drawing_area for
clipping.
fill specifies the fill style to be used
when drawing. The available fill styles are:
SOLID | draw with the foreground color. |
TILED | draw with a tiled pixmap. |
STIPPLED | draw using the stipple bitmap. Pixels corresponding to bits in the stipple bitmap that are set will be drawn in the foreground color; pixels corresponding to bits that are not set will be left untouched. |
OPAQUE_STIPPLED | draw using the stipple bitmap. Pixels corresponding to bits in the stipple bitmap that are set will be drawn in the foreground color; pixels corresponding to bits that are not set will be drawn with the background color. |
font is a
gtk.gdk.Font that is used as the default font for
drawing text.
The use of the font attribute is
deprecated.
function specifies how the bit values for
the source pixels are combined with the bit values for destination pixels to
produce the resulting pixels bits. The sixteen values here correspond to the
16 different possible 2x2 truth tables but only a couple of these values are
usually useful. For color images, only COPY, XOR and INVERT are generally
useful while for bitmaps, AND and OR are also useful. The function values
are:
COPY INVERT XOR CLEAR AND AND_REVERSE AND_INVERT NOOP OR EQUIV OR_REVERSE COPY_INVERT OR_INVERT NAND SET
graphics_exposures specifies whether
graphics exposures are enabled (TRUE) or disabled
(FALSE). When graphics_exposures
is TRUE, a failure when copy pixels in a drawing
operation will cause an expose event to be issued. If the copy succeeds, a
noexpose event is issued.
join_style specifies the style of joint to be
used when lines meet at an angle. The available styles are:
JOIN_MITER | the sides of each line are extended to meet at an angle. |
JOIN_ROUND | the sides of the two lines are joined by a circular arc. |
JOIN_BEVEL | the sides of the two lines are joined by a straight line which makes an equal angle with each line. |
line_style specifies the style that a line
will be drawn with. The available styles are:
LINE_SOLID | lines are drawn as continuous segments. |
LINE_ON_OFF_DASH | even segments are drawn; odd segments are not drawn. |
LINE_DOUBLE_DASH | even segments are normally. Odd segments are drawn in the
background color if the fill style is SOLID, or in the
background color masked by the stipple if the fill style is
STIPPLED. |
line_width specifies the width that lines
will be drawn with.
stipple specifies the
gtk.gdk.Pixmap that will be used for stippled drawing
when the fill is set to either STIPPLED or OPAQUE_STIPPLED.
sub_window specifies the mode of drawing
into a gtk.gdk.Window that has child
gtk.gdk.Windows. The possible values of
sub_window are:
CLIP_BY_CHILDREN | only draw onto the window itself but not its child windows |
INCLUDE_INFERIORS | draw onto the window and its child windows. |
tile specifies the
gtk.gdk.Pixmap to used for tiled drawing when the
fill is set to TILED.
ts_x_origin and
ts_y_origin specify the tiling/stippling origin (the
starting position for the stippling bitmap or tiling pixmap).
A new Graphics Context is created by a call to the
gtk.gdk.Drawable.new_gc() method:
gc = drawable.new_gc(foreground=None,background=None,font=None,function=-1,fill=-1,tile=None,stipple=None,clip_mask=None,subwindow_mode=-1,ts_x_origin=-1,ts_y_origin=-1,clip_x_origin=-1,clip_y_origin=-1,graphics_exposures=-1,line_width=-1,line_style=-1,cap_style=-1join_style=-1)
In order for a new Graphics Context to be created with this method, the drawable must be:
a gtk.gdk.Window which has been
realized (created), or;
a gtk.gdk.Pixmap associated with a
realized gtk.gdk.Window.
The various attributes of the Graphics Context have default values
if not set in the new_gc() method. If you want to
set the GC attributes using the new_gc() method,
it's much easier to use the Python keyword arguments.
The individual attributes of a gtk.gdk.GC
can also be set by assigning a value to the GC object attribute. For
example:
gc.cap_style = CAP_BUTT gc.line_width = 10 gc.fill = SOLD gc.foreground = mycolor
or by using the following methods:
gc.set_foreground(color) gc.set_background(color) gc.set_function(function) gc.set_fill(fill) gc.set_tile(tile) gc.set_stipple(stipple) gc.set_ts_origin(x, y) gc.set_clip_origin(x, y) gc.set_clip_mask(mask) gc.set_clip_rectangle(rectangle) gc.set_subwindow(mode) gc.set_exposures(exposures) gc.set_line_attributes(line_width, line_style, cap_style, join_style)
The dash pattern to be used when the
line_style is LINE_ON_OFF_DASH or
LINE_DOUBLE_DASH can be set using the following
method:
gc.set_dashes(offset, dash_list)
where offset is the index of the starting
dash value in dash_list and
dash_list is a list or tuple containing numbers of
pixels to be drawn or skipped to form the dashes. The dashes are drawn
starting with the number of pixels at the offset position; then the next
number of pixels is skipped; and then the next number is drawn; and so on
rotating through all the dash_list numbers and starting over when the end is
reached. For example, if the dash_list is (2, 4, 8, 16) and the offset is 1,
the dashes will be drawn as: draw 4 pixels, skip 8 pixels, draw 16 pixels,
skip 2 pixels, draw 4 pixels and so on.
A copy of an existing gtk.gdk.GC can be
made using the method:
gc.copy(src_gc)
The attributes of gc will then be the same as
src_gc.