Graphics Contexts

A graphics context, or GC, is simply a set of parameters to be used when drawing (such as color, clip mask, font, and so on). It is a server-side resource, just as pixmaps and windows are. GCs reduce the number of arguments to the GDK drawing functions, and also reduce the number of parameters passed from client to server with each drawing request.

A graphics context can be created with a GdkGCValues struct, analagous to GdkWindowAttr; the struct contains all the interesting features of a graphics context, and you pass gdk_gc_new_with_values() flags indicating which fields are valid. The other fields retain their default value. You can also create an all-default GC with gdk_gc_new() (this is usually easier). Functions are provided to change GC settings after the GC is created as well---but remember that each change requires a message to the X server. These functions are summarized in Figure 16. The attributes of a GC, and the flags used as the final argument to gdk_gc_new_with_values(), are summarized in Table 6.

All GCs are not interchangeable; they are tied to a particular depth and visual. The GC's depth and visual must match the depth and visual of the drawable you are drawing to. A GC's depth and visual are taken from the GdkWindow* argument to gdk_gc_new(), so the easiest way to handle this issue is to create the GC with the window you plan to draw on.

GdkGCValues is a nice summary of a GC's attributes:

typedef struct _GdkGCValues GdkGCValues;

struct _GdkGCValues
{
  GdkColor          foreground;
  GdkColor          background;
  GdkFont          *font;
  GdkFunction       function;
  GdkFill           fill;
  GdkPixmap        *tile;
  GdkPixmap        *stipple;
  GdkPixmap        *clip_mask;
  GdkSubwindowMode  subwindow_mode;
  gint              ts_x_origin;
  gint              ts_y_origin;
  gint              clip_x_origin;
  gint              clip_y_origin;
  gint              graphics_exposures;
  gint              line_width;
  GdkLineStyle      line_style;
  GdkCapStyle       cap_style;
  GdkJoinStyle      join_style;
};

The foreground color is the "pen color" used to draw lines, circles, and other shapes. The purpose of the background color depends on the particular drawing operation. These colors must be allocated in the current colormap with gdk_color_alloc().

The font field is unused: in Xlib, it specifies the font to use when drawing text. In GDK, it used to have the same purpose; but now the GDK routines for drawing text all require a GdkFont* argument instead. An Xlib graphics context can only store plain fonts, but a GdkFont can also represent a fontset (used to render some foreign languages). GDK should probably store a font field in its GdkGC instead of requiring a font argument to the text-drawing functions, but it doesn't.

The function field specifies how each pixel being drawn is combined with the pixel that already exists in the drawable. There are many possible values, but only two are ever used:

• GDK_COPY is the default. It ignores the existing pixel (just writes the new pixel over it).

• GDK_XOR combines the old and new pixels in an invertable way. That is, if you perform exactly the same GDK_XOR operation twice, the first draw is undone by the second. GDK_XOR is often used for "rubberbanding," since it makes it easy to restore the original contents of the drawable once rubberbanding is complete.

The fill field determines how the tile and stipple fields are used. A tile is a pixmap with the same depth as the destination drawable; it is copied over and over into the destination drawable---the origin of the first tile is (ts_x_origin, ts_y_origin). A stipple is a bitmap (pixmap with depth 1); stipples are also tiled starting at (ts_x_origin, ts_y_origin). Possible fill values are:

• GDK_SOLID means to ignore the tile and stipple. Shapes are drawn in the foreground and background colors.

• GDK_TILED means that shapes are drawn with the tile, instead of the foreground and background colors. Imagine a tiled surface underneath your drawable; drawing in GDK_TILED mode will scratch away the contents of the drawable, revealing the tiled surface underneath.

• GDK_STIPPLED is like GDK_SOLID with a bitmask defined by the stipple. That is, bits not set in the stipple are not drawn.

• GDK_OPAQUE_STIPPLED draws bits set in the stipple with the foreground color, and bits not set in the stipple with the background color.

Some X servers do not implement the more obscure function and fill modes very efficiently. Don't be surprised if using them noticeably slows down drawing.

The optional clip_mask is a bitmap; only bits set in this bitmap will be drawn. The mapping from the clip mask to the drawable is determined by clip_x_origin and clip_y_origin; these define the drawable coordinates corresponding to (0,0) in the clip mask. It is also possible to set a clip rectangle (the most common and useful form of clipping) or a clip region (a region is an arbitrary area on the screen, typically a polygon or list of rectangles). To set a clip rectangle, use gdk_gc_set_clip_rectangle():

  GdkRectangle clip_rect;
  clip_rect.x = 10;
  clip_rect.y = 20;
  clip_rect.width = 200;
  clip_rect.height = 100;
  gdk_gc_set_clip_rectangle(gc, &clip_rect);

