GDK Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# Graphics Contexts

## Name

Graphics Contexts -- objects to encapsulate drawing properties.

## Synopsis

    #include <gdk/gdk.h>

    struct      GdkGC;
    struct      GdkGCValues;
    enum        GdkGCValuesMask;
    enum        GdkFunction;
    GdkGC*      gdk_gc_new                      (GdkDrawable *drawable);
    GdkGC*      gdk_gc_new_with_values          (GdkDrawable *drawable,
                                                 GdkGCValues *values,
                                                 GdkGCValuesMask values_mask);
    GdkScreen*  gdk_gc_get_screen               (GdkGC *gc);
    GdkGC*      gdk_gc_ref                      (GdkGC *gc);
    void        gdk_gc_unref                    (GdkGC *gc);
    #define     gdk_gc_destroy
    void        gdk_gc_set_values               (GdkGC *gc,
                                                 GdkGCValues *values,
                                                 GdkGCValuesMask values_mask);
    void        gdk_gc_get_values               (GdkGC *gc,
                                                 GdkGCValues *values);
    void        gdk_gc_set_foreground           (GdkGC *gc,
                                                 GdkColor *color);
    void        gdk_gc_set_background           (GdkGC *gc,
                                                 GdkColor *color);
    void        gdk_gc_set_rgb_fg_color         (GdkGC *gc,
                                                 GdkColor *color);
    void        gdk_gc_set_rgb_bg_color         (GdkGC *gc,
                                                 GdkColor *color);
    void        gdk_gc_set_font                 (GdkGC *gc,
                                                 GdkFont *font);
    void        gdk_gc_set_function             (GdkGC *gc,
                                                 GdkFunction function);
    void        gdk_gc_set_fill                 (GdkGC *gc,
                                                 GdkFill fill);
    enum        GdkFill;
    void        gdk_gc_set_tile                 (GdkGC *gc,
                                                 GdkPixmap *tile);
    void        gdk_gc_set_stipple              (GdkGC *gc,
                                                 GdkPixmap *stipple);
    void        gdk_gc_set_ts_origin            (GdkGC *gc,
                                                 gint x,
                                                 gint y);
    void        gdk_gc_set_clip_origin          (GdkGC *gc,
                                                 gint x,
                                                 gint y);
    void        gdk_gc_set_clip_mask            (GdkGC *gc,
                                                 GdkBitmap *mask);
    void        gdk_gc_set_clip_rectangle       (GdkGC *gc,
                                                 GdkRectangle *rectangle);
    void        gdk_gc_set_clip_region          (GdkGC *gc,
                                                 GdkRegion *region);
    void        gdk_gc_set_subwindow            (GdkGC *gc,
                                                 GdkSubwindowMode mode);
    enum        GdkSubwindowMode;
    void        gdk_gc_set_exposures            (GdkGC *gc,
                                                 gboolean exposures);
    void        gdk_gc_set_line_attributes      (GdkGC *gc,
                                                 gint line_width,
                                                 GdkLineStyle line_style,
                                                 GdkCapStyle cap_style,
                                                 GdkJoinStyle join_style);
    enum        GdkLineStyle;
    enum        GdkCapStyle;
    enum        GdkJoinStyle;
    void        gdk_gc_set_dashes               (GdkGC *gc,
                                                 gint dash_offset,
                                                 gint8 dash_list[],
                                                 gint n);
    void        gdk_gc_copy                     (GdkGC *dst_gc,
                                                 GdkGC *src_gc);
    void        gdk_gc_set_colormap             (GdkGC *gc,
                                                 GdkColormap *colormap);
    GdkColormap* gdk_gc_get_colormap            (GdkGC *gc);
    void        gdk_gc_offset                   (GdkGC *gc,
                                                 gint x_offset,
                                                 gint y_offset);

## Object Hierarchy

      GObject
       +----GdkGC

## Description

All drawing operations in GDK take a graphics context (GC) argument. A graphics context encapsulates information about the way things are drawn, such as the foreground color or line width. By using graphics contexts, the number of arguments to each drawing call is greatly reduced, and communication overhead is minimized, since identical arguments do not need to be passed repeatedly.

Most values of a graphics context can be set at creation time by using gdk_gc_new_with_values(), or can be set one-by-one using functions such as gdk_gc_set_foreground(). A few of the values in the GC, such as the dash pattern, can only be set by the latter method.

## Details

### struct GdkGC

    struct GdkGC;

The GdkGC structure represents a graphics context. It is an opaque structure with no user-visible elements.

### struct 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 GdkGCValues structure holds a set of values used to create or modify a graphics context.

