Next: , Previous: Graphics Contexts, Up: Top


8 Drawing Primitives

Functions for drawing points, lines, arcs, and text

8.1 Overview

These functions 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 <gdk-window> or <gdk-pixmap> objects.

Many of the drawing operations take a <gdk-gc> argument, which represents a graphics context. This <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 data structures like <pango-context>, <pango-layout> or <pango-layout-line> as arguments. If you're using GTK+, the ususal way to obtain these structures is via gtk-widget-create-pango-context or gtk-widget-create-pango-layout.

8.2 Usage

— Class: <gdk-drawable>

Derives from <gobject>.

This class defines no direct slots.

— Function: gdk-drawable-get-display (self <gdk-drawable>) ⇒  (ret <gdk-display>)
— Method: get-display

Gets the <gdk-display> associated with a <gdk-drawable>.

drawable
a <gdk-drawable>
ret
the <gdk-display> associated with drawable

Since 2.2

— Function: gdk-drawable-get-screen (self <gdk-drawable>) ⇒  (ret <gdk-screen>)
— Method: get-screen

Gets the <gdk-screen> associated with a <gdk-drawable>.

drawable
a <gdk-drawable>
ret
the <gdk-screen> associated with drawable

Since 2.2

— Function: gdk-drawable-get-visual (self <gdk-drawable>) ⇒  (ret <gdk-visual>)
— Method: get-visual

Gets the <gdk-visual> describing the pixel format of drawable.

drawable
a <gdk-drawable>
ret
a <gdk-visual>
— Function: gdk-drawable-set-colormap (self <gdk-drawable>) (colormap <gdk-colormap>)
— Method: set-colormap

Sets the colormap associated with drawable. 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 <gdk-gc> to draw to a drawable, or copying one drawable to another, the colormaps should match.

drawable
a <gdk-drawable>
colormap
a <gdk-colormap>
— Function: gdk-drawable-get-colormap (self <gdk-drawable>) ⇒  (ret <gdk-colormap>)
— Method: get-colormap

Gets the colormap for drawable, if one is set; returns ‘#f’ otherwise.

drawable
a <gdk-drawable>
ret
the colormap, or ‘#f
— Function: gdk-drawable-get-depth (self <gdk-drawable>) ⇒  (ret int)
— Method: get-depth

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

drawable
a <gdk-drawable>
ret
number of bits per pixel
— Function: gdk-drawable-get-size (self <gdk-drawable>) ⇒  (width int) (height int)
— Method: get-size

Fills *width and *height with the size of drawable. width or height can be ‘#f’ if you only want the other one.

On the X11 platform, if drawable is a <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.

drawable
a <gdk-drawable>
width
location to store drawable's width, or ‘#f
height
location to store drawable's height, or ‘#f
— Function: gdk-drawable-get-clip-region (self <gdk-drawable>) ⇒  (ret <gdk-region>)
— Method: get-clip-region

Computes the region of a drawable that potentially can be written to by drawing primitives. This region will not take into account the clip region for the 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.

drawable
a <gdk-drawable>
ret
a <gdk-region>. This must be freed with gdk-region-destroy when you are done.
— Function: gdk-drawable-get-visible-region (self <gdk-drawable>) ⇒  (ret <gdk-region>)
— Method: get-visible-region

Computes the region of a 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.

drawable
a <gdk-drawable>
ret
a <gdk-region>. This must be freed with gdk-region-destroy when you are done.
— Function: gdk-draw-point (drawable <gdk-drawable>) (gc <gdk-gc>) (int) (int)

Draws a point, using the foreground color and other attributes of the <gdk-gc>.

drawable
a <gdk-drawable> (a <gdk-window> or a <gdk-pixmap>).
gc
a <gdk-gc>.
x
the x coordinate of the point.
y
the y coordinate of the point.
— Function: gdk-draw-line (drawable <gdk-drawable>) (gc <gdk-gc>) (x1_ int) (y1_ int) (x2_ int) (y2_ int)

Draws a line, using the foreground color and other attributes of the <gdk-gc>.

drawable
a <gdk-drawable> (a <gdk-window> or a <gdk-pixmap>).
gc
a <gdk-gc>.
x1
the x coordinate of the start point.
y1
the y coordinate of the start point.
x2
the x coordinate of the end point.
y2
the y coordinate of the end point.
— Function: gdk-draw-pixbuf (drawable <gdk-drawable>) (gc <gdk-gc>) (pixbuf <gdk-pixbuf>) (src_x int) (src_y int) (dest_x int) (dest_y int) (width int) (height int) (dither <gdk-rgb-dither>) (x_dither int) (y_dither int)

Renders a rectangular portion of a pixbuf to a drawable. 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-‘#f’ window argument. Otherwise a colormap must be set on them with gdk-drawable-set-colormap.

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.

