Graphics Contexts: GDK 2 Reference Manual

## Graphics Contexts Graphics Contexts |

## Functions

GdkGC * | gdk_gc_new ()
GdkGC * | gdk_gc_new_with_values ()
GdkScreen * | gdk_gc_get_screen ()
GdkGC * | gdk_gc_ref ()
void | gdk_gc_unref ()
void | gdk_gc_set_values ()
void | gdk_gc_get_values ()
void | gdk_gc_set_foreground ()
void | gdk_gc_set_background ()
void | gdk_gc_set_rgb_fg_color ()
void | gdk_gc_set_rgb_bg_color ()
void | gdk_gc_set_font ()
void | gdk_gc_set_function ()
void | gdk_gc_set_fill ()
void | gdk_gc_set_tile ()
void | gdk_gc_set_stipple ()
void | gdk_gc_set_ts_origin ()
void | gdk_gc_set_clip_origin ()
void | gdk_gc_set_clip_mask ()
void | gdk_gc_set_clip_rectangle ()
void | gdk_gc_set_clip_region ()
void | gdk_gc_set_subwindow ()
void | gdk_gc_set_exposures ()
void | gdk_gc_set_line_attributes ()
void | gdk_gc_set_dashes ()
void | gdk_gc_copy ()
void | gdk_gc_set_colormap ()
GdkColormap * | gdk_gc_get_colormap ()
void | gdk_gc_offset ()

## Types and Values

| GdkGC
struct | GdkGCValues
enum | GdkGCValuesMask
enum | GdkFunction
#define | gdk_gc_destroy
enum | GdkFill
enum | GdkSubwindowMode
enum | GdkLineStyle
enum | GdkCapStyle
enum | GdkJoinStyle

## Object Hierarchy

        GObject
        ╰── GdkGC

## Includes

    #include <gdk/gdk.h>

## Description

## Functions

### gdk_gc_new ()

    GdkGC *
    gdk_gc_new (GdkDrawable *drawable);

`gdk_gc_new` has been deprecated since version 2.22 and should not be used in newly-written code.

Use Cairo for rendering.

Create a new graphics context with default values.

#### Parameters

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);

`gdk_gc_new_with_values` has been deprecated since version 2.22 and should not be used in newly-written code.

Use Cairo for rendering.

Create a new GC with the given initial values.

#### Parameters

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);

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

Gets the GdkScreen for which `gc` was created

#### Parameters

gc | a GdkGC. |

#### Returns

the GdkScreen for `gc` .

Since: 2.2

### gdk_gc_ref ()

    GdkGC *
    gdk_gc_ref (GdkGC *gc);

`gdk_gc_ref` has been deprecated since version 2.0 and should not be used in newly-written code.

Use `g_object_ref()` instead.

Deprecated function; use `g_object_ref()` instead.

#### Parameters

gc | a GdkGC |

#### Returns

the gc.

### gdk_gc_unref ()

    void
    gdk_gc_unref (GdkGC *gc);

`gdk_gc_unref` has been deprecated since version 2.0 and should not be used in newly-written code.

Use `g_object_unref()` instead.

Decrement the reference count of `gc` .

#### Parameters

gc | a GdkGC |

### gdk_gc_set_values ()

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

`gdk_gc_set_values` has been deprecated since version 2.22 and should not be used in newly-written code.

Use Cairo for rendering.

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.

#### Parameters

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);

`gdk_gc_get_values` has been deprecated since version 2.22 and should not be used in newly-written code.

Use Cairo for rendering.

Retrieves the current values from a graphics context. Note that only the pixel values of the `values->foreground` and `values->background` are filled, use `gdk_colormap_query_color()` to obtain the rgb values if you need them.

#### Parameters

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

### gdk_gc_set_foreground ()

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

`gdk_gc_set_foreground` has been deprecated since version 2.22 and should not be used in newly-written code.

Use `gdk_cairo_set_source_color()` to use a GdkColor as the source in Cairo.

Sets the foreground color for a graphics context. Note that this function uses `color->pixel` , use `gdk_gc_set_rgb_fg_color()` to specify the foreground color as red, green, blue components.

#### Parameters

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

### gdk_gc_set_background ()

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

`gdk_gc_set_background` has been deprecated since version 2.22 and should not be used in newly-written code.

Use `gdk_cairo_set_source_color()` to use a GdkColor as the source in Cairo. Note that if you want to draw a background and a foreground in Cairo, you need to call drawing functions (like `cairo_fill()`) twice.

