Chapter 12. Drawing Area
Prev |  | Next

## Chapter 12. Drawing Area

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”.

### Note

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.

## 12.1. Graphics Context

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 color name (e.g. "red", "orange", "navajo white" as defined in the X Window file `rgb.txt`), or
- a hexadecimal string starting with '#' and containing three sets of hex digits of the same length (1, 2, 3 or 4 digits). For example, "#F0A", "#FF00AA", "#FFF000AAA" and "#FFFF0000AAAA" all represent the same color.

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.

### Note

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.Window`s. 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`.

Prev | Up | Next
11.4. Item Factory Example | Home | 12.2. Drawing Methods