'Core' Structures

Modules
	structures

Typedefs
typedef struct s_WBGC *	WBGC
	internal wrapper struct for GC with local cache More...
typedef struct s_WB_POINT	WB_POINT
	internal wrapper struct for 'point' definition More...
typedef struct s_WB_EXTENT	WB_EXTENT
	internal wrapper struct for 'extent' definition More...
typedef struct s_WB_RECT	WB_RECT
	internal wrapper struct for 'rectangle' definition More...
typedef struct s_WB_GEOM	WB_GEOM
	internal wrapper struct for X11 'geometry' definition More...

Detailed Description

Structures that help to implement 'Core' functionality

Typedef Documentation

WB_EXTENT

WB_EXTENT

internal wrapper struct for 'extent' definition

The extent structure has been defined primarily for convenience, so that specific coding methods that work well in GUI environments that use 'extents' can easily be ported into this environment.

typedef struct s_WB_EXTENT
{
  unsigned int width;   // the 'width' value of the extent.
  unsigned int height;  // the 'height' value of the extent.
} WB_EXTENT;

Definition at line 79 of file font_helper.h.

WB_GEOM

WB_GEOM

internal wrapper struct for X11 'geometry' definition

The geometry structure is a wrapper for the X11 functions that specify the individual parameters for a geometry, such as XGetGeometry. Instead of passing 5 integers, you pass the pointer to a structure for the X11workbench API functions. This provides many advantages over the 'individual parameter' method as well as providing a structure for cacheing geometry information.

typedef struct s_WB_GEOM
{
  int x, y;
  unsigned int width, height, border;
} WB_GEOM;

Use of 'int' and 'unsigned int' for the various parameter is consistent with the various 'Geom' functions, which typically use 'int *' for returned parameters, as shown:

Status XGetGeometry(Display *display, Drawable d, Window *root_return,
                    int *x_return, int *y_return,
                    unsigned int *width_return, unsigned int *height_return,
                    unsigned int *border_return, unsigned int *depth_return);

WB_POINT

WB_POINT

internal wrapper struct for 'point' definition

The point structure has been defined primarily for convenience, so that specific coding methods that work well in GUI environments that use 'points' can easily be ported into this environment.

typedef struct s_WB_POINT
{
  int x;   // the 'x' value of the point.  can be negative.
  int y;   // the 'y' value of the point.  can be negative.
} WB_POINT;

Note that this is different from an XPoint structure, which is defined as

typedef struct
{
  short x, y;
} XPoint;

WB_RECT

WB_RECT

internal wrapper struct for 'rectangle' definition

The rectangle structure has been defined primarily for convenience, so that specific coding methods that work well in GUI environments that use rectangles (instead of 'geometry') can easily be ported into this environment.

typedef struct s_WB_RECT
{
  int left, top, right, bottom;
} WB_RECT;

Note that this is different from an XRectangle structure, which is defined as

typedef struct
{
  short x, y;
  unsigned short width, height;
} XRectangle;

WBGC

WBGC

internal wrapper struct for GC with local cache

The WBGC data type (and its associated structure) represent a locally cached 'Graphics Context' that can be efficiently used by the X11workbench Toolkit . It is similar to a GC structure in X11, and an HDC in windows, and exists for basically the same purpose.

Local cacheing of context information improves efficiency, especially for remote X11 clients.

typedef struct s_WBGC
{
  Display *display;   // the Display associated with the WBGC (NULL implies 'Default Display')
  Drawable dw;        // the Drawable for which this WBGC was created (None implies default Window)
  GC gc;              // the associated 'GC'
  XGCValues values;   // cached XGCValues for the GC
  WB_FONT pFont;      // cached default font
  Region clip_rgn;    // clipping region (or None to use clip_image)
  XImage *clip_image; // cached XImage for the GC, for 'clip mask'
  XImage *tile_image; // cached XImage for the GC, for 'tile'
  XImage *stip_image; // cached XImage for the GC, for 'stipple'
} * WBGC;

It is generally safe to query the 'values' member in order to get cached information about the WBGC. You should not change them, however.

The XOrg documentation defines the XGCValues structure as follows:

typedef struct // XGCValues
{
  int function;               // logical operation
  unsigned long plane_mask;   // plane mask
  unsigned long foreground;   // foreground pixel
  unsigned long background;   // background pixel
  int line_width;             // line width (in pixels)
  int line_style;             // LineSolid, LineOnOffDash, LineDoubleDash
  int cap_style;              // CapNotLast, CapButt, CapRound, CapProjecting
  int join_style;             // JoinMiter, JoinRound, JoinBevel
  int fill_style;             // FillSolid, FillTiled, FillStippled FillOpaqueStippled
  int fill_rule;              // EvenOddRule, WindingRule
  int arc_mode;               // ArcChord, ArcPieSlice
  Pixmap tile;                // tile pixmap for tiling operations
  Pixmap stipple;             // stipple 1 plane pixmap for stippling
  int ts_x_origin;            // offset for tile or stipple operations
  int ts_y_origin;
  Font font;                  // default text font for text operations
  int subwindow_mode;         // ClipByChildren, IncludeInferiors
  Bool graphics_exposures;    // boolean, should exposures be generated
  int clip_x_origin;          // origin for clipping
  int clip_y_origin;
  Pixmap clip_mask;           // bitmap clipping; other calls for rects
  int dash_offset;            // patterned/dashed line information
  char dashes;
} XGCValues;

Additional information regarding the drawing of lines

The XOrg 'manual page' documentation for XGCValues also includes the following information (slightly edited):

The line-width is measured in pixels and either can be greater than or
equal to one (wide line) or can be the special value zero (thin line).

Wide lines are drawn centered on the path described by the graphics
request.  Unless otherwise specified by the join-style or cap-style,
the bounding box of a wide line with endpoints [x1, y1], [x2, y2] and
width w is a rectangle with vertices at the following real coordinates:

[x1-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1-(w*cs/2)],
[x2-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2-(w*cs/2)]

Here sn is the sine of the angle of the line, and cs is the cosine of
the angle of the line.  A pixel is part of the line and so is drawn if
the center of the pixel is fully inside the bounding box (which is
viewed as having infinitely thin edges).  If the center of the pixel is
exactly on the bounding box, it is part of the line if and only if the
interior is immediately to its right (x increasing direction).  Pixels
with centers on a horizontal edge are a special case and are part of
the line if and only if the interior or the boundary is immediately
below (y increasing direction) and the interior or the boundary is
immediately to the right (x increasing direction).

Thin lines (zero line-width) are one-pixel-wide lines drawn using an
unspecified, device-dependent algorithm.  There are only two con-
straints on this algorithm.

1.   If a line is drawn unclipped from [x1,y1] to [x2,y2] and if
    another line is drawn unclipped from [x1+dx,y1+dy] to
    [x2+dx,y2+dy], a point [x,y] is touched by drawing the first line
    if and only if the point [x+dx,y+dy] is touched by drawing the
    second line.

2.   The effective set of points comprising a line cannot be affected
    by clipping.  That is, a point is touched in a clipped line if and
    only if the point lies inside the clipping region and the point
    would be touched by the line when drawn unclipped.

A wide line drawn from [x1,y1] to [x2,y2] always draws the same pixels
as a wide line drawn from [x2,y2] to [x1,y1], not counting cap-style
and join-style.  It is recommended that this property be true for thin
lines, but this is not required.  A line-width of zero may differ from
a line-width of one in which pixels are drawn.  This permits the use of
line drawing hardware from many manufacturers, which may run many times
faster than the more precisely specified wide lines.

In general, drawing a thin line will be faster than drawing a wide line
of width one.  However, because of their different drawing algorithms,
thin lines may not mix well aesthetically with wide lines.  If it is
desirable to obtain precise and uniform results across all displays, a
client should always use a line-width of one rather than a line-width
of zero.

To be fair, the use of a line width of zero in the X11Workbench Toolkit is NOT recommended. The XImage code will assume zero implies width=1.

Also, an algorithm that allows the 'touching' of the same point many times is not impractical with an XImage; that is, the amount of code needed to check if a point were touched or will be touched is more computationally expensive than 'just touching it anyway'. As such, the XImage code may 'touch' a point multiple times, depending. For video hardware, especially accelerated video hardware, this could be a performance hit. But when using an XImage as a backing store for the window contents, it makes more sense to simply draw it anyway.

Additional information can be found in the aforementioned manual page.