Xfce Foundation Classes
Main Page  | Index |  Namespace List  |  Alphabetical List  |  Class List  |  File List


Xfc::Gdk::Drawable Class Reference

A GdkDrawable C++ wrapper class. More...

#include <xfc/gdk/drawable.hh>

Inheritance diagram for Xfc::Gdk::Drawable:

Xfc::G::Object Xfc::G::TypeInstance Xfc::Trackable Xfc::Gdk::Pixmap Xfc::Gdk::Window Xfc::Gdk::Bitmap List of all members.

Public Member Functions

Constructors
Accessors
Methods
RGB Methods

Protected Member Functions

Constructors

Detailed Description

A GdkDrawable C++ wrapper class.

Drawable provides 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 of the GDK reference documentationfor more information.

Constructor & Destructor Documentation

Xfc::Gdk::Drawable::Drawable (  GdkDrawable *  drawable,
bool  owns_reference = true
)  [explicit, protected]
 

Construct a new Drawable from an existing GdkDrawable.

Parameters:
drawable A pointer to a GdkDrawable.
owns_reference Set false if the initial reference count is floating, set true if it's not.
The drawable can be a newly created GdkDrawable or an existing GdkDrawable. (see G::Object::Object).

Member Function Documentation

void Xfc::Gdk::Drawable::copy_to_image (  Image &  image,
const Rectangle &  src_rect,
int  dest_x,
int  dest_y
) 
 

Copies a portion of the drawable into the specified client side image (see get_image() for further details).

Parameters:
image A Gdk::Image to copy the drawable portion to.
src_rect The rectangular coordinates on the drawable.
dest_x The x coordinate within the image.
dest_y The y coordinate within the image.

void Xfc::Gdk::Drawable::copy_to_image (  Image &  image,
int  src_x,
int  src_y,
int  dest_x,
int  dest_y,
int  width,
int  height
) 
 

Copies a portion of the drawable into the specified client side image (see get_image() for further details).

Parameters:
image A Gdk::Image to copy the drawable portion to.
src_x The x coordinate on the drawable.
src_y The y coordinate on the drawable.
dest_x The x coordinate within the image.
dest_y The y coordinate within the image.
width The width of the region to get.
height The height of the region to get.

void Xfc::Gdk::Drawable::draw_arc (  const GC &  gc,
const Rectangle &  rectangle,
int  angle1,
int  angle2,
bool  filled = true
) 
 

Draws an arc or a filled 'pie slice'.

Parameters:
gc A GC.
rectangle A Rectangle holding the position and size of the bounding rectangle of the ellipse.
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.
filled Set true if the arc should be filled, producing a '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.

void Xfc::Gdk::Drawable::draw_arc (  const GC &  gc,
int  x,
int  y,
int  width,
int  height,
int  angle1,
int  angle2,
bool  filled = true
) 
 

Draws an arc or a filled 'pie slice'.

Parameters:
gc A GC.
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.
filled Set true if the arc should be filled, producing a '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.

void Xfc::Gdk::Drawable::draw_drawable (  const GC &  gc,
const Drawable &  src,
const Rectangle &  src_rect,
int  xdest,
int  ydest
) 
 

Copies the dest.width x dest.height region of src at coordinates (xsrc, ysrc) to coordinates (dest.x, dest.y) in the drawable.

Parameters:
gc A GC sharing the drawable's visual and colormap.
src Another Drawable.
src_rect A rectangle holding the position and size of the src region to draw in the drawable.
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.
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 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 GC, then use draw_rectangle() to draw a rectangle clipped to the bitmap.

void Xfc::Gdk::Drawable::draw_drawable (  const GC &  gc,
const Drawable &  src,
int  xsrc,
int  ysrc,
int  xdest,
int  ydest,
int  width,
int  height
) 
 

Copies the width x height region of src at coordinates (xsrc, ysrc) to coordinates (xdest, ydest) in the drawable.

Parameters:
gc A GC sharing the drawable's visual and colormap.
src Another Drawable.
xsrc The X position in src of the rectangle to draw.
ysrc The Y position in src of the 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 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 a clip mask on your GC, then use draw_rectangle() to draw a rectangle clipped to the bitmap.

void Xfc::Gdk::Drawable::draw_glyphs (  const GC &  gc,
const Pango::Font &  font,
int  x,
int  y,
const Pango::GlyphString &  glyphs,
const Pango::Matrix *  matrix = 0
) 
 

Renders a Pango::GlyphString onto a drawable, possibly transforming the layed-out coordinates through a transformation matrix.