GdkColor `foreground` | the foreground color.
GdkColor `background` | the background color.
GdkFont *`font` | the default font.
GdkFunction `function` | the bitwise operation used when drawing.
GdkFill `fill` | the fill style.
GdkPixmap *`tile` | the tile pixmap.
GdkPixmap *`stipple` | the stipple bitmap.
GdkPixmap *`clip_mask` | the clip mask bitmap.
GdkSubwindowMode `subwindow_mode` | the subwindow mode.
gint `ts_x_origin` | the x origin of the tile or stipple.
gint `ts_y_origin` | the y origin of the tile or stipple.
gint `clip_x_origin` | the x origin of the clip mask.
gint `clip_y_origin` | the y origin of the clip mask.
gint `graphics_exposures` | whether graphics exposures are enabled.
gint `line_width` | the line width.
GdkLineStyle `line_style` | the way dashed lines are drawn.
GdkCapStyle `cap_style` | the way the ends of lines are drawn.
GdkJoinStyle `join_style` | the way joins between lines are drawn.

### enum GdkGCValuesMask

    typedef enum
    {
      GDK_GC_FOREGROUND    = 1 << 0,
      GDK_GC_BACKGROUND    = 1 << 1,
      GDK_GC_FONT	       = 1 << 2,
      GDK_GC_FUNCTION      = 1 << 3,
      GDK_GC_FILL	       = 1 << 4,
      GDK_GC_TILE	       = 1 << 5,
      GDK_GC_STIPPLE       = 1 << 6,
      GDK_GC_CLIP_MASK     = 1 << 7,
      GDK_GC_SUBWINDOW     = 1 << 8,
      GDK_GC_TS_X_ORIGIN   = 1 << 9,
      GDK_GC_TS_Y_ORIGIN   = 1 << 10,
      GDK_GC_CLIP_X_ORIGIN = 1 << 11,
      GDK_GC_CLIP_Y_ORIGIN = 1 << 12,
      GDK_GC_EXPOSURES     = 1 << 13,
      GDK_GC_LINE_WIDTH    = 1 << 14,
      GDK_GC_LINE_STYLE    = 1 << 15,
      GDK_GC_CAP_STYLE     = 1 << 16,
      GDK_GC_JOIN_STYLE    = 1 << 17
    } GdkGCValuesMask;

A set of bit flags used to indicate which fields GdkGCValues structure are set.

`GDK_GC_FOREGROUND` | the `foreground` is set.
`GDK_GC_BACKGROUND` | the `background` is set.
`GDK_GC_FONT` | the `font` is set.
`GDK_GC_FUNCTION` | the `function` is set.
`GDK_GC_FILL` | the `fill` is set.
`GDK_GC_TILE` | the `tile` is set.
`GDK_GC_STIPPLE` | the `stipple` is set.
`GDK_GC_CLIP_MASK` | the `clip_mask` is set.
`GDK_GC_SUBWINDOW` | the `subwindow_mode` is set.
`GDK_GC_TS_X_ORIGIN` | the `ts_x_origin` is set.
`GDK_GC_TS_Y_ORIGIN` | the `ts_y_origin` is set.
`GDK_GC_CLIP_X_ORIGIN` | the `clip_x_origin` is set.
`GDK_GC_CLIP_Y_ORIGIN` | the `clip_y_origin` is set.
`GDK_GC_EXPOSURES` | the `graphics_exposures` is set.
`GDK_GC_LINE_WIDTH` | the `line_width` is set.
`GDK_GC_LINE_STYLE` | the `line_style` is set.
`GDK_GC_CAP_STYLE` | the `cap_style` is set.
`GDK_GC_JOIN_STYLE` | the `join_style` is set.

### enum GdkFunction

    typedef enum
    {
      GDK_COPY,
      GDK_INVERT,
      GDK_XOR,
      GDK_CLEAR,
      GDK_AND,
      GDK_AND_REVERSE,
      GDK_AND_INVERT,
      GDK_NOOP,
      GDK_OR,
      GDK_EQUIV,
      GDK_OR_REVERSE,
      GDK_COPY_INVERT,
      GDK_OR_INVERT,
      GDK_NAND,
      GDK_NOR,
      GDK_SET
    } GdkFunction;

Determines 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 `GDK_COPY`, `GDK_XOR` and `GDK_INVERT` are generally useful. For bitmaps, `GDK_AND` and `GDK_OR` are also useful.

### gdk_gc_new ()

    GdkGC*      gdk_gc_new                      (GdkDrawable *drawable);

Create a new graphics context with default values.

`drawable` : | a GdkDrawable. The created GC must always be used with drawables of the same depth as this one.
Returns : | the new graphics context.

