gtk.gdk.GC
Prev | The gtk.gdk Class Reference | Next

## gtk.gdk.GC

gtk.gdk.GC — objects to encapsulate drawing properties.

## Synopsis

    class gtk.gdk.GC(gobject.GObject):
        gtk.gdk.GC(drawable, foreground, background, font, function, fill, tile, stipple, clip_mask, subwindow_mode, ts_x_origin, ts_y_origin, clip_x_origin, clip_y_origin, graphics_exposures, line_width, line_style, cap_style, join_style>)
        def set_values(foreground, background, font, function, fill, tile, stipple, clip_mask, subwindow_mode, ts_x_origin, ts_y_origin, clip_x_origin, clip_y_origin, graphics_exposures, line_width, line_style, cap_style, join_style>)
        def set_foreground(color)
        def set_background(color)
        def set_function(function)
        def set_fill(fill)
        def set_tile(tile)
        def set_stipple(stipple)
        def set_ts_origin(x, y)
        def set_clip_origin(x, y)
        def set_clip_mask(mask)
        def set_clip_rectangle(rectangle)
        def set_clip_region(region)
        def set_subwindow(mode)
        def set_exposures(exposures)
        def set_line_attributes(line_width, line_style, cap_style, join_style)
        def set_dashes(dash_offset, dash_list)
        def offset(x_offset, y_offset)
        def copy(src_gc)
        def set_colormap(colormap)
        def get_colormap()
        def set_rgb_fg_color(color)
        def set_rgb_bg_color(color)
        def get_screen()

## Ancestry

    +-- gobject.GObject
      +-- gtk.gdk.GC

## Attributes

"background" | Read-Write | The background `gtk.gdk.Color`.
"cap_style" | Read-Write | The style of drawing the ends of lines - one of: `gtk.gdk.CAP_NOT_LAST`, `gtk.gdk.CAP_BUTT`, `gtk.gdk.CAP_ROUND` or `gtk.gdk.CAP_PROJECTING`.
"clip_mask" | Read-Write | A `gtk.gdk.Pixmap` bitmap used to clip the drawing operation.
"clip_x_origin" | Read-Write | The x origin of the clip mask.
"clip_y_origin" | Read-Write | The y origin of the clip mask.
"fill" | Read-Write | The fill style - one of: `gtk.gdk.SOLID`, `gtk.gdk.TILED`, `gtk.gdk.STIPPLED` or `gtk.gdk.OPAQUE_STIPPLED`.
"font" | Read-Write | The default font (deprecated and unused)
"foreground" | Read-Write | The foreground `gtk.gdk.Color`.
"function" | Read-Write | A bitwise operation type to combine source and destination pixels - one of: `gtk.gdk.COPY`, `gtk.gdk.INVERT`, `gtk.gdk.XOR`, `gtk.gdk.CLEAR`, `gtk.gdk.AND`, `gtk.gdk.AND_REVERSE`, `gtk.gdk.AND_INVERT`, `gtk.gdk.NOOP`, `gtk.gdk.OR`, `gtk.gdk.EQUIV`, `gtk.gdk.OR_REVERSE`, `gtk.gdk.COPY_INVERT`, `gtk.gdk.OR_INVERT`, `gtk.gdk.NAND`, `gtk.gdk.NOR` or `gtk.gdk.SET`.
"graphics_exposures" | Read-Write | If `True` graphics exposures are enabled.
"join_style" | Read-Write | The style used to join lines - one of: `gtk.gdk.JOIN_MITER`, `gtk.gdk.JOIN_ROUND` or `gtk.gdk.JOIN_BEVEL`.
"line_style" | Read-Write | The style of drawing lines - one of: `gtk.gdk.LINE_SOLID`, `gtk.gdk.LINE_ON_OFF_DASH` or `gtk.gdk.LINE_DOUBLE_DASH`.
"line_width" | Read-Write | The width of a line in pixels.
"stipple" | Read-Write | The `gtk.gdk.Pixmap` bitmap used to stipple the background.
"sub_window" | Read-Write | The mode of drawing in a `gtk.gdk.Window` with subwindows - one of: `gtk.gdk.CLIP_BY_CHILDREN` or `gtk.gdk.INCLUDE_INFERIORS`.
"tile" | Read-Write | The `gtk.gdk.Pixmap` used to tile the background.
"ts_x_origin" | Read-Write | The x origin of the tile or stipple.
"ts_y_origin" | Read-Write | The y origin of the tile or stipple.