Parameters:
gc A GC.
font The font in which to draw the string.
x The X coordinate of the start of the string (in Pango units in user space coordinates).
y The Y coordinate of the baseline (in Pango units in user space coordinates).
glyphs The glyph string to draw.
matrix A Pango::Matrix, or null.
A glyph is a character in a font. This method 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 draw_layout() instead of this method, draw_layout() handles the details.

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 method. This is a low-level method; 99% of text rendering should be done using draw_layout() instead.

void Xfc::Gdk::Drawable::draw_gray_image (  const GC &  gc,
int  x,
int  y,
int  width,
int  height,
RgbDither  dith,
unsigned char *  buf,
int  rowstride
) 
 

Draws a grayscale image in the drawable.

Parameters:
gc The 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 RgbDither value, selecting the desired dither mode.
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.

void Xfc::Gdk::Drawable::draw_image (  const GC &  gc,
const Image &  image,
int  xsrc,
int  ysrc,
int  xdest,
int  ydest,
int  width,
int  height
) 
 

Draws an Image onto the drawable.

Parameters:
gc A GC.
image The Gdk::Image to draw.
xsrc The left edge of the source rectangle within the image.
ysrc The top of the source rectangle within the image.
xdest The x coordinate of the destination within the drawable.
ydest The y coordinate of the destination within the 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 depth of the Image must match the depth of the Drawable.

void Xfc::Gdk::Drawable::draw_indexed_image (  const GC &  gc,
int  x,
int  y,
int  width,
int  height,
RgbDither  dith,
unsigned char *  buf,
int  rowstride,
GdkRgbCmap *  cmap
) 
 

Draws an indexed image in the drawable, using a GdkRgbCmap to assign actual colors to the color indices.

Parameters:
gc The 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 RgbDither 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.
cmap The GdkRgbCmap used to assign colors to the color indices.

void Xfc::Gdk::Drawable::draw_layout (  const GC &  gc,
int  x,
int  y,
const Pango::Layout &  layout,
const Color *  foreground = 0,
const Color *  background = 0
) 
 

Render a Pango::Layout onto the drawable.

Parameters:
gc The 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 The foreground override color, or null for none.
background The background override color, or null for none
If foreground and/or background colors are specified these will override the layout's normal colors. The colors need not be allocated.

void Xfc::Gdk::Drawable::draw_layout_line (  const GC &  gc,
int  x,
int  y,
const Pango::LayoutLine &  line,
const Color *  foreground = 0,
const Color *  background = 0
) 
 

Render a Pango::LayoutLine onto the drawable.

Parameters:
gc The base graphics context to use.
x The X position of the start of string (in pixels).
y The Y position of the baseline (in pixels).
line A Pango::LayoutLine.
foreground The foreground override color, or null for none.
background The background override color, or null for none
If foreground and/or background colors are specified these will override the layout's normal colors. The colors need not be allocated.

void Xfc::Gdk::Drawable::draw_line (  const GC &  gc,
const Segment &  seg
) 
 

Draws a line, using the foreground color and other attributes of the GC.

Parameters:
gc A GC.
seg A Segment that holds the start and end coordinates of the line.

void Xfc::Gdk::Drawable::draw_line (  const GC &  gc,
int  x1,
int  y1,
int  x2,
int  y2
) 
 

Draws a line, using the foreground color and other attributes of the GC.

Parameters:
gc A 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.

void Xfc::Gdk::Drawable::draw_lines (  const GC &  gc,
const std::vector< Point > &  points
) 
 

Draws a series of lines connecting the given points.

Parameters:
gc A GC.
points A reference to a vector of Point holding the endpoints of the lines.
The way in which joins between lines are drawn is determined by the CapStyle value in the GC. This can be set with Gdk::GC::set_line_attributes().

void Xfc::Gdk::Drawable::draw_pixbuf (  const GC *  gc,
const Pixbuf &  pixbuf,
int  src_x,
int  src_y,
int  dest_x,
int  dest_y,
int  width,
int  height,
RgbDither  dither,
int  x_dither,
int  y_dither
) 
 

Renders a rectangular portion of a pixbuf to a drawable.

Parameters:
gc A GC, used for clipping, or null.
pixbuf A Pixbuf.
src_x The source X coordinate within pixbuf.
src_y The source Y coordinates within pixbuf.
dest_x The destination X coordinate within drawable.
dest_y The destination Y coordinate within drawable.
width The width of region to render, in pixels, or -1 to use pixbuf width.
height The height of region to render, in pixels, or -1 to use pixbuf height.
dither The dithering mode for GdkRGB.
x_dither The X offset for dither.
y_dither The Y offset for dither.
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-null window argument. Otherwise a colormap must be set on them with set_colormap(). On older X servers, rendering pixbufs with an alpha channel involves round trips to the X server, and may be somewhat slow.

