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-WriteThe background gtk.gdk.Color.
"cap_style"Read-WriteThe 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-WriteA gtk.gdk.Pixmap bitmap used to clip the drawing operation.
"clip_x_origin"Read-WriteThe x origin of the clip mask.
"clip_y_origin"Read-WriteThe y origin of the clip mask.
"fill"Read-WriteThe fill style - one of: gtk.gdk.SOLID, gtk.gdk.TILED, gtk.gdk.STIPPLED or gtk.gdk.OPAQUE_STIPPLED.
"font"Read-WriteThe default font (deprecated and unused)
"foreground"Read-WriteThe foreground gtk.gdk.Color.
"function"Read-WriteA 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-WriteIf True graphics exposures are enabled.
"join_style"Read-WriteThe style used to join lines - one of: gtk.gdk.JOIN_MITER, gtk.gdk.JOIN_ROUND or gtk.gdk.JOIN_BEVEL.
"line_style"Read-WriteThe 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-WriteThe width of a line in pixels.
"stipple"Read-WriteThe gtk.gdk.Pixmap bitmap used to stipple the background.
"sub_window"Read-WriteThe mode of drawing in a gtk.gdk.Window with subwindows - one of: gtk.gdk.CLIP_BY_CHILDREN or gtk.gdk.INCLUDE_INFERIORS.
"tile"Read-WriteThe gtk.gdk.Pixmap used to tile the background.
"ts_x_origin"Read-WriteThe x origin of the tile or stipple.
"ts_y_origin"Read-WriteThe 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.