To turn off clipping, set the clip rectangle, clip region, or clip mask to NULL.

The subwindow_mode of a GC only matters if the drawable is a window. The default setting is GDK_CLIP_BY_CHILDREN; this means that child windows are not affected by drawing on parent windows. This preserves the illusion that child windows are "on top" of parents, and child windows are opaque. GDK_INCLUDE_INFERIORS will draw right over the top of any child windows, overwriting any graphics the child windows may contain; normally this mode is not used. If you do use GDK_INCLUDE_INFERIORS, you will probably use GDK_XOR as your drawing function, since it allows you to restore the child windows' previous contents.

graphics_exposures is a boolean value which defaults to TRUE; it determines whether gdk_window_copy_area() sometimes generates expose events. the section called Expose Events explained this in more detail.

The final four GC values determine how lines are drawn. These values are used for drawing lines, including the borders of unfilled polygons and arcs. The line_width field specifies the width of a line, in pixels. A line width of 0 specifies a "thin line"; thin lines are one-pixel lines that can be drawn very quickly (usually with hardware acceleration), but the exact pixels drawn depend on the X server in use. For consistent results, use a width of 1 instead.

The line_style field can have one of three values:

• GDK_LINE_SOLID is the default; a solid line.

• GDK_LINE_ON_OFF_DASH draws a dashed line with the foreground color, leaving the "off" parts of the dash blank.

• GDK_LINE_DOUBLE_DASH draws a dashed line in the foreground color, but the "off" parts of the dash are drawn in the background color.

Dashes are specified with gdk_gc_set_dashes(); GdkGCValues does not include a field for this. gdk_gc_set_dashes() accepts three arguments:

• dash_list is an array of dash lengths. Even-indexed lengths are "on" dashes; these are drawn in the foreground color. Odd-indexed lengths are "off" dashes; they are not drawn or drawn in the background color, depending on line_style. 0 is not a permitted value; all lengths must be positive.

• dash_offset is the index of the first pixel to use in the dash list. That is, if the dash list specifies 5 pixels "on" and 5 "off", and the offset is 3, the line will begin in the middle of the "on" dash.

• n is simply the number of elements in dash_list.

You might set a whimsical dash pattern this way, for example:

  gchar dash_list[] = { 5, 5, 3, 3, 1, 1, 3, 3 };
  gdk_gc_set_dashes(gc, 0, dash_list, sizeof(dash_list));

The default dash list is {4, 4} with an offset of 0.

Figure 13 shows some dashed lines drawn with GDK_LINE_DOUBLE_DASH. The graphics context's foreground color is black, and its background color is a light gray. The first five lines are the default {4, 4} dash pattern with offsets of 0, 1, 2, 3, and 4. Remember that 0 is the default. Figure 14 shows a magnified view of these five lines. The last line is the whimsical dash pattern mentioned above; it's shown magnified in Figure 15.

cap_style determines how X draws line endpoints (or dash endpoints, if a line is dashed). It has four possible values:

• GDK_CAP_BUTT is the default; it means that lines have square ends (as you might expect).

• GDK_CAP_NOT_LAST specifies that the last pixel is skipped for one-pixel lines. It is otherwise the same as GDK_CAP_BUTT.

• GDK_CAP_ROUND draws a small arc on the end of the line, extending beyond the line's endpoint. The center of the arc is on the endpoint, and the radius of the arc is one-half the width of the line. For one-pixel lines, it has no effect (since there is no way to draw a one-pixel-wide arc).

• GDK_CAP_PROJECTING extends the line past its endpoint by one-half its width. It has no effect on one-pixel lines.

The join_style parameter affects how lines are connected to one another, when drawing a polygon or drawing multiple lines in one function call. If you think of lines as long, thin rectangles, it is clear that they do not connect smoothly; there is a "notch" where the two endpoints come together. The three join styles fill in this notch:

• GDK_JOIN_MITER is the default; it draws a sharp angle where the lines intersect.

• GDK_JOIN_ROUND creates rounded corners by drawing an arc in the notch.

• GDK_JOIN_BEVEL creates a flat corner, filling the notch with the smallest possible shape.

#include <gdk/gdk.h>