drawable
Destination drawable.
gc
a <gdk-gc>, used for clipping, or ‘#f
pixbuf
a <gdk-pixbuf>
src-x
Source X coordinate within pixbuf.
src-y
Source Y coordinates 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.
height
Height of region to render, in pixels, or -1 to use pixbuf height.
dither
Dithering mode for <gdk-rgb>.
x-dither
X offset for dither.
y-dither
Y offset for dither.

Since 2.2

— Function: gdk-draw-rectangle (drawable <gdk-drawable>) (gc <gdk-gc>) (filled bool) (int) (int) (width int) (height int)

Draws a rectangular outline or filled rectangle, using the foreground color and other attributes of the <gdk-gc>.

A rectangle drawn filled is 1 pixel smaller in both dimensions than a rectangle outlined. Calling ‘gdk_draw_rectangle (window, gc, TRUE, 0, 0, 20, 20)’ results in a filled rectangle 20 pixels wide and 20 pixels high. Calling ‘gdk_draw_rectangle (window, 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.

drawable
a <gdk-drawable> (a <gdk-window> or a <gdk-pixmap>).
gc
a <gdk-gc>.
filled
#t’ if the rectangle should be filled.
x
the x coordinate of the left edge of the rectangle.
y
the y coordinate of the top edge of the rectangle.
width
the width of the rectangle.
height
the height of the rectangle.
— Function: gdk-draw-arc (drawable <gdk-drawable>) (gc <gdk-gc>) (filled bool) (int) (int) (width int) (height int) (angle1 int) (angle2 int)

Draws an arc or a filled 'pie slice'. The arc is defined by the bounding rectangle of the entire ellipse, and the start and end angles of the part of the ellipse to be drawn.

drawable
a <gdk-drawable> (a <gdk-window> or a <gdk-pixmap>).
gc
a <gdk-gc>.
filled
#t’ if the arc should be filled, producing 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, in 1/64ths of a degree.
— Function: gdk-draw-glyphs (drawable <gdk-drawable>) (gc <gdk-gc>) (font <pango-font>) (int) (int) (glyphs <pango-glyph-string>)

This is a low-level function; 99% of text rendering should be done using gdk-draw-layout instead.

A glyph is a single image in a font. This function draws a sequence of glyphs. To obtain a sequence of glyphs you have to understand a lot about internationalized text handling, which you don't want to understand; thus, use gdk-draw-layout instead of this function, gdk-draw-layout handles the details.

drawable
a <gdk-drawable>
gc
a <gdk-gc>
font
font to be used
x
X coordinate of baseline origin
y
Y coordinate of baseline origin
glyphs
the glyph string to draw
— Function: gdk-draw-glyphs-transformed (drawable <gdk-drawable>) (gc <gdk-gc>) (matrix <pango-matrix>) (font <pango-font>) (int) (int) (glyphs <pango-glyph-string>)

Renders a <pango-glyph-string> onto a drawable, possibly transforming the layed-out coordinates through a transformation matrix. Note that the transformation matrix for font is not changed, so to produce correct rendering results, the font must have been loaded using a <pango-context> with an identical transformation matrix to that passed in to this function.

See also gdk-draw-glyphs, gdk-draw-layout.

drawable
a <gdk-drawable>
gc
a <gdk-gc>
matrix
a <pango-matrix>, or ‘#f’ to use an identity transformation
font
the font in which to draw the string
x
the x position of the start of the string (in Pango units in user space coordinates)
y
the y position of the baseline (in Pango units in user space coordinates)
glyphs
the glyph string to draw

Since 2.6

— Function: gdk-draw-layout-line (drawable <gdk-drawable>) (gc <gdk-gc>) (int) (int) (line <pango-layout-line>)

Render a <pango-layout-line> onto an GDK drawable

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.

drawable
the drawable on which to draw the line
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-layout-line>
— Function: gdk-draw-layout-line-with-colors (drawable <gdk-drawable>) (gc <gdk-gc>) (int) (int) (line <pango-layout-line>) (foreground <gdk-color>) (background <gdk-color>)

Render a <pango-layout-line> onto a <gdk-drawable>, overriding the layout's normal colors with foreground and/or background. foreground and background need not be allocated.

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.

drawable
the drawable on which to draw the line
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-layout-line>
foreground
foreground override color, or ‘#f’ for none
background
background override color, or ‘#f’ for none
— Function: gdk-draw-layout (drawable <gdk-drawable>) (gc <gdk-gc>) (int) (int) (layout <pango-layout>)

Render a <pango-layout> onto a GDK drawable

If the layout's <pango-context> has a transformation matrix set, then x and y specify the position of the top left corner of the bounding box (in device space) of the transformed layout.

If you're using GTK+, the usual way to obtain a <pango-layout> is gtk-widget-create-pango-layout.

drawable
the drawable on which to draw string
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>
— Function: gdk-draw-layout-with-colors (drawable <gdk-drawable>) (gc <gdk-gc>) (int) (int) (layout <pango-layout>) (foreground <gdk-color>) (background <gdk-color>)

Render a <pango-layout> onto a <gdk-drawable>, overriding the layout's normal colors with foreground and/or background. foreground and background need not be allocated.

If the layout's <pango-context> has a transformation matrix set, then x and y specify the position of the top left corner of the bounding box (in device space) of the transformed layout.

If you're using GTK+, the ususal way to obtain a <pango-layout> is gtk-widget-create-pango-layout.

drawable
the drawable on which to draw string
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
foreground override color, or ‘#f’ for none
background
background override color, or ‘#f’ for none
— Function: gdk-draw-string (drawable <gdk-drawable>) (font <gdk-font>) (gc <gdk-gc>) (int) (int) (string mchars)

gdk_draw_string’ is deprecated and should not be used in newly-written code. Use gdk-draw-layout instead.

Draws a string of characters in the given font or fontset.

drawable
a <gdk-drawable> (a <gdk-window> or a <gdk-pixmap>).
font
a <gdk-font>.
gc
a <gdk-gc>.
x
the x coordinate of the left edge of the text.
y
the y coordinate of the baseline of the text.
string
the string of characters to draw.
— Function: gdk-draw-drawable (drawable <gdk-drawable>) (gc <gdk-gc>) (src <gdk-drawable>) (xsrc int) (ysrc int) (xdest int) (ydest int) (width int) (height int)

Copies the width x height region of src at coordinates (xsrc, ysrc) to coordinates (xdest, ydest) in drawable. width and/or height may be given as -1, in which case the entire src drawable will be copied.

Most fields in gc are not used for this operation, but notably 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/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 the stipple on the <gdk-gc>, set the fill mode to ‘GDK_STIPPLED’, and then draw the rectangle.

drawable
a <gdk-drawable>
gc
a <gdk-gc> sharing the drawable's visual and colormap
src
the source <gdk-drawable>, which may be the same as drawable
xsrc
X position in src of rectangle to draw
ysrc
Y position in src of rectangle to draw
xdest
X position in drawable where the rectangle should be drawn
ydest
Y position in drawable where the rectangle should be drawn
width
width of rectangle to draw, or -1 for entire src width
height
height of rectangle to draw, or -1 for entire src height
— Function: gdk-draw-image (drawable <gdk-drawable>) (gc <gdk-gc>) (image <gdk-image>) (xsrc int) (ysrc int) (xdest int) (ydest int) (width int) (height int)

Draws a <gdk-image> onto a drawable. The depth of the <gdk-image> must match the depth of the <gdk-drawable>.

drawable
a <gdk-drawable> (a <gdk-window> or a <gdk-pixmap>).
gc
a <gdk-gc>.
image
the <gdk-image> to draw.
xsrc
the left edge of the source rectangle within image.
ysrc
the top of the source rectangle within image.
xdest
the x coordinate of the destination within drawable.
ydest
the y coordinate 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.
— Function: gdk-drawable-get-image (self <gdk-drawable>) (int) (int) (width int) (height int) ⇒  (ret <gdk-image>)
— Method: get-image

A <gdk-image> stores client-side image data (pixels). In contrast, <gdk-pixmap> and <gdk-window> are server-side objects. gdk-drawable-get-image obtains the pixels from a server-side drawable as a client-side <gdk-image>. The format of a <gdk-image> depends on the <gdk-visual> of the current display, which makes manipulating <gdk-image> extremely difficult; therefore, in most cases you should use gdk-pixbuf-get-from-drawable instead of this lower-level function. A <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.

x, y, width, and height define the region of drawable to obtain as an image.

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 <gdk-window> and partially offscreen or obscured, then the obscured portions of the returned image will contain undefined data.

drawable
a <gdk-drawable>
x
x coordinate on drawable
y
y coordinate on drawable
width
width of region to get
height
height or region to get
ret
a <gdk-image> containing the contents of drawable
— Function: gdk-drawable-copy-to-image (self <gdk-drawable>) (image <gdk-image>) (src_x int) (src_y int) (dest_x int) (dest_y int) (width int) (height int) ⇒  (ret <gdk-image>)
— Method: copy-to-image

Copies a portion of drawable into the client side image structure image. If image is ‘#f’, creates a new image of size width x height and copies into that. See gdk-drawable-get-image for further details.

drawable
a <gdk-drawable>
image
a <gdk-drawable>, or ‘#f’ if a new image should be created.
src-x
x coordinate on drawable
src-y
y coordinate on drawable
dest-x
x coordinate within image. Must be 0 if image is ‘#f
dest-y
y coordinate within image. Must be 0 if image is ‘#f
width
width of region to get
height
height or region to get
ret
image, or a new a <gdk-image> containing the contents of drawable

Since 2.4