void Xfc::Gdk::Drawable::draw_point (  const GC &  gc,
const Point &  point
) 
 

Draws a point, using the foreground color and other attributes of the GC.

Parameters:
gc A GC.
point A Point holding the X and Y coordinates of the point.

void Xfc::Gdk::Drawable::draw_point (  const GC &  gc,
int  x,
int  y
) 
 

Draws a point, using the foreground color and other attributes of the GC.

Parameters:
gc A GC.
x The X coordinate of the point.
y The y coordinate of the point.

void Xfc::Gdk::Drawable::draw_points (  const GC &  gc,
const std::vector< Point > &  points
) 
 

Draws a number of points, using the foreground color and other attributes of the GC.

Parameters:
gc A GC.
points A reference to a vector of Point holding the points to draw.

void Xfc::Gdk::Drawable::draw_polygon (  const GC &  gc,
const std::vector< Point > &  points,
bool  filled = true
) 
 

Draws an outlined or filled polygon.

Parameters:
gc A GC.
points A reference to a vector of Point specifying the points making up the polygon.
filled Set true if the polygon should be filled.
The polygon is closed automatically, connecting the last point to the first point if necessary.

void Xfc::Gdk::Drawable::draw_rectangle (  const GC &  gc,
const Rectangle &  rectangle,
bool  filled = true
) 
 

Draws a rectangular outline or filled rectangle, using the foreground color and other attributes of the GC.

Parameters:
gc A GC.
rectangle A Rectangle holding the position and size of the rectangle to draw.
filled Set true if the rectangle should be filled.
A rectangle drawn filled is 1 pixel smaller in both dimensions than a rectangle outlined. Calling window->draw_rectangle(gc, 0, 0, 20, 20, true) results in a filled rectangle 20 pixels wide and 20 pixels high. Calling window->gdk_draw_rectangle(gc, 0, 0, 20, 20, false) 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.

void Xfc::Gdk::Drawable::draw_rectangle (  const GC &  gc,
int  x,
int  y,
int  width,
int  height,
bool  filled = true
) 
 

Draws a rectangular outline or filled rectangle, using the foreground color and other attributes of the GC.

Parameters:
gc A GC.
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.
filled Set true if the rectangle should be filled.
A rectangle drawn filled is 1 pixel smaller in both dimensions than a rectangle outlined. Calling window->draw_rectangle(gc, 0, 0, 20, 20, true) results in a filled rectangle 20 pixels wide and 20 pixels high. Calling window->gdk_draw_rectangle(gc, 0, 0, 20, 20, false) 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.

void Xfc::Gdk::Drawable::draw_rgb_32_image (  const GC &  gc,
int  x,
int  y,
int  width,
int  height,
RgbDither  dith,
unsigned char *  buf,
int  rowstride
) 
 

Draws a padded RGB image in the drawable.

Parameters:
gc The 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 RgbDither value, selecting the desired dither mode.
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.
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. It's unlikely that this method will give significant performance gains in practice. In my experience, the performance gain from having pixels aligned to 32-bit boundaries is cancelled out by the increased memory bandwidth.

void Xfc::Gdk::Drawable::draw_rgb_32_image_dithalign (  const GC &  gc,
int  x,
int  y,
int  width,
int  height,
RgbDither  dith,
unsigned char *  buf,
int  rowstride,
int  xdith,
int  ydith
) 
 

Like draw_rgb_32_image(), but allows you to specify the dither offsets (see dar_rgb_image_dithalign()).

Parameters:
gc A gaphics context.
x The X coordinate on drawable where image should go.
y The Y coordinate on drawable where image should go.
width The width of area of image to draw.
height The height of area of image to draw.
dith The dithering mode.
buf The RGB image data.
rowstride The rowstride of the RGB image data.
xdith The X dither offset.
ydith The Y dither offset.

void Xfc::Gdk::Drawable::draw_rgb_image (  const GC &  gc,
int  x,
int  y,
int  width,
int  height,
RgbDither  dith,
unsigned char *  rgb_buf,
int  rowstride
) 
 

Draws an RGB image in the drawable.

Parameters:
gc The 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 An RgbDither value, selecting the desired dither mode.
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.
This is the core GdkRGB method, and likely the only one you will need to use. The rowstride parameter allows for lines to be aligned more flexibly. For example, lines may be allocated to begin on 32-bit boundaries, even if the width of the rectangle is odd. Rowstride is also useful when drawing a subrectangle of a larger image in memory. Finally, to replicate the same line a number of times, the trick of setting rowstride to 0 is allowed.

