
@c %start of fragment

@deftp Class <gdk-drawable>
Derives from @code{<gobject>}.

This class defines no properties, other than those defined by its superclasses.

@end deftp

@deffn Function gdk-drawable-get-display  (self@tie{}@code{<gdk-drawable>}) @result{}@tie{} (ret@tie{}@code{<gdk-display>})
@deffnx Method get-display
Gets the @code{<gdk-display>} associated with a @code{<gdk-drawable>}.

@table @var
@item drawable
a @code{<gdk-drawable>}

@item ret
the @code{<gdk-display>} associated with @var{drawable}

@end table

Since 2.2

@end deffn

@deffn Function gdk-drawable-get-screen  (self@tie{}@code{<gdk-drawable>}) @result{}@tie{} (ret@tie{}@code{<gdk-screen>})
@deffnx Method get-screen
Gets the @code{<gdk-screen>} associated with a @code{<gdk-drawable>}.

@table @var
@item drawable
a @code{<gdk-drawable>}

@item ret
the @code{<gdk-screen>} associated with @var{drawable}

@end table

Since 2.2

@end deffn

@deffn Function gdk-drawable-get-visual  (self@tie{}@code{<gdk-drawable>}) @result{}@tie{} (ret@tie{}@code{<gdk-visual>})
@deffnx Method get-visual
Gets the @code{<gdk-visual>} describing the pixel format of @var{drawable}.

@table @var
@item drawable
a @code{<gdk-drawable>}

@item ret
a @code{<gdk-visual>}

@end table

@end deffn