### gdk_gc_new_with_values ()

    GdkGC*      gdk_gc_new_with_values          (GdkDrawable *drawable,
                                                 GdkGCValues *values,
                                                 GdkGCValuesMask values_mask);

Create a new GC with the given initial values.

`drawable` : | a GdkDrawable. The created GC must always be used with drawables of the same depth as this one.
`values` : | a structure containing initial values for the GC.
`values_mask` : | a bit mask indicating which fields in `values` are set.
Returns : | the new graphics context.

### gdk_gc_get_screen ()

    GdkScreen*  gdk_gc_get_screen               (GdkGC *gc);

Gets the GdkScreen for which `gc` was created

`gc` : | a GdkGC.
Returns : | the GdkScreen for `gc`.

### gdk_gc_ref ()

    GdkGC*      gdk_gc_ref                      (GdkGC *gc);

Warning
`gdk_gc_ref` is deprecated and should not be used in newly-written code.

Deprecated function; use g_object_ref() instead.

`gc` : | a GdkGC
Returns : | the gc.

### gdk_gc_unref ()

    void        gdk_gc_unref                    (GdkGC *gc);

Warning
`gdk_gc_unref` is deprecated and should not be used in newly-written code.

Deprecated function; use g_object_unref() instead.

`gc` : | a GdkGC

### gdk_gc_destroy

    #define gdk_gc_destroy                 gdk_gc_unref

Warning
`gdk_gc_destroy` is deprecated and should not be used in newly-written code.

Identical to gdk_gc_unref(). This function is obsolete and should not be used.

### gdk_gc_set_values ()

    void        gdk_gc_set_values               (GdkGC *gc,
                                                 GdkGCValues *values,
                                                 GdkGCValuesMask values_mask);

Sets attributes of a graphics context in bulk. For each flag set in `values_mask`, the corresponding field will be read from `values` and set as the new value for `gc`. If you're only setting a few values on `gc`, calling individual "setter" functions is likely more convenient.

`gc` : | a GdkGC
`values` : | struct containing the new values
`values_mask` : | mask indicating which struct fields are to be used

### gdk_gc_get_values ()

    void        gdk_gc_get_values               (GdkGC *gc,
                                                 GdkGCValues *values);

Retrieves the current values from a graphics context.

`gc` : | a GdkGC.
`values` : | the GdkGCValues structure in which to store the results.

### gdk_gc_set_foreground ()

    void        gdk_gc_set_foreground           (GdkGC *gc,
                                                 GdkColor *color);

Sets the foreground color for a graphics context.

`gc` : | a GdkGC.
`color` : | the new foreground color.

### gdk_gc_set_background ()

    void        gdk_gc_set_background           (GdkGC *gc,
                                                 GdkColor *color);

Sets the background color for a graphics context.

`gc` : | a GdkGC.
`color` : | the new background color.

### gdk_gc_set_rgb_fg_color ()

    void        gdk_gc_set_rgb_fg_color         (GdkGC *gc,
                                                 GdkColor *color);

Set the foreground color of a GC using an unallocated color. The pixel value for the color will be determined using GdkRGB. If the colormap for the GC has not previously been initialized for GdkRGB, then for pseudo-color colormaps (colormaps with a small modifiable number of colors), a colorcube will be allocated in the colormap.

Calling this function for a GC without a colormap is an error.

`gc` : | a GdkGC
`color` : | an unallocated GdkColor.

### gdk_gc_set_rgb_bg_color ()

    void        gdk_gc_set_rgb_bg_color         (GdkGC *gc,
                                                 GdkColor *color);

Set the background color of a GC using an unallocated color. The pixel value for the color will be determined using GdkRGB. If the colormap for the GC has not previously been initialized for GdkRGB, then for pseudo-color colormaps (colormaps with a small modifiable number of colors), a colorcube will be allocated in the colormap.

Calling this function for a GC without a colormap is an error.

`gc` : | a GdkGC
`color` : | an unallocated GdkColor.

### gdk_gc_set_font ()

    void        gdk_gc_set_font                 (GdkGC *gc,
                                                 GdkFont *font);

Warning
`gdk_gc_set_font` is deprecated and should not be used in newly-written code.

Sets the font for a graphics context. (Note that all text-drawing functions in GDK take a `font` argument; the value set here is used when that argument is `NULL`.)

`gc` : | a GdkGC.
`font` : | the new font.

### gdk_gc_set_function ()

    void        gdk_gc_set_function             (GdkGC *gc,
                                                 GdkFunction function);

Determines how the current pixel values and the pixel values being drawn are combined to produce the final pixel values.