In general, for 0 <= i < width and 0 <= j < height, the pixel (x + i, y + j) is colored with red value rgb_buf[j * rowstride + i * 3], green value rgb_buf[j * rowstride + i * 3 + 1], and blue value rgb_buf[j * rowstride + i * 3 + 2].

void Xfc::Gdk::Drawable::draw_rgb_image_dithalign (  const GC &  gc,
int  x,
int  y,
int  width,
int  height,
RgbDither  dith,
unsigned char *  rgb_buf,
int  rowstride,
int  xdith,
int  ydith
) 
 

Draws an RGB image in the drawable, with an adjustment for dither alignment.

Parameters:
gc The 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 An RgbDither value, selecting the desired dither mode.
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.
xdith An x offset for dither alignment.
ydith A y offset 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.

void Xfc::Gdk::Drawable::draw_segments (  const GC &  gc,
const std::vector< Segment > &  segs
) 
 

Draws a number of unconnected lines.

Parameters:
gc A GC.
segs A reference to a vector of Segment specifying the start and end points of the lines.

void Xfc::Gdk::Drawable::draw_trapezoids (  const GC &  gc,
std::vector< Trapezoid > &  trapezoids
) 
 

Draws a set of anti-aliased trapezoids.

Parameters:
gc A GC.
trapezoids A vector of Trapezoid
The trapezoids are combined using saturation addition, then drawn over the background as a set. This is low level functionality used internally to implement rotated underlines and backgrouds when rendering a Pango::Layout and is likely not useful for applications.

Pointer<Region> Xfc::Gdk::Drawable::get_clip_region (   )  const
 

Computes the region of a drawable that potentially can be written to by drawing primitives.

Returns:
A smart pointer to the newly allocated Region.
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.

Colormap* Xfc::Gdk::Drawable::get_colormap (   )  const
 

Gets the Colormap for the drawable, if one is set; returns null otherwise.

Returns:
The colormap, or null.

int Xfc::Gdk::Drawable::get_depth (   )  const
 

Obtains the bit depth of the drawable, that is, the number of bits that make up a pixel in the drawable's visual.

Returns:
The number of bits per pixel.
Examples are 8 bits per pixel, 24 bits per pixel, etc.

Display* Xfc::Gdk::Drawable::get_display (   )  const
 

Gets the Display associated with the drawable.

Returns:
The Display associated with the drawable.

Pointer<Image> Xfc::Gdk::Drawable::get_image (  int  x,
int  y,
int  width,
int  height
)  const
 

Obtains the pixels from a server-side drawable as a client-side Gdk::Image.

Parameters:
x The X coordinate on the drawable.
y The Y coordinate on the drawable.
width The width of the region to get.
height The height of the region to get.
Returns:
A smart pointer to a new Gdk::Image containing the contents of the drawable.
A Gdk::Image stores client-side image data (pixels). In contrast, Gdk::Pixmap and Gdk::Window are server-side objects. The format of a Gdk::Image depends on the 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 method. 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.

The x, y, width, and height arguments 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 method 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.

Screen* Xfc::Gdk::Drawable::get_screen (   )  const
 

Gets the Screen associated with the drawable.

Returns:
The Screen associated with the drawable.

void Xfc::Gdk::Drawable::get_size (  int *  width,
int *  height
)  const
 

Fills width and height with the size of drawable; width or height can be null if you only want the other one.

Parameters:
width The location to store drawable's width, or null.
height The location to store drawable's height, or null.
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.

Pointer<Region> Xfc::Gdk::Drawable::get_visible_region (   )  const
 

Computes the region of a drawable that is potentially visible.

Returns:
A smart pointer to the newly allocated Region.
This does not necessarily take into account if the window is obscured by other windows, but no area outside of this region is visible.

const Visual* Xfc::Gdk::Drawable::get_visual (   )  const
 

Gets the Visual describing the pixel format of the drawable.

Returns:
A Visual.

void Xfc::Gdk::Drawable::set_colormap (  Colormap *  colormap  ) 
 

Sets the colormap associated with the drawable.

Parameters:
colormap A Colormap.
Normally this will happen automatically when the drawable is created; you only need to use this method 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 GdkGC to draw to a drawable, or copying one drawable to another, the colormaps should match.

The documentation for this class was generated from the following file: Xfce Foundation Classes
Copyright © 2004-2005 The XFC Development Team XFC 4.3