gtk.gdk.Drawable — a base class for drawing methods
class gtk.gdk.Drawable( |
|
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.
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.
def set_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.
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.
def get_visual()
Returns : | a gtk.gdk.Visual |
The get_visual
() method returns the
gtk.gdk.Visual
describing the pixel format of the drawable.
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.
def get_screen()
Returns : | the gtk.gdk.Screen
associated with the drawable |
This method is available in PyGTK 2.2 and above.
The get_screen
() method returns the
gtk.gdk.Screen
associated with the drawable.
def get_display()
Returns : | the gtk.gdk.Display
associated with the drawable |
This method is available in PyGTK 2.2 and above.
The get_display
() method returns the
gtk.gdk.Display
associated with the drawable.
def draw_point(gc
, x
, y
)
| a graphics context |
| the X coordinate of the point in drawable coordinates |
| 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
.
def draw_line(gc
, x1
, y1
, x2
, y2
)
| a graphics context |
| the X coordinate of the first point |
| the Y coordinate of the first point |
| the X coordinate of the second point |
| 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
.
def draw_rectangle(gc
, filled
, x
, y
, width
, height
)
| a graphics context |
| if True the rectangle will
be filled with the foreground color |
| the X coordinate of the top left corner |
| the Y coordinate of the top left corner |
| the width of the rectangle |
| 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.
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.
def draw_arc(gc
, filled
, x
, y
, width
, height
, angle1
, angle2
)
| a graphics context |
| if True the arc will be
filled with the foreground color creating a "pie slice" |
| the X coordinate of the left edge of the bounding rectangle. |
| the Y coordinate of the top edge of the bounding rectangle. |
| the width of the bounding rectangle. |
| the height of the bounding rectangle. |
| the start angle of the arc, relative to the 3 o'clock position, counter-clockwise, in 1/64ths of a degree. |
| 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.
def draw_polygon(gc
, filled
, points
)
| a graphics context |
| if True the polygon will be
filled with the foreground color |
| 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.
def draw_drawable(gc
, src
, xsrc
, ysrc
, xdest
, ydest
, width
, height
)
| a gtk.gdk.GC sharing the
drawable's visual and colormap |
| another gtk.gdk.Drawable |
| the X position in src of
rectangle to draw |
| the Y position in src of
rectangle to draw |
| the X position in the drawable where the rectangle should be drawn |
| the Y position in the drawable where the rectangle should be drawn |
| the width of rectangle to draw, or -1 for
entire src width |
| 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.
def draw_image(gc
, image
, xsrc
, ysrc
, xdest
, ydest
, width
, height
)
| a graphics context |
| a gtk.gdk.Image |
| the left edge of the source rectangle within
image . |
| the top edge of the source rectangle within
image . |
| the left edge of the destination within drawable. |
| the top edge of the destination within drawable. |
| the width of the area to be copied, or -1 to
make the area extend to the right edge of
image . |
| 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.
def draw_points(gc
, points
)
| a graphics context |
| 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.
def draw_segments(gc
, segs
)
| a graphics context |
| 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).
def draw_lines(gc
, points
)
| a graphics context |
| 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.
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)
| a gtk.gdk.GC ,
used for clipping, or None |
| a gtk.gdk.Pixbuf |
| Source X coordinate within pixbuf. |
| Source Y coordinate within pixbuf. |
| Destination X coordinate within drawable. |
| Destination Y coordinate within drawable. |
| Width of region to render, in pixels, or -1 to use pixbuf width. Must be specified in PyGTK 2.2. |
| Height of region to render, in pixels, or -1 to use pixbuf height. Must be specified in PyGTK 2.2 |
| Dithering mode for
GdkRGB . |
| X offset for dither. |
| Y offset for dither. |
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:
| Never use dithering. |
| Use dithering in 8 bits per pixel (and below) only. |
| 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.
def draw_glyphs(gc
, font
, x
, y
, glyphs
)
| a gtk.gdk.GC |
| the font to be used |
| the X coordinate of baseline origin |
| the Y coordinate of baseline origin |
| 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.
def draw_layout_line(gc
, x
, y
, line
, foreground
=None, background
=None)
| base graphics to use |
| the x position of start of string (in pixels) |
| the y position of baseline (in pixels) |
| a pango.LayoutLine |
| a gtk.gdk.Color
to override the foreground color or
None |
| a gtk.gdk.Color
to override the background color or
None |
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.Color
s
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.
def draw_layout(gc
, x
, y
, layout
, foreground
=None, background
=None)
| base graphics context to use |
| the X position of the left of the layout (in pixels) |
| the Y position of the top of the layout (in pixels) |
| a pango.Layout |
| a gtk.gdk.Color to
override the foreground color or
None |
| 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
.
def get_image(x
, y
, width
, height
)
| the X coordinate on the drawable |
| the Y coordinate on the drawable |
| the width of region to get |
| 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.
def get_clip_region()
Returns : | a gtk.gdk.Region . |
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.
def get_visible_region()
Returns : | a gtk.gdk.Region . This must be freed with gdk_region_destroy()
when you are done. |
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.
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
>)
| the foreground gtk.gdk.Color |
| the background gtk.gdk.Color |
| a font (deprecated and ignored) |
| 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 fill style - one of:
gtk.gdk.SOLID , gtk.gdk.TILED ,
gtk.gdk.STIPPLED ,
gtk.gdk.OPAQUE_STIPPLED |
| a gtk.gdk.Pixmap used
for tiling the background |
| a gtk.gdk.Pixmap used
for stippling the background |
| a gtk.gdk.Pixmap of
depth 1 used to mask pixels to be drawn |
| the mode of drawing on subwindows in a
gtk.gdk.Window - one of: gtk.gdk.CLIP_BY_CHILDREN or
gtk.gdk.INCLUDE_INFERIORS |
| the X coordinate of the origin of
tile or
stipple |
| the Y coordinate of the origin of
tile or
stipple |
| the X coordinate of the origin of
clip_mask |
| the Y coordinate of the origin of
clip_mask |
| if True graphics exposures
are enabled for calls to the draw_drawable ()
method. |
| the line width in pixels |
| the line style - one of:
gtk.gdk.LINE_SOLID ,
gtk.gdk.LINE_ON_OFF_DASH ,
gtk.gdk.LINE_DOUBLE_DASH |
| the style of line ends - one of:
gtk.gdk.CAP_NOT_LAST ,
gtk.gdk.CAP_BUTT , gtk.gdk.CAP_ROUND ,
gtk.gdk.CAP_PROJECTING |
| 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.
def draw_rgb_image_dithalign(gc
, x
, y
, width
, height
, dith
, rgb_buf
, rowstride
=-1, xdith
=0, ydith
=0)
| a graphics context |
| the X coordinate of the top-left corner in the drawable. |
| the Y coordinate of the top-left corner in the drawable. |
| the width of the image to be drawn. |
| the height of the image to be drawn. |
| a dither value - one of:
gtk.gdk.RGB_DITHER_NONE ,
gtk.gdk.RGB_DITHER_NORMAL ,
gtk.gdk.RGB_DITHER_MAX |
| the pixel data, represented as packed 24-bit data. |
| 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. |
| an X offset for dither alignment. |
| 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.
def draw_rgb_32_image(gc
, x
, y
, width
, height
, dith
, rgb_buf
, rowstride
=-1, xdith
=0, ydith
=0)
| a graphics context |
| the X coordinate of the top-left corner in the drawable. |
| the Y coordinate of the top-left corner in the drawable. |
| the width of the image to be drawn. |
| the height of the image to be drawn. |
| a dither value - one of:
gtk.gdk.RGB_DITHER_NONE ,
gtk.gdk.RGB_DITHER_NORMAL ,
gtk.gdk.RGB_DITHER_MAX |
| the pixel data, represented as padded 32-bit data. |
| 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. |
| an X offset for dither alignment. |
| 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.
def draw_gray_image(gc
, x
, y
, width
, height
, dith
, buf
, rowstride
=-1)
| a graphics context |
| the X coordinate of the top-left corner in the drawable. |
| the Y coordinate of the top-left corner in the drawable. |
| the width of the image to be drawn. |
| the height of the image to be drawn. |
| a dither value - one of:
gtk.gdk.RGB_DITHER_NONE ,
gtk.gdk.RGB_DITHER_NORMAL ,
gtk.gdk.RGB_DITHER_MAX |
| the pixel data, represented as 8-bit gray values. |
| 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
.
def draw_indexed_image(gc
, x
, y
, width
, height
, dith
, buf
, rowstride
, colors
)
| a graphics context |
| The x coordinate of the top-left corner in the drawable. |
| the y coordinate of the top-left corner in the drawable. |
| the width of the rectangle to be drawn. |
| the height of the rectangle to be drawn. |
| a GdkRgbDither value, selecting the desired dither mode. |
| the pixel data, represented as 8-bit color indices. |
| the number of bytes from the start of one row in
buf to the start of the
next. |
| a list of colors represented as 0xRRGGBB integer values. |
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.
def cairo_create()
Returns : | a gtk.gdk.CairoContext |
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.