## Description

All drawing operations in `PyGTK` take a graphics context (`gtk.gdk.GC`) argument (See the `gtk.gdk.Drawable` description). 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 `gtk.gdk.Drawable.new_gc`(), or can be set one-by-one using functions such as `set_foreground`() or by setting a `gtk.gdk.GC` attribute. A few of the values in the `gtk.gdk.GC`, such as the dash pattern, can only be set by the latter method.

Note that all coordinates except for clip mask and clip region are relative to destination drawable (e.g. gtk.gdk.Window) origin. In particular, coordinates are not related to widget allocation.

## Constructor

        gtk.gdk.GC(drawable, foreground, background, font, function, fill, tile, stipple, clip_mask, subwindow_mode, ts_x_origin, ts_y_origin, clip_x_origin, clip_y_origin, graphics_exposures, line_width, line_style, cap_style, join_style>)

`drawable` : | A `gtk.gdk.Drawable` (`gtk.gdk.Window` or `gtk.gdk.Pixmap`)
`foreground` : | the foreground `gtk.gdk.Color`
`background` : | the background `gtk.gdk.Color`
`font` : | a font (deprecated and ignored)
`function` : | the bitwise operator used to combine the existing pixel value and a new pixel value - usually one of: `gtk.gdk.COPY`, `gtk.gdk.XOR` or `gtk.gdk.INVERT`.
`fill` : | the fill style - one of: `gtk.gdk.SOLID`, `gtk.gdk.TILED`, `gtk.gdk.STIPPLED`, `gtk.gdk.OPAQUE_STIPPLED`
`tile` : | a `gtk.gdk.Pixmap` used for tiling the background
`stipple` : | a `gtk.gdk.Pixmap` used for stippling the background
`clip_mask` : | a `gtk.gdk.Pixmap` of depth 1 used to mask pixels to be drawn
`subwindow_mode` : | the mode of drawing on subwindows in a `gtk.gdk.Window` - one of: `gtk.gdk.CLIP_BY_CHILDREN` or `gtk.gdk.INCLUDE_INFERIORS`
`ts_x_origin` : | the X coordinate of the origin of `tile` or `stipple`
`ts_y_origin` : | the Y coordinate of the origin of `tile` or `stipple`
`clip_x_origin` : | the X coordinate of the origin of `clip_mask`
`clip_y_origin` : | the Y coordinate of the origin of `clip_mask`
`graphics_exposures` : | if `True` graphics exposures are enabled for calls to the `gtk.gdk.Drawable.draw_drawable`() method.
`line_width` : | the line width in pixels
`line_style` : | the line style - one of: `gtk.gdk.LINE_SOLID`, `gtk.gdk.LINE_ON_OFF_DASH`, `gtk.gdk.LINE_DOUBLE_DASH`
`cap_style` : | the style of line ends - one of: `gtk.gdk.CAP_NOT_LAST`, `gtk.gdk.CAP_BUTT`, `gtk.gdk.CAP_ROUND`, `gtk.gdk.CAP_PROJECTING`
`join_style` : | the style of line joins - one of: `gtk.gdk.JOIN_MITER`, `gtk.gdk.JOIN_ROUND`, `gtk.gdk.JOIN_BEVEL`
Returns : | a new `gtk.gdk.GC` object

Creates a new `gtk.gdk.GC` object for the `gtk.gdk.Drawable` specified by `drawable` with the optional attributes as specified by the arguments. The drawable parameter must be specified but the rest of the parameters are optional. Any attributes not specified will use a default value. This is an alternative to the `gtk.gdk.Drawable.new_gc`() method. Since there are a large number of optional attribute parameters it's probably best to specify the attribute values using keywords.

## Methods

### gtk.gdk.GC.set_values

        def set_values(values, foreground, background, font, function, fill, tile, stipple, clip_mask, subwindow_mode, ts_x_origin, ts_y_origin, clip_x_origin, clip_y_origin, graphics_exposures, line_width, line_style, cap_style, join_style>)

