16.2. Drawing Area

drawing_area = GtkDrawingArea()

A Drawing Area is created with a size of (0, 0) so you should use the following method to make the drawing_area visible:
 

drawing_area.size(width, height)

16.2.1 Graphics Context

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 the GdkColor that is used to draw the background color.

foreground specifies the GdkColor that is used to draw the foreground color.

A GdkColor is created by using the GdkColormap method alloc(). The colormap associated with a widget can be retrieved using the method:

colormap = widget.get_colormap()

A GdkColor can be specified as either a string color name (e.g. "red", "orange", "navajo white" defined in the X Window file rgb.txt), or as a triple of red, green and blue integers in the range of 0 to 65535. For example:

navajowhite = colormap.alloc('navajo white')

cyan = colormap.alloc(0, 65535, 65535)

cap_style specifies the line ending style that is used when drawing end of a line that is not joined. The available cap styles (defined in GDK.py) are:
 

CAP_NOT_LAST       # 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 GdkBitmap 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 (defined in GDK.py) 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 GdkFont that is used as the default font for drawing text.

function specifies how the bit values for the source pixels are combined with the bit values for destination pixels to produce the final result. The sixteen values here correspond to the 16 different possible 2x2 truth tables. Only a couple of these values are usually useful; for colored images, only COPY, XOR and INVERT are generally useful. For bitmaps, AND and OR are also useful. The function values (defined in GDK.py) 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 to 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 (defined in GDK.py) 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 (defined in GDK.py) are:
 

LINE_SOLID              # lines are drawn solid.     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 GdkBitmap 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 GdkWindows with child GdkWindow. The available values (defined in GDK.py) 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 GdkPixmap 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 GdkWindow new_gc() method:
 

gc = widget.get_window().new_gc()

In order for a new Graphics Context to be created with this method, the widget must be a type that has a GdkWindow and the widget must be realized (i.e. the GdkWindow has been created).

The various attributes of the Graphics Context can be set in the new_gc() method by using Python keyword arguments. For example:
 

gc = widget.get_window().new_gc(      foreground=fgcolor,      background=bgcolor,      cap_style=CAP_ROUND,      fill=STIPPLED,      function=COPY,      font=myfont,      join_Style=JOIN_BEVEL,      line_style=LINE_DOUBLE_DASH,      line_width=5,      stipple=mystipple      )

The individual attributes of a GdkGC can be set by assigning a value to the attribute. For example:
 

gc.cap_style = CAP_BUTT gc.line_width = 10 gc.fill = SOLD gc.foreground = mycolor

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.