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:
A 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=-1
join_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.