gtk.gdk.Drawable

gtk.gdk.Drawable — a base class for drawing methods

Synopsis

class gtk.gdk.Drawable(gobject.GObject):
    def get_size()
def set_colormap(colormap)
def get_colormap()
def get_visual()
def get_depth()
def get_screen()
def get_display()
def draw_point(gc, x, y)
def draw_line(gc, x1, y1, x2, y2)
def draw_rectangle(gc, filled, x, y, width, height)
def draw_arc(gc, filled, x, y, width, height, angle1, angle2)
def draw_polygon(gc, filled, points)
def draw_drawable(gc, src, xsrc, ysrc, xdest, ydest, width, height)
def draw_image(gc, image, xsrc, ysrc, xdest, ydest, width, height)
def draw_points(gc, points)
def draw_segments(gc, segs)
def draw_lines(gc, points)
def draw_pixbuf(gc, pixbuf, src_x, src_y, dest_x, dest_y, width=-1, height=-1, dither=gtk.gdk.RGB_DITHER_NORMAL, x_dither=0, y_dither=0)
def draw_glyphs(gc, font, x, y, glyphs)
def draw_layout_line(gc, x, y, line, layout, foreground=None, background=None)
def draw_layout(gc, x, y, layout, foreground=None, background=None)
def get_image(x, y, width, height)
def get_clip_region()
def get_visible_region()
def new_gc(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 draw_rgb_image(gc, x, y, width, height, dith, rgb_buf, rowstride=-1, xdith=0, ydith=0)
def draw_rgb_32_image(gc, x, y, width, height, dith, rgb_buf, rowstride=-1, xdith=0, ydith=0)
def draw_gray_image(gc, x, y, width, height, dith, buf, rowstride=-1)
def draw_indexed_image(gc, x, y, width, height, dith, buf, rowstride, cmap)
def cairo_create()

Ancestry

+-- gobject.GObject
  +-- gtk.gdk.Drawable

Attributes

"handle"ReadThe handle of the MS Windows window associated with the drawable. Not supported on X11.
"xid"ReadThe id of the X window available with the drawable. Not supported on MS Windows

Description

A gtk.gdk.Drawable is a base class providing drawing primitives for its subclasses: gtk.gdk.Pixmap and gtk.gdk.Window.

These methods provide support for drawing points, lines, arcs and text onto what are called 'drawables'. Drawables, as the name suggests, are things which support drawing onto them, and are either gtk.gdk.Window or gtk.gdk.Pixmap objects.

Many of the drawing operations take a gtk.gdk.GC argument, which represents a graphics context. This gtk.gdk.GC contains a number of drawing attributes such as foreground color, background color and line width, and is used to reduce the number of arguments needed for each drawing operation. See the Graphics Contexts section for more information.

Some of the drawing operations take Pango objects like pango.Context or pango.Layout as arguments. Use the gtk.Widget.create_pango_context() or gtk.Widget.create_pango_layout() methods to obtain these objects.

Methods

gtk.gdk.Drawable.get_size

    def get_size()

Returns :

a tuple containing the drawable's width and height

The get_size() method returns a tuple containing the width and height of the drawable.

On the X11 platform, if the drawable is a gtk.gdk.Window, the returned size is the size reported in the most-recently-processed configure event, rather than the current size on the X server.

gtk.gdk.Drawable.set_colormap

    def set_colormap(colormap)

colormap :

a gtk.gdk.Colormap

The set_colormap() method sets the gtk.gdk.Colormap associated with the drawable to the value specified by colormap. Normally this will happen automatically when the drawable is created; you only need to use this function if the drawable-creating function did not have a way to determine the colormap, and you then use drawable operations that require a colormap. The colormap for all drawables and graphics contexts you intend to use together should match. i.e. when using a gtk.gdk.GC to draw to a drawable, or copying one drawable to another, the colormaps should match.

gtk.gdk.Drawable.get_colormap

    def get_colormap()

Returns :

the colormap, or None

The get_colormap() method returns the gtk.gdk.Colormap for the drawable or None if no colormap is set.

gtk.gdk.Drawable.get_visual

    def get_visual()

Returns :

a gtk.gdk.Visual

The get_visual() method returns the gtk.gdk.Visual describing the pixel format of the drawable.

gtk.gdk.Drawable.get_depth

    def get_depth()

Returns :

the number of bits per pixel

The get_depth() method returns the bit depth of the drawable, that is, the number of bits that make up a pixel in the drawable's visual. Examples are 8 bits per pixel, 24 bits per pixel, etc.

gtk.gdk.Drawable.get_screen

    def get_screen()

Returns :

the gtk.gdk.Screen associated with the drawable

Note

This method is available in PyGTK 2.2 and above.

The get_screen() method returns the gtk.gdk.Screen associated with the drawable.

gtk.gdk.Drawable.get_display

    def get_display()

Returns :

the gtk.gdk.Display associated with the drawable

Note

This method is available in PyGTK 2.2 and above.

The get_display() method returns the gtk.gdk.Display associated with the drawable.

gtk.gdk.Drawable.draw_point

    def draw_point(gc, x, y)

gc :

a graphics context

x :

the X coordinate of the point in drawable coordinates

y :

the Y coordinate of the point in drawable coordinates

The draw_point() method draws a point at the location specified by x and y in the drawable using the gtk.gdk.GC graphics context specified by gc.

gtk.gdk.Drawable.draw_line

    def draw_line(gc, x1, y1, x2, y2)

gc :

a graphics context

x1 :

the X coordinate of the first point

y1 :

the Y coordinate of the first point

x2 :

the X coordinate of the second point

y2 :

the Y coordinate of the second point

The draw_line() method draws a line between the two points specified by (x1, y1) and (x2, y2) using the gtk.gdk.GC graphics context specified by gc.

gtk.gdk.Drawable.draw_rectangle

    def draw_rectangle(gc, filled, x, y, width, height)

gc :

a graphics context

filled :

if True the rectangle will be filled with the foreground color

x :

the X coordinate of the top left corner

y :

the Y coordinate of the top left corner

width :

the width of the rectangle

height :

the height of the rectangle

The draw_rectangle() method draws a rectangle of the specified width and height with its top left corner at the location specified by (x, y) using the gtk.gdk.GC graphics context specified by gc. If filled is True the rectangle will be filled with the foreground color.

Note

A rectangle drawn filled is 1 pixel smaller in both dimensions than a rectangle outlined. Calling:

  window.draw_rectangle(gc, True, 0, 0, 20, 20)

results in a filled rectangle 20 pixels wide and 20 pixels high. Calling:

  window.draw_rectangle(gc, False, 0, 0, 20, 20)
 

results in an outlined rectangle with corners at (0, 0), (0, 20), (20, 20), and (20, 0), which makes it 21 pixels wide and 21 pixels high.

gtk.gdk.Drawable.draw_arc

    def draw_arc(gc, filled, x, y, width, height, angle1, angle2)

gc :

a graphics context

filled :

if True the arc will be filled with the foreground color creating a "pie slice"

x :

the X coordinate of the left edge of the bounding rectangle.

y :

the Y coordinate of the top edge of the bounding rectangle.

width :

the width of the bounding rectangle.

height :

the height of the bounding rectangle.

angle1 :

the start angle of the arc, relative to the 3 o'clock position, counter-clockwise, in 1/64ths of a degree.

angle2 :

the end angle of the arc, relative to angle1, counter-clockwise, in 1/64ths of a degree.

The draw_arc() method draws an arc or a filled 'pie slice' if filled is True. The arc is defined by the bounding rectangle of the entire ellipse (specified by x, y, width and height), and the start and end angles of the part of the ellipse to be drawn (specified by angle1 and angle2). The gtk.gdk.GC graphics context specified by gc is used to determine the drawing attributes.

gtk.gdk.Drawable.draw_polygon

    def draw_polygon(gc, filled, points)

gc :

a graphics context

filled :

if True the polygon will be filled with the foreground color

points :

a sequence of 2-tuples

The draw_polygon() method draws an outlined or filled polygon using the points specified by points. points is a sequence of 2-tuples that each contain an x and y coordinate of a point. The points are connected in the order that they are specified and the last point is automatically connected to the first point. The gtk.gdk.GC graphics context specified by gc is used to determine the drawing attributes.

gtk.gdk.Drawable.draw_drawable

    def draw_drawable(gc, src, xsrc, ysrc, xdest, ydest, width, height)

gc :

a gtk.gdk.GC sharing the drawable's visual and colormap

src :

another gtk.gdk.Drawable

xsrc :

the X position in src of rectangle to draw

ysrc :

the Y position in src of rectangle to draw

xdest :

the X position in the drawable where the rectangle should be drawn

ydest :

the Y position in the drawable where the rectangle should be drawn

width :

the width of rectangle to draw, or -1 for entire src width

height :

the height of rectangle to draw, or -1 for entire src height

The draw_drawable() method copies the specified width x height area of the drawable specified by src at the specified coordinates (xsrc, ysrc) to the specified coordinates (xdest, ydest) in the drawable. width and height may be given as -1, to copy the entire src drawable. Most fields in the gtk.gdk.GC specified by gc are not used for this operation, but the clip mask or clip region will be honored.

The source and destination drawables must have the same visual and colormap, or errors will result. (On X11, failure to match visual and colormap results in a BadMatch error from the X server.) A common cause of this problem is an attempt to draw a bitmap to a color drawable. The way to draw a bitmap is to set the bitmap as a clip mask on your gtk.gdk.GC, then use the draw_rectangle() method to draw a rectangle clipped to the bitmap.

gtk.gdk.Drawable.draw_image

    def draw_image(gc, image, xsrc, ysrc, xdest, ydest, width, height)

gc :

a graphics context

image :

a gtk.gdk.Image

xsrc :

the left edge of the source rectangle within image.

ysrc :

the top edge of the source rectangle within image.

xdest :

the left edge of the destination within drawable.

ydest :

the top edge of the destination within drawable.

width :

the width of the area to be copied, or -1 to make the area extend to the right edge of image.

height :

the height of the area to be copied, or -1 to make the area extend to the bottom edge of image.

The draw_image() method draws the portion of the gtk.gdk.Image specified by the rectangle (xsrc, ysrc, width and height) onto the drawable at the location specified by xdest and ydest. The depth of the gtk.gdk.Image must match the depth of the gtk.gdk.Drawable. The gtk.gdk.GC graphics context specified by gc is used to determine the drawing attributes.

gtk.gdk.Drawable.draw_points

    def draw_points(gc, points)

gc :

a graphics context

points :

a sequence of 2-tuples

The draw_points() method draws the set of points specified by points on the drawable using the gtk.gdk.GC graphics context specified by gc. points is a sequence of 2-tuples each containing a pair of x and y coordinates of a point location in the drawable.

gtk.gdk.Drawable.draw_segments

    def draw_segments(gc, segs)

gc :

a graphics context

segs :

a sequence of 4-tuples

The draw_segments() method draws a set of line segments specified by segs on the drawable using the gtk.gdk.GC graphics context specified by gc to specify the drawing attributes. segs is a sequence of 4-tuples each containing the coordinates of the start and end points of the line segment in the format (x1, y1, x2, y2).

gtk.gdk.Drawable.draw_lines

    def draw_lines(gc, points)

gc :

a graphics context

points :

a sequence of 2-tuples

The draw_lines() method draws a series of lines connecting the points specified by points. points is a sequence of 2-tuples each containing the x and y coordinates of a point location. The gtk.gdk.GC graphics context specified by gc is used to determine the drawing attributes.The style of joins between lines is determined by the cap style attribute in the gtk.gdk.GC. This can be set with the gtk.gdk.GC.set_line_attributes() method.

gtk.gdk.Drawable.draw_pixbuf

    def draw_pixbuf(gc, pixbuf, src_x, src_y, dest_x, dest_y, width=-1, height=-1, dither=gtk.gdk.RGB_DITHER_NORMAL, x_dither=0, y_dither=0)

gc :

a gtk.gdk.GC, used for clipping, or None

pixbuf :

a gtk.gdk.Pixbuf

src_x :

Source X coordinate within pixbuf.

src_y :

Source Y coordinate within pixbuf.

dest_x :

Destination X coordinate within drawable.

dest_y :

Destination Y coordinate within drawable.

width :

Width of region to render, in pixels, or -1 to use pixbuf width. Must be specified in PyGTK 2.2.

height :

Height of region to render, in pixels, or -1 to use pixbuf height. Must be specified in PyGTK 2.2

dither :

Dithering mode for GdkRGB.

x_dither :

X offset for dither.

y_dither :

Y offset for dither.

Note

This method is available in PyGTK 2.2 and above.

The draw_pixbuf() method renders a rectangular portion of a gtk.gdk.Pixbuf specified by pixbuf to the drawable using the gtk.gdk.GC specified by gc. The portion of pixbuf that is rendered is specified by the origin point (src_x src_y) and the width and height arguments. pixbuf is rendered to the location in the drawable specified by (dest_x dest_y). dither specifies the dithering mode as one of:

gtk.gdk.RGB_DITHER_NONE

Never use dithering.

gtk.gdk.RGB_DITHER_NORMAL

Use dithering in 8 bits per pixel (and below) only.

gtk.gdk.RGB_DITHER_MAX

Use dithering in 16 bits per pixel and below.

The destination drawable must have a colormap. All windows have a colormap, however, pixmaps only have colormap by default if they were created with a non-None window argument. Otherwise a colormap must be set on them with the gtk.gdk.Drawable.set_colormap() method.

On older X servers, rendering pixbufs with an alpha channel involves round trips to the X server, and may be somewhat slow. The clip mask of gc is ignored, but clip rectangles and clip regions work fine.

gtk.gdk.Drawable.draw_glyphs

    def draw_glyphs(gc, font, x, y, glyphs)

gc :

a gtk.gdk.GC

font :

the font to be used

x :

the X coordinate of baseline origin

y :

the Y coordinate of baseline origin

glyphs :

the glyphs to render

The draw_glyphs() method draws the sequence of glyphs (characters in a font) specified by glyphs at the location specified by x and y using the font specified by font. Instead of using this method 99% of text rendering should be done using the draw_layout() method.

gtk.gdk.Drawable.draw_layout_line

    def draw_layout_line(gc, x, y, line, foreground=None, background=None)

gc :

base graphics to use

x :

the x position of start of string (in pixels)

y :

the y position of baseline (in pixels)

line :

a pango.LayoutLine

foreground :

a gtk.gdk.Color to override the foreground color or None

background :

a gtk.gdk.Color to override the background color or None

Note

This method is available in PyGTK 2.10 and above.

The draw_layout_line() method renders the pango.LayoutLine specified by line onto the drawable at the position specified by (x, y). The gtk.gdk.GC specified by gc is used as the graphics context but the layout's normal colors may be overriden with the gtk.gdk.Colors specified by foreground and/or background. foreground and background are optional and default to None.

If the layout's pango.Context has a transformation matrix set, then x and y specify the position of the left edge of the baseline (left is in before-tranform user coordinates) in after-transform device coordinates.

gtk.gdk.Drawable.draw_layout

    def draw_layout(gc, x, y, layout, foreground=None, background=None)

gc :

base graphics context to use

x :

the X position of the left of the layout (in pixels)

y :

the Y position of the top of the layout (in pixels)

layout :

a pango.Layout

foreground :

a gtk.gdk.Color to override the foreground color or None

background :

a gtk.gdk.Color to override the background color or None

The draw_layout() method renders the pango.Layout specified by layout onto the drawable at the location specified by x and y. If foreground or background has a value other than None it is used to override the corresponding attribute specified by gc.

gtk.gdk.Drawable.get_image

    def get_image(x, y, width, height)

x :

the X coordinate on the drawable

y :

the Y coordinate on the drawable

width :

the width of region to get

height :

the height or region to get

Returns :

a gtk.gdk.Image containing the contents of the drawable

The get_image() method returns a gtk.gdk.Image object containing a copy of the region in the drawable specified by x, y, width and height. A gtk.gdk.Image stores client-side image data (pixels). In contrast, a gtk.gdk.Pixmap and gtk.gdk.Window are server-side objects. The get_image() method retrieves the pixels from a server-side drawable as a client-side gtk.gdk.Image. The format of a gtk.gdk.Image depends on the gtk.gdk.Visual of the current display, which makes manipulating gtk.gdk.Image extremely difficult; therefore, in most cases you should use the gtk.gdk.Pixbuf.get_from_drawable() method instead of this lower-level function. A gtk.gdk.Pixbuf contains image data in a canonicalized RGB format, rather than a display-dependent format. Of course, there's a convenience vs. speed tradeoff here, so you'll want to think about what makes sense for your application.

You would usually copy image data to the client side if you intend to examine the values of individual pixels, for example to darken an image or add a red tint. It would be prohibitively slow to make a round-trip request to the windowing system for each pixel, so instead you get all of them at once, modify them, then copy them all back at once. If the X server or other windowing system backend is on the local machine, this function may use shared memory to avoid copying the image data. If the source drawable is a gtk.gdk.Window and partially off screen or obscured, then the obscured portions of the returned image will contain undefined data.

gtk.gdk.Drawable.get_clip_region

    def get_clip_region()

Returns :

a gtk.gdk.Region.

Note

This method is available in PyGTK 2.10 and above.

The get_clip_region() method computes and returns the gtk.gdk.Region of the drawable that potentially can be written to by drawing primitives. This region will not take into account the clip region for the gtk.gdk.GC, and may also not take into account other factors such as if the window is obscured by other windows, but no area outside of this region will be affected by drawing primitives.

gtk.gdk.Drawable.get_visible_region

    def get_visible_region()

Returns :

a gtk.gdk.Region. This must be freed with gdk_region_destroy() when you are done.

Note

This method is available in PyGTK 2.10 and above.

The get_visible_region() method computes and returns the gtk.gdk.Region of the drawable that is potentially visible. This does not necessarily take into account if the window is obscured by other windows, but no area outside of this region is visible.

gtk.gdk.Drawable.new_gc

    def new_gc(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 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 graphics context

The new_gc() method creates a new gtk.gdk.GC object with the attributes as specified by the arguments. Since there are a large number of parameters it's probably best to specify the attributes using keywords. Any attributes not specified will use a default value.

gtk.gdk.Drawable.draw_rgb_image

    def draw_rgb_image_dithalign(gc, x, y, width, height, dith, rgb_buf, rowstride=-1, xdith=0, ydith=0)

gc :

a graphics context

x :

the X coordinate of the top-left corner in the drawable.

y :

the Y coordinate of the top-left corner in the drawable.

width :

the width of the image to be drawn.

height :

the height of the image to be drawn.

dith :

a dither value - one of: gtk.gdk.RGB_DITHER_NONE, gtk.gdk.RGB_DITHER_NORMAL, gtk.gdk.RGB_DITHER_MAX

rgb_buf :

the pixel data, represented as packed 24-bit data.

rowstride :

the number of bytes from the start of one row in rgb_buf to the start of the next or -1 to calculate the number of bytes.

xdith :

an X offset for dither alignment.

ydith :

a Y offset for dither alignment.

The draw_rgb_image() method draws an RGB image in the drawable, with an adjustment for dither alignment. This method is useful when drawing dithered images into a window that may be scrolled. Pixel (x, y) will be drawn dithered as if its actual location is (x + xdith, y + ydith). Thus, if you draw an image into a window using zero dither alignment, then scroll up one pixel, subsequent draws to the window should have ydith = 1. Setting the dither alignment correctly allows updating of small parts of the screen while avoiding visible "seams" between the different dither textures.

gtk.gdk.Drawable.draw_rgb_32_image

    def draw_rgb_32_image(gc, x, y, width, height, dith, rgb_buf, rowstride=-1, xdith=0, ydith=0)

gc :

a graphics context

x :

the X coordinate of the top-left corner in the drawable.

y :

the Y coordinate of the top-left corner in the drawable.

width :

the width of the image to be drawn.

height :

the height of the image to be drawn.

dith :

a dither value - one of: gtk.gdk.RGB_DITHER_NONE, gtk.gdk.RGB_DITHER_NORMAL, gtk.gdk.RGB_DITHER_MAX

buf :

the pixel data, represented as padded 32-bit data.

rowstride :

the number of bytes from the start of one row in buf to the start of the next or -1 to calculate the number of bytes.

xdith :

an X offset for dither alignment.

ydith :

a Y offset for dither alignment.

The draw_rgb_32_image() method draws a padded RGB image in the drawable. The image is stored as one pixel per 32-bit word. It is laid out as a red byte, a green byte, a blue byte, and a padding byte. Otherwise this method works the same as the draw_rgb_image() method.

gtk.gdk.Drawable.draw_gray_image

    def draw_gray_image(gc, x, y, width, height, dith, buf, rowstride=-1)

gc :

a graphics context

x :

the X coordinate of the top-left corner in the drawable.

y :

the Y coordinate of the top-left corner in the drawable.

width :

the width of the image to be drawn.

height :

the height of the image to be drawn.

dith :

a dither value - one of: gtk.gdk.RGB_DITHER_NONE, gtk.gdk.RGB_DITHER_NORMAL, gtk.gdk.RGB_DITHER_MAX

buf :

the pixel data, represented as 8-bit gray values.

rowstride :

the number of bytes from the start of one row in buf to the start of the next or -1 to calculate the number of bytes.

The draw_gray_image() method draws a grayscale image on the drawable at the location specified by x and y with the image data in buf.

gtk.gdk.Drawable.draw_indexed_image

    def draw_indexed_image(gc, x, y, width, height, dith, buf, rowstride, colors)

gc :

a graphics context

x :

The x coordinate of the top-left corner in the drawable.

y :

the y coordinate of the top-left corner in the drawable.

width :

the width of the rectangle to be drawn.

height :

the height of the rectangle to be drawn.

dith :

a GdkRgbDither value, selecting the desired dither mode.

buf :

the pixel data, represented as 8-bit color indices.

rowstride :

the number of bytes from the start of one row in buf to the start of the next.

colors :

a list of colors represented as 0xRRGGBB integer values.

Note

This method is available in PyGTK 2.10 and above.

The draw_indexed_image() method draws an indexed image in the drawable, using the list of colors specified by colors to assign actual colors to the image's color indices.

gtk.gdk.Drawable.cairo_create

    def cairo_create()

Returns :

a gtk.gdk.CairoContext

Note

This method is available in PyGTK 2.8 and above.

The cairo_create() method returns a gtk.gdk.CairoContext object to be used for drawing on the drawable using Cairo drawing operations.