`gc` : | a GdkGC.
`function` : |

### gdk_gc_set_fill ()

    void        gdk_gc_set_fill                 (GdkGC *gc,
                                                 GdkFill fill);

Set the fill mode for a graphics context.

`gc` : | a GdkGC.
`fill` : | the new fill mode.

### enum GdkFill

    typedef enum
    {
      GDK_SOLID,
      GDK_TILED,
      GDK_STIPPLED,
      GDK_OPAQUE_STIPPLED
    } GdkFill;

Determines how primitives are drawn.

`GDK_SOLID` | draw with the foreground color.
`GDK_TILED` | draw with a tiled pixmap.
`GDK_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.
`GDK_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.

### gdk_gc_set_tile ()

    void        gdk_gc_set_tile                 (GdkGC *gc,
                                                 GdkPixmap *tile);

Set a tile pixmap for a graphics context. This will only be used if the fill mode is `GDK_TILED`.

`gc` : | a GdkGC.
`tile` : | the new tile pixmap.

### gdk_gc_set_stipple ()

    void        gdk_gc_set_stipple              (GdkGC *gc,
                                                 GdkPixmap *stipple);

Set the stipple bitmap for a graphics context. The stipple will only be used if the fill mode is `GDK_STIPPLED` or `GDK_OPAQUE_STIPPLED`.

`gc` : | a GdkGC.
`stipple` : | the new stipple bitmap.

### gdk_gc_set_ts_origin ()

    void        gdk_gc_set_ts_origin            (GdkGC *gc,
                                                 gint x,
                                                 gint y);

Set the origin when using tiles or stipples with the GC. The tile or stipple will be aligned such that the upper left corner of the tile or stipple will coincide with this point.

`gc` : | a GdkGC.
`x` : | the x-coordinate of the origin.
`y` : | the y-coordinate of the origin.

### gdk_gc_set_clip_origin ()

    void        gdk_gc_set_clip_origin          (GdkGC *gc,
                                                 gint x,
                                                 gint y);

Sets the origin of the clip mask. The coordinates are interpreted relative to the upper-left corner of the destination drawable of the current operation.

`gc` : | a GdkGC.
`x` : | the x-coordinate of the origin.
`y` : | the y-coordinate of the origin.

### gdk_gc_set_clip_mask ()

    void        gdk_gc_set_clip_mask            (GdkGC *gc,
                                                 GdkBitmap *mask);

Sets the clip mask for a graphics context from a bitmap. The clip mask is interpreted relative to the clip origin. (See gdk_gc_set_clip_origin()).

`gc` : | the GdkGC.
`mask` : | a bitmap.

### gdk_gc_set_clip_rectangle ()

    void        gdk_gc_set_clip_rectangle       (GdkGC *gc,
                                                 GdkRectangle *rectangle);

Sets the clip mask for a graphics context from a rectangle. The clip mask is interpreted relative to the clip origin. (See gdk_gc_set_clip_origin()).

`gc` : | a GdkGC.
`rectangle` : | the rectangle to clip to.

### gdk_gc_set_clip_region ()

    void        gdk_gc_set_clip_region          (GdkGC *gc,
                                                 GdkRegion *region);

Sets the clip mask for a graphics context from a region structure. The clip mask is interpreted relative to the clip origin. (See gdk_gc_set_clip_origin()).

`gc` : | a GdkGC.
`region` : | the GdkRegion.

### gdk_gc_set_subwindow ()

    void        gdk_gc_set_subwindow            (GdkGC *gc,
                                                 GdkSubwindowMode mode);

Sets how drawing with this GC on a window will affect child windows of that window.

`gc` : | a GdkGC.
`mode` : | the subwindow mode.

### enum GdkSubwindowMode

    typedef enum
    {
      GDK_CLIP_BY_CHILDREN	= 0,
      GDK_INCLUDE_INFERIORS = 1
    } GdkSubwindowMode;

Determines how drawing onto a window will affect child windows of that window.

`GDK_CLIP_BY_CHILDREN` | only draw onto the window itself.
`GDK_INCLUDE_INFERIORS` | draw onto the window and child windows.

### gdk_gc_set_exposures ()

    void        gdk_gc_set_exposures            (GdkGC *gc,
                                                 gboolean exposures);

Sets whether copying non-visible portions of a drawable using this graphics context generate exposure events for the corresponding regions of the destination drawable. (See gdk_draw_drawable()).

`gc` : | a GdkGC.
`exposures` : | if `TRUE`, exposure events will be generated.