Sets the background color for a graphics context. Note that this function uses `color->pixel` , use `gdk_gc_set_rgb_bg_color()` to specify the background color as red, green, blue components.

#### Parameters

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

### gdk_gc_set_rgb_fg_color ()

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

`gdk_gc_set_rgb_fg_color` has been deprecated since version 2.22 and should not be used in newly-written code.

Use `gdk_cairo_set_source_color()` instead.

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.

#### Parameters

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

### gdk_gc_set_rgb_bg_color ()

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

`gdk_gc_set_rgb_bg_color` has been deprecated since version 2.22 and should not be used in newly-written code.

Use `gdk_cairo_set_source_color()` instead.

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.

#### Parameters

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

### gdk_gc_set_font ()

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

`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`.)

#### Parameters

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

### gdk_gc_set_function ()

    void
    gdk_gc_set_function (GdkGC *gc,
                         GdkFunction function);

`gdk_gc_set_function` has been deprecated since version 2.22 and should not be used in newly-written code.

Use `cairo_set_operator()` with Cairo.

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

#### Parameters

gc | a GdkGC. |
function | the GdkFunction to use |

### gdk_gc_set_fill ()

    void
    gdk_gc_set_fill (GdkGC *gc,
                     GdkFill fill);

`gdk_gc_set_fill` has been deprecated since version 2.22 and should not be used in newly-written code.

You can achieve tiling in Cairo by using `cairo_pattern_set_extend()` on the source. For stippling, see the deprecation comments on `gdk_gc_set_stipple()`.

Set the fill mode for a graphics context.

#### Parameters

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

### gdk_gc_set_tile ()

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

`gdk_gc_set_tile` has been deprecated since version 2.22 and should not be used in newly-written code.

The following code snippet sets a tiling GdkPixmap as the source in Cairo:

    1
    cairo_pattern_set_extend (cairo_get_source (cr), CAIRO_EXTEND_REPEAT);]|

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

#### Parameters

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

### gdk_gc_set_stipple ()

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

`gdk_gc_set_stipple` has been deprecated since version 2.22 and should not be used in newly-written code.

Stippling has no direct replacement in Cairo. If you want to achieve an identical look, you can use the stipple bitmap as a mask. Most likely, this involves rendering the source to an intermediate surface using `cairo_push_group()` first, so that you can then use `cairo_mask()` to achieve the stippled look.

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

#### Parameters

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);

`gdk_gc_set_ts_origin` has been deprecated since version 2.22 and should not be used in newly-written code.

You can set the origin for tiles and stipples in Cairo by changing the source's matrix using `cairo_pattern_set_matrix()`. Or you can specify it with `gdk_cairo_set_source_pixmap()` as shown in the example for `gdk_gc_set_tile()`.

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.

#### Parameters

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);

`gdk_gc_set_clip_origin` has been deprecated since version 2.22 and should not be used in newly-written code.

Use `cairo_translate()` before applying the clip path in Cairo.

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.

#### Parameters

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);

`gdk_gc_set_clip_mask` has been deprecated since version 2.22 and should not be used in newly-written code.

Use `cairo_mask()` instead.

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()`).

#### Parameters

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

### gdk_gc_set_clip_rectangle ()

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

`gdk_gc_set_clip_rectangle` has been deprecated since version 2.22 and should not be used in newly-written code.

Use `cairo_rectangle()` and `cairo_clip()` in Cairo.

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()`).

#### Parameters

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

### gdk_gc_set_clip_region ()

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

`gdk_gc_set_clip_region` has been deprecated since version 2.22 and should not be used in newly-written code.

Use `gdk_cairo_region()` and `cairo_clip()` in Cairo.

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()`).

#### Parameters

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

### gdk_gc_set_subwindow ()

    void
    gdk_gc_set_subwindow (GdkGC *gc,
                          GdkSubwindowMode mode);

`gdk_gc_set_subwindow` has been deprecated since version 2.22 and should not be used in newly-written code.

There is no replacement. If you need to control subwindows, you must use drawing operations of the underlying window system manually. Cairo will always use `GDK_INCLUDE_INFERIORS` on sources and masks and `GDK_CLIP_BY_CHILDREN` on targets.

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

#### Parameters

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

### gdk_gc_set_exposures ()

    void
    gdk_gc_set_exposures (GdkGC *gc,
                          gboolean exposures);

`gdk_gc_set_exposures` has been deprecated since version 2.22 and should not be used in newly-written code.

There is no replacement. If you need to control exposures, you must use drawing operations of the underlying window system or use `gdk_window_invalidate_rect()`. Cairo will never generate 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()`).