@deffn Function gdk-drawable-set-colormap  (self@tie{}@code{<gdk-drawable>}) (colormap@tie{}@code{<gdk-colormap>})
@deffnx Method set-colormap
Sets the colormap associated with @var{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 @code{<gdk-gc>} to draw to a drawable, or copying one drawable
to another, the colormaps should match.

@table @var
@item drawable
a @code{<gdk-drawable>}

@item colormap
a @code{<gdk-colormap>}

@end table

@end deffn

@deffn Function gdk-drawable-get-colormap  (self@tie{}@code{<gdk-drawable>}) @result{}@tie{} (ret@tie{}@code{<gdk-colormap>})
@deffnx Method get-colormap
Gets the colormap for @var{drawable}, if one is set; returns @samp{@code{#f}}
otherwise.

@table @var
@item drawable
a @code{<gdk-drawable>}

@item ret
the colormap, or @samp{@code{#f}}

@end table

@end deffn

@deffn Function gdk-drawable-get-depth  (self@tie{}@code{<gdk-drawable>}) @result{}@tie{} (ret@tie{}@code{int})
@deffnx 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.

@table @var
@item drawable
a @code{<gdk-drawable>}

@item ret
number of bits per pixel

@end table

@end deffn

@deffn Function gdk-drawable-get-size  (self@tie{}@code{<gdk-drawable>}) @result{}@tie{} (width@tie{}@code{int}) (height@tie{}@code{int})
@deffnx Method get-size
Fills *@var{width} and *@var{height} with the size of @var{drawable}.
@var{width} or @var{height} can be @samp{@code{#f}} if you only want the other
one.

On the X11 platform, if @var{drawable} is a @code{<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.

@table @var
@item drawable
a @code{<gdk-drawable>}

@item width
location to store drawable's width, or @samp{@code{#f}}

@item height
location to store drawable's height, or @samp{@code{#f}}

@end table

@end deffn

@deffn Function gdk-drawable-get-clip-region  (self@tie{}@code{<gdk-drawable>}) @result{}@tie{} (ret@tie{}@code{<gdk-region>})
@deffnx 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.

@table @var
@item drawable
a @code{<gdk-drawable>}

@item ret
a @code{<gdk-region>}. This must be freed with @code{gdk-region-destroy} when
you are done.

@end table

@end deffn

@deffn Function gdk-drawable-get-visible-region  (self@tie{}@code{<gdk-drawable>}) @result{}@tie{} (ret@tie{}@code{<gdk-region>})
@deffnx 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.

@table @var
@item drawable
a @code{<gdk-drawable>}

@item ret
a @code{<gdk-region>}. This must be freed with @code{gdk-region-destroy} when
you are done.

@end table

@end deffn

@deffn Function gdk-draw-point  (drawable@tie{}@code{<gdk-drawable>}) (gc@tie{}@code{<gdk-gc>}) (x@tie{}@code{int}) (y@tie{}@code{int})
Draws a point, using the foreground color and other attributes of the
@code{<gdk-gc>}.

@table @var
@item drawable
a @code{<gdk-drawable>} (a @code{<gdk-window>} or a @code{<gdk-pixmap>}).

@item gc
a @code{<gdk-gc>}.

@item x
the x coordinate of the point.

@item y
the y coordinate of the point.

@end table

@end deffn

@deffn Function gdk-draw-line  (drawable@tie{}@code{<gdk-drawable>}) (gc@tie{}@code{<gdk-gc>}) (x1_@tie{}@code{int}) (y1_@tie{}@code{int}) (x2_@tie{}@code{int}) (y2_@tie{}@code{int})
Draws a line, using the foreground color and other attributes of the
@code{<gdk-gc>}.

@table @var
@item drawable
a @code{<gdk-drawable>} (a @code{<gdk-window>} or a @code{<gdk-pixmap>}).

@item gc
a @code{<gdk-gc>}.

@item x1
the x coordinate of the start point.

@item y1
the y coordinate of the start point.

@item x2
the x coordinate of the end point.

@item y2
the y coordinate of the end point.

@end table

@end deffn

@deffn Function gdk-draw-pixbuf  (drawable@tie{}@code{<gdk-drawable>}) (gc@tie{}@code{<gdk-gc>}) (pixbuf@tie{}@code{<gdk-pixbuf>}) (src_x@tie{}@code{int}) (src_y@tie{}@code{int}) (dest_x@tie{}@code{int}) (dest_y@tie{}@code{int}) (width@tie{}@code{int}) (height@tie{}@code{int}) (dither@tie{}@code{<gdk-rgb-dither>}) (x_dither@tie{}@code{int}) (y_dither@tie{}@code{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-@samp{@code{#f}}
window argument. Otherwise a colormap must be set on them with
@code{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 @var{gc} is ignored, but clip rectangles and clip regions work
fine.

@table @var
@item drawable
Destination drawable.

@item gc
a @code{<gdk-gc>}, used for clipping, or @samp{@code{#f}}

@item pixbuf
a @code{<gdk-pixbuf>}

@item src-x
Source X coordinate within pixbuf.

@item src-y
Source Y coordinates within pixbuf.

@item dest-x
Destination X coordinate within drawable.

@item dest-y
Destination Y coordinate within drawable.

@item width
Width of region to render, in pixels, or -1 to use pixbuf width.

@item height
Height of region to render, in pixels, or -1 to use pixbuf height.

@item dither
Dithering mode for @code{<gdk-rgb>}.

@item x-dither
X offset for dither.

@item y-dither
Y offset for dither.

@end table

Since 2.2

@end deffn

@deffn Function gdk-draw-rectangle  (drawable@tie{}@code{<gdk-drawable>}) (gc@tie{}@code{<gdk-gc>}) (filled@tie{}@code{bool}) (x@tie{}@code{int}) (y@tie{}@code{int}) (width@tie{}@code{int}) (height@tie{}@code{int})
Draws a rectangular outline or filled rectangle, using the foreground color and
other attributes of the @code{<gdk-gc>}.

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

@table @var
@item drawable
a @code{<gdk-drawable>} (a @code{<gdk-window>} or a @code{<gdk-pixmap>}).

@item gc
a @code{<gdk-gc>}.

@item filled
@samp{@code{#t}} if the rectangle should be filled.

@item x
the x coordinate of the left edge of the rectangle.

@item y
the y coordinate of the top edge of the rectangle.

@item width
the width of the rectangle.

@item height
the height of the rectangle.

@end table

@end deffn

@deffn Function gdk-draw-arc  (drawable@tie{}@code{<gdk-drawable>}) (gc@tie{}@code{<gdk-gc>}) (filled@tie{}@code{bool}) (x@tie{}@code{int}) (y@tie{}@code{int}) (width@tie{}@code{int}) (height@tie{}@code{int}) (angle1@tie{}@code{int}) (angle2@tie{}@code{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.

@table @var
@item drawable
a @code{<gdk-drawable>} (a @code{<gdk-window>} or a @code{<gdk-pixmap>}).

@item gc
a @code{<gdk-gc>}.

@item filled
@samp{@code{#t}} if the arc should be filled, producing a 'pie slice'.

@item x
the x coordinate of the left edge of the bounding rectangle.

@item y
the y coordinate of the top edge of the bounding rectangle.

@item width
the width of the bounding rectangle.

@item height
the height of the bounding rectangle.

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

@item angle2
the end angle of the arc, relative to @var{angle1}, in 1/64ths of a degree.

@end table

@end deffn

@deffn Function gdk-draw-glyphs  (drawable@tie{}@code{<gdk-drawable>}) (gc@tie{}@code{<gdk-gc>}) (font@tie{}@code{<pango-font>}) (x@tie{}@code{int}) (y@tie{}@code{int}) (glyphs@tie{}@code{<pango-glyph-string>})
This is a low-level function; 99% of text rendering should be done using
@code{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
@code{gdk-draw-layout} instead of this function, @code{gdk-draw-layout} handles
the details.

@table @var
@item drawable
a @code{<gdk-drawable>}

@item gc
a @code{<gdk-gc>}

@item font
font to be used

@item x
X coordinate of baseline origin

@item y
Y coordinate of baseline origin

@item glyphs
the glyph string to draw

@end table

@end deffn

@deffn Function gdk-draw-glyphs-transformed  (drawable@tie{}@code{<gdk-drawable>}) (gc@tie{}@code{<gdk-gc>}) (matrix@tie{}@code{<pango-matrix>}) (font@tie{}@code{<pango-font>}) (x@tie{}@code{int}) (y@tie{}@code{int}) (glyphs@tie{}@code{<pango-glyph-string>})
Renders a @code{<pango-glyph-string>} onto a drawable, possibly transforming the
layed-out coordinates through a transformation matrix. Note that the
transformation matrix for @var{font} is not changed, so to produce correct
rendering results, the @var{font} must have been loaded using a
@code{<pango-context>} with an identical transformation matrix to that passed in
to this function.

See also @code{gdk-draw-glyphs}, @code{gdk-draw-layout}.

@table @var
@item drawable
a @code{<gdk-drawable>}

@item gc
a @code{<gdk-gc>}

@item matrix
a @code{<pango-matrix>}, or @samp{@code{#f}} to use an identity transformation

@item font
the font in which to draw the string

@item x
the x position of the start of the string (in Pango units in user space
coordinates)

@item y
the y position of the baseline (in Pango units in user space coordinates)

@item glyphs
the glyph string to draw

@end table

Since 2.6

@end deffn

@deffn Function gdk-draw-layout-line  (drawable@tie{}@code{<gdk-drawable>}) (gc@tie{}@code{<gdk-gc>}) (x@tie{}@code{int}) (y@tie{}@code{int}) (line@tie{}@code{<pango-layout-line>})
Render a @code{<pango-layout-line>} onto an GDK drawable

If the layout's @code{<pango-context>} has a transformation matrix set, then
@var{x} and @var{y} specify the position of the left edge of the baseline (left
is in before-tranform user coordinates) in after-transform device coordinates.

@table @var
@item drawable
the drawable on which to draw the line

@item gc
base graphics to use

@item x
the x position of start of string (in pixels)

@item y
the y position of baseline (in pixels)

@item line
a @code{<pango-layout-line>}

@end table

@end deffn

@deffn Function gdk-draw-layout-line-with-colors  (drawable@tie{}@code{<gdk-drawable>}) (gc@tie{}@code{<gdk-gc>}) (x@tie{}@code{int}) (y@tie{}@code{int}) (line@tie{}@code{<pango-layout-line>}) (foreground@tie{}@code{<gdk-color>}) (background@tie{}@code{<gdk-color>})
Render a @code{<pango-layout-line>} onto a @code{<gdk-drawable>}, overriding the
layout's normal colors with @var{foreground} and/or @var{background}.
@var{foreground} and @var{background} need not be allocated.

If the layout's @code{<pango-context>} has a transformation matrix set, then
@var{x} and @var{y} specify the position of the left edge of the baseline (left
is in before-tranform user coordinates) in after-transform device coordinates.

@table @var
@item drawable
the drawable on which to draw the line

@item gc
base graphics to use

@item x
the x position of start of string (in pixels)

@item y
the y position of baseline (in pixels)

@item line
a @code{<pango-layout-line>}

@item foreground
foreground override color, or @samp{@code{#f}} for none

@item background
background override color, or @samp{@code{#f}} for none

@end table

@end deffn

@deffn Function gdk-draw-layout  (drawable@tie{}@code{<gdk-drawable>}) (gc@tie{}@code{<gdk-gc>}) (x@tie{}@code{int}) (y@tie{}@code{int}) (layout@tie{}@code{<pango-layout>})
Render a @code{<pango-layout>} onto a GDK drawable

If the layout's @code{<pango-context>} has a transformation matrix set, then
@var{x} and @var{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 @code{<pango-layout>} is
@code{gtk-widget-create-pango-layout}.

@table @var
@item drawable
the drawable on which to draw string

@item gc
base graphics context to use

@item x
the X position of the left of the layout (in pixels)

@item y
the Y position of the top of the layout (in pixels)

@item layout
a @code{<pango-layout>}

@end table

@end deffn

@deffn Function gdk-draw-layout-with-colors  (drawable@tie{}@code{<gdk-drawable>}) (gc@tie{}@code{<gdk-gc>}) (x@tie{}@code{int}) (y@tie{}@code{int}) (layout@tie{}@code{<pango-layout>}) (foreground@tie{}@code{<gdk-color>}) (background@tie{}@code{<gdk-color>})
Render a @code{<pango-layout>} onto a @code{<gdk-drawable>}, overriding the
layout's normal colors with @var{foreground} and/or @var{background}.
@var{foreground} and @var{background} need not be allocated.

If the layout's @code{<pango-context>} has a transformation matrix set, then
@var{x} and @var{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 @code{<pango-layout>} is
@code{gtk-widget-create-pango-layout}.

@table @var
@item drawable
the drawable on which to draw string

@item gc
base graphics context to use

@item x
the X position of the left of the layout (in pixels)

@item y
the Y position of the top of the layout (in pixels)

@item layout
a @code{<pango-layout>}

@item foreground
foreground override color, or @samp{@code{#f}} for none

@item background
background override color, or @samp{@code{#f}} for none

@end table

@end deffn

@deffn Function gdk-draw-string  (drawable@tie{}@code{<gdk-drawable>}) (font@tie{}@code{<gdk-font>}) (gc@tie{}@code{<gdk-gc>}) (x@tie{}@code{int}) (y@tie{}@code{int}) (string@tie{}@code{mchars})
@samp{gdk_draw_string} is deprecated and should not be used in newly-written
code. Use @code{gdk-draw-layout} instead.

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

@table @var
@item drawable
a @code{<gdk-drawable>} (a @code{<gdk-window>} or a @code{<gdk-pixmap>}).

@item font
a @code{<gdk-font>}.

@item gc
a @code{<gdk-gc>}.

@item x
the x coordinate of the left edge of the text.

@item y
the y coordinate of the baseline of the text.

@item string
the string of characters to draw.

@end table

@end deffn

@deffn Function gdk-draw-drawable  (drawable@tie{}@code{<gdk-drawable>}) (gc@tie{}@code{<gdk-gc>}) (src@tie{}@code{<gdk-drawable>}) (xsrc@tie{}@code{int}) (ysrc@tie{}@code{int}) (xdest@tie{}@code{int}) (ydest@tie{}@code{int}) (width@tie{}@code{int}) (height@tie{}@code{int})
Copies the @var{width} x @var{height} region of @var{src} at coordinates
(@var{xsrc}, @var{ysrc}) to coordinates (@var{xdest}, @var{ydest}) in
@var{drawable}. @var{width} and/or @var{height} may be given as -1, in which
case the entire @var{src} drawable will be copied.

Most fields in @var{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 @code{<gdk-gc>}, set the fill mode to
@samp{GDK_STIPPLED}, and then draw the rectangle.

@table @var
@item drawable
a @code{<gdk-drawable>}

@item gc
a @code{<gdk-gc>} sharing the drawable's visual and colormap

@item src
the source @code{<gdk-drawable>}, which may be the same as @var{drawable}

@item xsrc
X position in @var{src} of rectangle to draw

@item ysrc
Y position in @var{src} of rectangle to draw

@item xdest
X position in @var{drawable} where the rectangle should be drawn

@item ydest
Y position in @var{drawable} where the rectangle should be drawn

@item width
width of rectangle to draw, or -1 for entire @var{src} width

@item height
height of rectangle to draw, or -1 for entire @var{src} height

@end table

@end deffn

@deffn Function gdk-draw-image  (drawable@tie{}@code{<gdk-drawable>}) (gc@tie{}@code{<gdk-gc>}) (image@tie{}@code{<gdk-image>}) (xsrc@tie{}@code{int}) (ysrc@tie{}@code{int}) (xdest@tie{}@code{int}) (ydest@tie{}@code{int}) (width@tie{}@code{int}) (height@tie{}@code{int})
Draws a @code{<gdk-image>} onto a drawable. The depth of the @code{<gdk-image>}
must match the depth of the @code{<gdk-drawable>}.

@table @var
@item drawable
a @code{<gdk-drawable>} (a @code{<gdk-window>} or a @code{<gdk-pixmap>}).

@item gc
a @code{<gdk-gc>}.

@item image
the @code{<gdk-image>} to draw.

@item xsrc
the left edge of the source rectangle within @var{image}.

@item ysrc
the top of the source rectangle within @var{image}.

@item xdest
the x coordinate of the destination within @var{drawable}.

@item ydest
the y coordinate of the destination within @var{drawable}.

@item width
the width of the area to be copied, or -1 to make the area extend to the right
edge of @var{image}.

@item height
the height of the area to be copied, or -1 to make the area extend to the bottom
edge of @var{image}.

@end table

@end deffn

@deffn Function gdk-drawable-get-image  (self@tie{}@code{<gdk-drawable>}) (x@tie{}@code{int}) (y@tie{}@code{int}) (width@tie{}@code{int}) (height@tie{}@code{int}) @result{}@tie{} (ret@tie{}@code{<gdk-image>})
@deffnx Method get-image
A @code{<gdk-image>} stores client-side image data (pixels). In contrast,
@code{<gdk-pixmap>} and @code{<gdk-window>} are server-side objects.
@code{gdk-drawable-get-image} obtains the pixels from a server-side drawable as
a client-side @code{<gdk-image>}. The format of a @code{<gdk-image>} depends on
the @code{<gdk-visual>} of the current display, which makes manipulating
@code{<gdk-image>} extremely difficult; therefore, in most cases you should use
@code{gdk-pixbuf-get-from-drawable} instead of this lower-level function. A
@code{<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.

@var{x}, @var{y}, @var{width}, and @var{height} define the region of
@var{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 @code{<gdk-window>} and partially offscreen or
obscured, then the obscured portions of the returned image will contain
undefined data.

@table @var
@item drawable
a @code{<gdk-drawable>}

@item x
x coordinate on @var{drawable}

@item y
y coordinate on @var{drawable}

@item width
width of region to get

@item height
height or region to get

@item ret
a @code{<gdk-image>} containing the contents of @var{drawable}

@end table

@end deffn

@deffn Function gdk-drawable-copy-to-image  (self@tie{}@code{<gdk-drawable>}) (image@tie{}@code{<gdk-image>}) (src_x@tie{}@code{int}) (src_y@tie{}@code{int}) (dest_x@tie{}@code{int}) (dest_y@tie{}@code{int}) (width@tie{}@code{int}) (height@tie{}@code{int}) @result{}@tie{} (ret@tie{}@code{<gdk-image>})
@deffnx Method copy-to-image
Copies a portion of @var{drawable} into the client side image structure
@var{image}. If @var{image} is @samp{@code{#f}}, creates a new image of size
@var{width} x @var{height} and copies into that. See
@code{gdk-drawable-get-image} for further details.

@table @var
@item drawable
a @code{<gdk-drawable>}

@item image
a @code{<gdk-drawable>}, or @samp{@code{#f}} if a new @var{image} should be
created.

@item src-x
x coordinate on @var{drawable}

@item src-y
y coordinate on @var{drawable}

@item dest-x
x coordinate within @var{image}. Must be 0 if @var{image} is @samp{@code{#f}}

@item dest-y
y coordinate within @var{image}. Must be 0 if @var{image} is @samp{@code{#f}}

@item width
width of region to get

@item height
height or region to get

@item ret
@var{image}, or a new a @code{<gdk-image>} containing the contents of
@var{drawable}

@end table

Since 2.4

@end deffn


@c %end of fragment