### gdk_gc_set_line_attributes ()

    void        gdk_gc_set_line_attributes      (GdkGC *gc,
                                                 gint line_width,
                                                 GdkLineStyle line_style,
                                                 GdkCapStyle cap_style,
                                                 GdkJoinStyle join_style);

Sets various attributes of how lines are drawn. See the corresponding members of GdkGCValues for full explanations of the arguments.

`gc` : | a GdkGC.
`line_width` : | the width of lines.
`line_style` : | the dash-style for lines.
`cap_style` : | the manner in which the ends of lines are drawn.
`join_style` : | the in which lines are joined together.

### enum GdkLineStyle

    typedef enum
    {
      GDK_LINE_SOLID,
      GDK_LINE_ON_OFF_DASH,
      GDK_LINE_DOUBLE_DASH
    } GdkLineStyle;

Determines how lines are drawn.

`GDK_LINE_SOLID` | lines are drawn solid.
`GDK_LINE_ON_OFF_DASH` | even segments are drawn; odd segments are not drawn.
`GDK_LINE_DOUBLE_DASH` | even segments are normally. Odd segments are drawn in the background color if the fill style is `GDK_SOLID`, or in the background color masked by the stipple if the fill style is `GDK_STIPPLED`.

### enum GdkCapStyle

    typedef enum
    {
      GDK_CAP_NOT_LAST,
      GDK_CAP_BUTT,
      GDK_CAP_ROUND,
      GDK_CAP_PROJECTING
    } GdkCapStyle;

Determines how the end of lines are drawn.

`GDK_CAP_NOT_LAST` | the same as `GDK_CAP_BUTT` for lines of non-zero width. for zero width lines, the final point on the line will not be drawn.
`GDK_CAP_BUTT` | the ends of the lines are drawn squared off and extending to the coordinates of the end point.
`GDK_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.
`GDK_CAP_PROJECTING` | the ends of the lines are drawn squared off and extending half the width of the line beyond the end point.

### enum GdkJoinStyle

    typedef enum
    {
      GDK_JOIN_MITER,
      GDK_JOIN_ROUND,
      GDK_JOIN_BEVEL
    } GdkJoinStyle;

Determines how the joins between segments of a polygon are drawn.

`GDK_JOIN_MITER` | the sides of each line are extended to meet at an angle.
`GDK_JOIN_ROUND` | the sides of the two lines are joined by a circular arc.
`GDK_JOIN_BEVEL` | the sides of the two lines are joined by a straight line which makes an equal angle with each line.

### gdk_gc_set_dashes ()

    void        gdk_gc_set_dashes               (GdkGC *gc,
                                                 gint dash_offset,
                                                 gint8 dash_list[],
                                                 gint n);

Sets the way dashed-lines are drawn. Lines will be drawn with alternating on and off segments of the lengths specified in `dash_list`. The manner in which the on and off segments are drawn is determined by the `line_style` value of the GC. (This can be changed with gdk_gc_set_line_attributes())

`gc` : | a GdkGC.
`dash_offset` : | the
`dash_list` : | an array of dash lengths.
`n` : | the number of elements in `dash_list`.

### gdk_gc_copy ()

    void        gdk_gc_copy                     (GdkGC *dst_gc,
                                                 GdkGC *src_gc);

Copy the set of values from one graphics context onto another graphics context.

`dst_gc` : | the destination graphics context.
`src_gc` : | the source graphics context.

### gdk_gc_set_colormap ()

    void        gdk_gc_set_colormap             (GdkGC *gc,
                                                 GdkColormap *colormap);

Sets the colormap for the GC to the given colormap. The depth of the colormap's visual must match the depth of the drawable for which the GC was created.

`gc` : | a GdkGC
`colormap` : | a GdkColormap

### gdk_gc_get_colormap ()

    GdkColormap* gdk_gc_get_colormap            (GdkGC *gc);

Retrieves the colormap for a given GC, if it exists. A GC will have a colormap if the drawable for which it was created has a colormap, or if a colormap was set explicitely with gdk_gc_set_colormap.

`gc` : | a GdkGC
Returns : |

### gdk_gc_offset ()

    void        gdk_gc_offset                   (GdkGC *gc,
                                                 gint x_offset,
                                                 gint y_offset);

Offset attributes such as the clip and tile-stipple origins of the GC so that drawing at x - x_offset, y - y_offset with the offset GC has the same effect as drawing at x, y with the original GC.

`gc` : | a GdkGC
`x_offset` : | amount by which to offset the GC in the X direction
`y_offset` : | amount by which to offset the GC in the Y direction

<<< Previous Page | Home | Up | Next Page >>>
Points, Rectangles and Regions | Drawing Primitives