`foreground` : | the foreground `gtk.gdk.Color`
`background` : | the background `gtk.gdk.Color`
`font` : | a font (deprecated and ignored)
`function` : | the bitwise operator used to combine the existing pixel value and a new pixel value - usually one of: `gtk.gdk.COPY`, `gtk.gdk.XOR` or `gtk.gdk.INVERT`.
`fill` : | the fill style - one of: `gtk.gdk.SOLID`, `gtk.gdk.TILED`, `gtk.gdk.STIPPLED`, `gtk.gdk.OPAQUE_STIPPLED`
`tile` : | a `gtk.gdk.Pixmap` used for tiling the background
`stipple` : | a `gtk.gdk.Pixmap` used for stippling the background
`clip_mask` : | a `gtk.gdk.Pixmap` of depth 1 used to mask pixels to be drawn
`subwindow_mode` : | the mode of drawing on subwindows in a `gtk.gdk.Window` - one of: `gtk.gdk.CLIP_BY_CHILDREN` or `gtk.gdk.INCLUDE_INFERIORS`
`ts_x_origin` : | the X coordinate of the origin of `tile` or `stipple`
`ts_y_origin` : | the Y coordinate of the origin of `tile` or `stipple`
`clip_x_origin` : | the X coordinate of the origin of `clip_mask`
`clip_y_origin` : | the Y coordinate of the origin of `clip_mask`
`graphics_exposures` : | if `True` graphics exposures are enabled for calls to the `gtk.gdk.Drawable.draw_drawable`() method.
`line_width` : | the line width in pixels
`line_style` : | the line style - one of: `gtk.gdk.LINE_SOLID`, `gtk.gdk.LINE_ON_OFF_DASH`, `gtk.gdk.LINE_DOUBLE_DASH`
`cap_style` : | the style of line ends - one of: `gtk.gdk.CAP_NOT_LAST`, `gtk.gdk.CAP_BUTT`, `gtk.gdk.CAP_ROUND`, `gtk.gdk.CAP_PROJECTING`
`join_style` : | the style of line joins - one of: `gtk.gdk.JOIN_MITER`, `gtk.gdk.JOIN_ROUND`, `gtk.gdk.JOIN_BEVEL`

The `set_values`() method sets the attributes of a graphics context in bulk using the optional parameters. Since there are a large number of attribute parameters it's probably best to specify the attribute values using keywords. Any attributes not specified will be left as is.

### gtk.gdk.GC.set_foreground

        def set_foreground(color)

`color` : | the new foreground `gtk.gdk.Color`

The `set_foreground`() method sets the foreground `gtk.gdk.Color` to the value specified by `color`.

### gtk.gdk.GC.set_background

        def set_background(color)

`color` : | the new background `gtk.gdk.Color`

The `set_background`() method sets the background `gtk.gdk.Color` to the value specified by `color`.

### gtk.gdk.GC.set_function

        def set_function(function)

`function` : | the bitwise operator used to combine the existing pixel value and a new pixel value - usually one of: `gtk.gdk.COPY`, `gtk.gdk.XOR` or `gtk.gdk.INVERT`.

The `set_function`() method sets the function attribute to the value specified by `function`. The value of `function` must be one of:

- `gtk.gdk.COPY`
- `gtk.gdk.INVERT`
- `gtk.gdk.XOR`
- `gtk.gdk.CLEAR`
- `gtk.gdk.AND`
- `gtk.gdk.AND_REVERSE.`
- `gtk.gdk.AND_INVERT`
- `gtk.gdk.NOOP`
- `gtk.gdk.OR`
- `gtk.gdk.EQUIV`
- `gtk.gdk.OR_REVERSE`
- `gtk.gdk.COPY_INVERT`
- `gtk.gdk.OR_INVERT`
- `gtk.gdk.NAND`
- `gtk.gdk.NOR`
- `gtk.gdk.SET`

Only a couple of these values are usually useful. For colored images, only `gtk.gdk.COPY`, `gtk.gdk.XOR` and `gtk.gdk.INVERT` are generally useful. For bitmaps, `gtk.gdk.AND` and `gtk.gdk.OR` are also useful.

### gtk.gdk.GC.set_fill

        def set_fill(fill)