#### Parameters

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);

`gdk_gc_set_line_attributes` has been deprecated since version 2.22 and should not be used in newly-written code.

Use the Cairo functions `cairo_set_line_width()`, `cairo_set_line_join()`, `cairo_set_line_cap()` and `cairo_set_dash()` to affect the stroking behavior in Cairo. Keep in mind that the default attributes of a cairo_t are different from the default attributes of a GdkGC.

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

#### Parameters

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

### gdk_gc_set_dashes ()

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

`gdk_gc_set_dashes` has been deprecated since version 2.22 and should not be used in newly-written code.

Use `cairo_set_dash()` to set the dash in Cairo.

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()`.)

The `dash_offset` defines the phase of the pattern, specifying how many pixels into the dash-list the pattern should actually begin.

#### Parameters

gc | a GdkGC. |
dash_offset | the phase of the dash pattern. |
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);

`gdk_gc_copy` has been deprecated since version 2.22 and should not be used in newly-written code.

Use Cairo for drawing. `cairo_save()` and `cairo_restore()` can be helpful in cases where you'd have copied a GdkGC.

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

#### Parameters

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);

`gdk_gc_set_colormap` has been deprecated since version 2.22 and should not be used in newly-written code.

There is no replacement. Cairo handles colormaps automatically, so there is no need to care about them.

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.

#### Parameters

gc | a GdkGC |
colormap | a GdkColormap |

### gdk_gc_get_colormap ()

    GdkColormap *
    gdk_gc_get_colormap (GdkGC *gc);

`gdk_gc_get_colormap` has been deprecated since version 2.22 and should not be used in newly-written code.

There is no replacement. Cairo handles colormaps automatically, so there is no need to care about them.

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.

#### Parameters

gc | a GdkGC |

#### Returns

the colormap of `gc` , or `NULL` if `gc` doesn't have one.

### gdk_gc_offset ()

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

`gdk_gc_offset` has been deprecated since version 2.22 and should not be used in newly-written code.

There is no direct replacement, as this is just a convenience function for gdk_gc_set_ts_origin and `gdk_gc_set_clip_origin()`.

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.

#### Parameters

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 |

## Types and Values

### GdkGC

    typedef struct _GdkGC GdkGC;

### 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;
    };

### enum GdkGCValuesMask

#### Members

GDK_GC_FOREGROUND |  |
GDK_GC_BACKGROUND |  |
GDK_GC_FONT |  |
GDK_GC_FUNCTION |  |
GDK_GC_FILL |  |
GDK_GC_TILE |  |
GDK_GC_STIPPLE |  |
GDK_GC_CLIP_MASK |  |
GDK_GC_SUBWINDOW |  |
GDK_GC_TS_X_ORIGIN |  |
GDK_GC_TS_Y_ORIGIN |  |
GDK_GC_CLIP_X_ORIGIN |  |
GDK_GC_CLIP_Y_ORIGIN |  |
GDK_GC_EXPOSURES |  |
GDK_GC_LINE_WIDTH |  |
GDK_GC_LINE_STYLE |  |
GDK_GC_CAP_STYLE |  |
GDK_GC_JOIN_STYLE |  |

### enum GdkFunction

#### Members

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

### gdk_gc_destroy

    #define gdk_gc_destroy                 g_object_unref

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

### enum GdkFill

#### Members

GDK_SOLID |  |
GDK_TILED |  |
GDK_STIPPLED |  |
GDK_OPAQUE_STIPPLED |  |

### enum GdkSubwindowMode

#### Members

GDK_CLIP_BY_CHILDREN |  |
GDK_INCLUDE_INFERIORS |  |

### enum GdkLineStyle

#### Members

GDK_LINE_SOLID |  |
GDK_LINE_ON_OFF_DASH |  |
GDK_LINE_DOUBLE_DASH |  |

### enum GdkCapStyle

#### Members

GDK_CAP_NOT_LAST |  |
GDK_CAP_BUTT |  |
GDK_CAP_ROUND |  |
GDK_CAP_PROJECTING |  |

### enum GdkJoinStyle

#### Members

GDK_JOIN_MITER |  |
GDK_JOIN_ROUND |  |
GDK_JOIN_BEVEL |  |