`fill` : | the new fill mode

The `set_fill`() method sets the fill mode for the graphics context to the value specified by `fill`. The value of `fill` must be one of:

`gtk.gdk.SOLID` | draw with the foreground color.
`gtk.gdk.TILED` | draw with a tiled pixmap.
`gtk.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.
`gtk.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.

### gtk.gdk.GC.set_tile

        def set_tile(tile)

`tile` : | a `gtk.gdk.Pixmap`

The `set_tile`() method sets the `gtk.gdk.Pixmap` specified by `tile` to be used for filling the background when the fill mode is `gtk.gdk.TILED`.

### gtk.gdk.GC.set_stipple

        def set_stipple(stipple)

`stipple` : | a `gtk.gdk.Pixmap` bitmap

The `set_stipple`() method sets the `gtk.gdk.Pixmap` bitmap specified by `stipple` to be used for stippling the background. `stipple` will only be used if the fill mode is `gtk.gdk.STIPPLED` or `gtk.gdk.OPAQUE_STIPPLED`.

### gtk.gdk.GC.set_ts_origin

        def set_ts_origin(x, y)

`x` : | the x origin of the tile or stipple
`y` : | the y origin of the tile or stipple

The `set_ts_origin`() method sets the origin of the tile or stipple to the value specified by `x` and `y`. The tile or stipple will be aligned such that the upper left corner of the tile or stipple will coincide with this point.

### gtk.gdk.GC.set_clip_origin

        def set_clip_origin(x, y)

`x` : | the x origin of the clip mask
`y` : | the y origin of the clip mask

The `set_clip_origin`() method sets the origin of the clip mask to the value specified by `x` and `y`. The coordinates are interpreted relative to the upper-left corner of the destination drawable of the current operation.

### gtk.gdk.GC.set_clip_mask

        def set_clip_mask(mask)

`mask` : | a `gtk.gdk.Pixmap`

The `set_clip_mask`() method sets the clip mask (a `gtk.gdk.Pixmap` bit map) to the value specified by `mask`. The clip mask is interpreted relative to the clip origin. See the `set_clip_origin`() method.

### gtk.gdk.GC.set_clip_rectangle

        def set_clip_rectangle(rectangle)

`rectangle` : | a `gtk.gdk.Rectangle` to use for clipping

The `set_clip_rectangle`() method sets the clip mask for the graphics context from the `gtk.gdk.Rectangle` specified by `rectangle` and sets the clip origin to (0, 0). The clip origin can be changed using the `set_clip_origin`() method.

### gtk.gdk.GC.set_clip_region

        def set_clip_region(region)

`region` : | a `gtk.gdk.Region`

### Note

This method is available in PyGTK 2.10 and above.

The `set_clip_region`() method sets the clip mask for a graphics context from the `gtk.gdk.Region` specified by `region`. The clip mask is interpreted relative to the clip origin. (See the `set_clip_origin`() method).

### gtk.gdk.GC.set_subwindow

        def set_subwindow(mode)

`mode` : | the new subwindow mode

The `set_subwindow`() method sets the mode of drawing on subwindows when drawing on a `gtk.gdk.Window` to the value specified by `mode`. The value of mode must be one of:

`gtk.gdk.CLIP_BY_CHILDREN` | only draw onto the window itself not the subwindows.
`gtk.gdk.INCLUDE_INFERIORS` | draw onto the window and child windows.

### gtk.gdk.GC.set_exposures

        def set_exposures(exposures)

`exposures` : | if `True` exposure events will be generated for non-visible areas

The `set_exposures`() method sets an attribute that determines if copying non-visible portions of a drawable using this graphics context will generate exposure events for the corresponding regions of the destination drawable. If `exposures` is `True` exposure events will be generated for non-visible areas. See the `gtk.gdk.Drawable.draw_drawable`() method.

### gtk.gdk.GC.set_line_attributes

        def set_line_attributes(line_width, line_style, cap_style, join_style)

`line_width` : | the new line width in pixels
`line_style` : | the new line style
`cap_style` : | the new line end style
`join_style` : | the new line join style

The `set_line_attributes`() method sets the attributes to be used when drawing a line using the graphics context to the values specified by `line_width`, `line_style`, `cap_style` and `join_style`. The value of `line_style` must be one of:

`gtk.gdk.LINE_SOLID` | Lines are drawn solid.
`gtk.gdk.LINE_ON_OFF_DASH` | Lines are drawn dashed where even segments are drawn but odd segments are not drawn.
`gtk.gdk.LINE_DOUBLE_DASH` | Lines are drawn dashed where even segments are drawn normally but odd segments are drawn in the background color if the fill style is `gtk.gdk.SOLID`, or in the background color masked by the stipple if the fill style is `gtk.gdk.STIPPLED`.

The value of cap_style must be one of:

`gtk.gdk.CAP_NOT_LAST` | The same as `gtk.gdk.CAP_BUTT` for lines of non-zero width but for zero width lines, the final point on the line will not be drawn.
`gtk.gdk.CAP_BUTT` | The ends of the lines are drawn squared off and extending to the coordinates of the end point.
`gtk.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.
`gtk.gdk.CAP_PROJECTING` | The ends of the lines are drawn squared off and extending half the width of the line beyond the end point.

The value of join_style must be one of:

`gtk.gdk.JOIN_MITER` | The sides of each line are extended to meet at an angle.
`gtk.gdk.JOIN_ROUND` | The sides of the two lines are joined by a circular arc.
`gtk.gdk.JOIN_BEVEL` | The sides of the two lines are joined by a straight line which makes an equal angle with each line.

### gtk.gdk.GC.set_dashes

        def set_dashes(dash_offset, dash_list, n)

`dash_offset` : | the index of the length in `dash_list` to use as the firstst dash
`dash_list` : | the tuple or list of dash lengths in pixels

The `set_dashes`() method sets the pattern for drawing dashed lines using the tuple or list of dash lengths specified by `dash_list` with the index of the starting dash length specified by `dash_offset`. 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 `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.

### gtk.gdk.GC.offset

        def offset(x_offset, y_offset)

`x_offset` : | the amount by which to offset the graphics context in the X direction
`y_offset` : | the amount by which to offset the graphics context in the Y direction

The `offset`() method sets offset attributes such as the clip and tile-stipple origins of the graphics context so that drawing at x - `x_offset`, y - `y_offset` with the offset graphics context has the same effect as drawing at x, y with the original graphics context.

### gtk.gdk.GC.copy

        def copy(src_gc)

`src_gc` : | the `gtk.gdk.GC` to copy

The `copy`() method copies the attributes of the `gtk.gdk.GC` specified by `src_gc` into this graphics context.

### gtk.gdk.GC.set_colormap

        def set_colormap(colormap)

`colormap` : | a `gtk.gdk.Colormap`

The `set_colormap`() method sets the colormap for the graphics context to the specified `colormap`. The depth of the colormap's visual must match the depth of the drawable for which the graphics context was created.

### gtk.gdk.GC.get_colormap

        def get_colormap()

Returns : | the colormap used by the graphics context

The `get_colormap`() method returns the colormap for the graphics context, if it exists. A graphics context will have a colormap if the drawable for which it was created has a colormap, or if a colormap was set explicitly with the `set_colormap`() method.

### gtk.gdk.GC.set_rgb_fg_color

        def set_rgb_fg_color(color)

`color` : | an unallocated `gtk.gdk.Color`.

The `set_rgb_fg_color`() method sets the foreground color of a graphics context using the specified unallocated `color`. The pixel value for `color` will be determined using GdkRGB. If the colormap for the graphics context 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 method for a graphics context without a colormap is an error.

### gtk.gdk.GC.set_rgb_bg_color

        def set_rgb_bg_color(color)

`color` : | an unallocated `gtk.gdk.Color`.

The `set_rgb_bg_color`() method sets the background color of a graphics context using the specified unallocated `color`. The pixel value for `color` will be determined using GdkRGB. If the colormap for the graphics context 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 method for a graphics context without a colormap is an error.

### gtk.gdk.GC.get_screen

        def get_screen()

Returns : | the `gtk.gdk.Screen` for the gc

### Note

This method is available in PyGTK 2.2. and above.

The `get_screen`() method returns the `gtk.gdk.Screen` on which the gc was created.

Prev | Up | Next
gtk.gdk.Event | Home | gtk.gdk.Image