X11workbench Toolkit  1.0
Exposure and Mapping/Visibility

Functions

static __inline__ void WBDialogControlInvalidateGeom (WBDialogControl *pDialogControl, const WB_GEOM *pGeom, int bPaintFlag)
 Convenience function, invalidates a Geom for a dialog box control. More...
 
static __inline__ void WBDialogControlInvalidateRegion (WBDialogControl *pDialogControl, Region rgn, int bPaintFlag)
 Convenience function, invalidates a region for a dialog box control. More...
 
int WBMapWindow (Display *pDisplay, Window wID)
 Wrapper for XMapWindow, makes window visible. More...
 
int WBMapRaised (Display *pDisplay, Window wID)
 wrapper for XMapRaised, makes window visible and moves to top More...
 
int WBUnmapWindow (Display *pDisplay, Window wID)
 wrapper for XUnmapWindow, makes window invisible without destroying it More...
 
int WBIsMapped (Display *pDisplay, Window wID)
 Returns non-zero if window has been mapped; zero otherwise. More...
 
void WBInvalidateGeom (Window wID, const WB_GEOM *pGeom, int bPaintFlag)
 'Paint' helper, invalidates a geometry for asynchronous Expose event generation More...
 
void WBInvalidateRegion (Window wID, Region rgn, int bPaintFlag)
 'Paint' helper, invalidates a region for asynchronous Expose event generation More...
 
void WBValidateGeom (Window wID, const WB_GEOM *pGeom)
 'Paint' helper, validates a geometry for asynchronous Expose event generation More...
 
void WBValidateRegion (Window wID, Region rgn)
 'Paint' helper, validates a region for asynchronous Expose event generation More...
 
Region WBGetInvalidRegion (Window wID)
 'Paint' helper, returns a copy of the invalid region for a window More...
 
Region WBGetPaintRegion (Window wID)
 'Paint' helper, returns a copy of the current 'paint' region for the window More...
 
Region WBRectToRegion (const WB_RECT *pRect)
 'Paint' helper, converts a WB_RECT structure to a Region. More...
 
Region WBGeomToRegion (const WB_GEOM *pGeom)
 'Paint' helper, converts a WB_GEOM structure to a Region. More...
 
Region WBCopyRegion (Region rgnSource)
 Simple utility to copy a region. More...
 
void WBUpdateWindow (Window wID)
 'Paint' helper, generates an asynchronous Expose event for non-empty 'invalid' region More...
 
void WBUpdateWindowImmediately (Window wID)
 'Paint' helper, generates an immediate Expose event for non-empty 'invalid' region More...
 
WBGC WBBeginPaint (Window wID, XExposeEvent *pEvent, WB_GEOM *pgRet)
 'Paint' helper, creates a WBGC for use in updating the window in an Expose event handler More...
 
WBGC WBBeginPaintGeom (Window wID, WB_GEOM *pgBounds)
 'Paint' helper, creates a WBGC for use in updating the window for a specified rectangular area More...
 
void WBEndPaint (Window wID, WBGC gc)
 'Paint' helper, frees resources and marks the update region 'valid' More...
 
void WBClearWindow (Window wID, WBGC gc)
 'Paint' helper, erases background by painting the background color within the clipping region More...
 
static __inline__ void WBInvalidateRect (Window wID, const WB_RECT *pRCT, int bPaintFlag)
 'Paint' helper, invalidates a WB_RECT for asynchronous Expose event generation More...
 
static __inline__ void WBValidateRect (Window wID, WB_RECT *pRCT)
 'Paint' helper, validates a WB_RECT for asynchronous Expose event generation More...
 
XImage * WBGetWindowImage (Display *pDisplay, Window wID)
 Obtain an XImage for the entire window. More...
 
int WBAssignWindowImage (Display *pDisplay, Window wID, XImage *pImage)
 Assign an XImage for the entire window. More...
 
int WBCopyIntoWindowImage (Display *pDisplay, Window wID, XImage *pSrcImage, int xSrc, int ySrc, int width, int height, int xOffs, int yOffs)
 Copy an XImage into the cached XImage for the entire window. More...
 
void WBUpdateWindowWithImage (Display *pDisplay, Window wID)
 Update the window's appearance with the contents of the cached XImage. More...
 
int WBDrawPoint (Display *display, Drawable d, WBGC gc, int x, int y)
 Wrapper for XDrawPoint() More...
 
int WBDrawPoints (Display *display, Drawable d, WBGC gc, XPoint *points, int npoints, int mode)
 Wrapper for XDrawPoints() More...
 
int WBDrawLine (Display *display, Drawable d, WBGC gc, int x1, int y1, int x2, int y2)
 Wrapper for XDrawLines() More...
 
int WBDrawLines (Display *display, Drawable d, WBGC gc, XPoint *points, int npoints, int mode)
 Wrapper for XDrawLine() More...
 
int WBDrawRectangle (Display *display, Drawable d, WBGC gc, int x, int y, unsigned int width, unsigned int height)
 Wrapper for XDrawRectangle() More...
 
int WBFillRectangle (Display *display, Drawable d, WBGC gc, int x, int y, unsigned int width, unsigned int height)
 Wrapper for XFillRectangle() More...
 
int WBDrawArc (Display *display, Drawable d, WBGC gc, int x, int y, unsigned int width, unsigned int height, int angle1, int angle2)
 Wrapper for XDrawArc() More...
 
int WBFillArc (Display *display, Drawable d, WBGC gc, int x, int y, unsigned int width, unsigned int height, int angle1, int angle2)
 Wrapper for XFillArc() More...
 
int WBFillPolygon (Display *display, Drawable d, WBGC gc, XPoint *points, int npoints, int shape, int mode)
 Wrapper for XFillPolygon() More...
 
int WBDrawString (Display *display, Drawable d, WBGC gc, int x, int y, const char *string, int length)
 wrapper for XDrawString() More...
 

Detailed Description

Proper handling of Expose events is a performance-critical component of graphical interfaces. To simplify the handling and processing of Expose events there are a set of APIs and internal states that assist you in determining when to re-draw a window, and what portion of the window needs to be re-drawn.

A typical Expose event handler might look like this:

// parameters to function are XExposeEvent *pEvent, Window wID
void MyExposeHandler(Window wID, XExposeEvent *pEvent)
{
Display *pDisplay = WBGetWindowDisplay(wID);
GC gc;
WB_GEOM geomPaint;
gc = WBBeginPaint(wID, pEvent, &geomPaint);
if(!gc)
{
return;
}
// here is where you modify the GC, change foreground/background colors, drawing modes, etc.
// and perform necessary erasing within the geometry specified by geomPaint.
// ideally your code will NOT attempt to draw anything outside of geomPaint.
XSetForeground(pDisplay, gc, WBGetWindowFGColor(wID)); // example
XSetBackground(pDisplay, gc, WBGetWindowBGColor(wID)); // example
XClearArea(pDisplay, wID, geomPaint.x, geomPaint.y, geomPaint.width, geomPaint.height, 0);
// perform any drawing here
WBEndPaint(wID, gc);
}

Function Documentation

◆ WBAssignWindowImage()

int WBAssignWindowImage ( Display *  pDisplay,
Window  wID,
XImage *  pImage 
)

Assign an XImage for the entire window.

Parameters
pDisplayThe display associated with the specified window
wIDThe window that receives the aWB_TIMER XClientEvent (None == application)
pImageThe XImage to assign to the window's internal information. On success, after the function call, this pointer is 'owned' by the window and should not be destroyed.
Returns
A value of zero on success. A non-zero value indicates an error.

Calling this function assigns a new cached XImage as 'backing store' for the window. It must be large enough to include the entire window's display area. On success, the assigned image will replace any existing image. Assigning a value of 'NULL' deletes any existing cached image. If an image is too small, the function call will fail, and ownership of the XImage remains as-is. Your call to this function needs to check for errors so that any resources can be properly cleaned up, as the XImage will not be owned nor destroyed.

Whenever graphics operations make use of the cached image, an implicit call to WBUpdateWindowWithImage() will be made within the call to WBEndPaint().

Header File: window_helper.h

See also
WBBeginPaint() WBEndPaint()

Definition at line 8166 of file window_helper.c.

◆ WBBeginPaint()

WBGC WBBeginPaint ( Window  wID,
XExposeEvent *  pEvent,
WB_GEOM pgRet 
)

'Paint' helper, creates a WBGC for use in updating the window in an Expose event handler

Parameters
wIDWindow ID associated with the Expose event
pEventPointer to the Expose event that's being processed
pgRetThe returned bounding geometry for the invalid region being 'painted'
Returns
A WBGC (graphics context) to be used in handling the Expose event

When processing Expose events, you should call WBBeginPaint to obtain the WBGC needed for all of the operations needed to update (paint) the window.
This function collects all of the relevant invalid regions associated with the window that fall within the 'Expose' event area, and calculates a bounding WB_GEOM rectangle for it. It also applies the invalid region as a 'clipping' region for the returned WBGC. When you call WBEndPaint(), the entire clipping region will be marked 'valid' automatically, so it is important for your 'paint' function to update the entire WB_GEOM rectangle identified by pgRet. This includes erasing the background as well as drawing whatever is in the foreground.

Header File: window_helper.h

Definition at line 7732 of file window_helper.c.

◆ WBBeginPaintGeom()

WBGC WBBeginPaintGeom ( Window  wID,
WB_GEOM pgBounds 
)

'Paint' helper, creates a WBGC for use in updating the window for a specified rectangular area

Parameters
wIDWindow ID associated with the Expose event
pgBoundsOn entry, the bounding WB_GEOM for which to get a graphics context. On return, the bounding WB_GEOM for the invalid region being 'painted'
Returns
A WBGC (graphics context) to be used in painting the specific rectangular region

When processing Expose events, you should call WBBeginPaint() to obtain the WBGC needed for all of the operations needed to update (paint) the window.
This particular function is more suited to updating a specific area outside of a normal Expose callback handler. As an example, a frame window would use this to update the tab area or the status bar area, prior to calling the user callback function. That way, only the desired region will be 'validated' on call to WBEndPaint(), and not the entire window client area.

Header File: window_helper.h

Definition at line 7780 of file window_helper.c.

◆ WBClearWindow()

void WBClearWindow ( Window  wID,
WBGC  gc 
)

'Paint' helper, erases background by painting the background color within the clipping region

Parameters
wIDWindow ID associated with the Expose event
gcThe WBGC (graphics context) returned by WBBeginPaint().

Call this function, following a call to WBBeginPaint(), if you want to erase the background of the window. Call this in lieu of XClearWindow() or XClearArea()

Header File: window_helper.h

Definition at line 7971 of file window_helper.c.

◆ WBCopyIntoWindowImage()

int WBCopyIntoWindowImage ( Display *  pDisplay,
Window  wID,
XImage *  pSrcImage,
int  xSrc,
int  ySrc,
int  width,
int  height,
int  xOffs,
int  yOffs 
)

Copy an XImage into the cached XImage for the entire window.

Parameters
pDisplayThe display associated with the specified window
wIDThe window that receives the aWB_TIMER XClientEvent (None == application)
pImageThe XImage to copy into the cached XImage for the window. Must be a pointer to a valid XImage. The specified XImage will not be changed, owned, nor destroyed.
xSrcThe 'x' offset within the source XImage to begin copying from
ySrcThe 'y' offset within the source XImage to begin copying from
widthThe width within the source XImage to copy from. a value of '-1' copies as much as possible to the destination image
heightThe height within the source XImage to copy from. a value of '-1' copies as much as possible to the destination image
xDstThe 'x' offset within the window's cached XImage to begin copying to
yDstThe 'y' offset within the window's cached XImage to begin copying to
Returns
A value of zero on success. A non-zero value indicates an error.

Calling this function copies the specified XImage's data into the cached image of the window. If the window does not already have a cached image, one will be created that containing the window's visible display data. On success, the assigned image will replace that portion of the existing image as specified by the source offset, source size, and destination offset. Images that are too large to fit into the destination will be limited within the appropriate dimensions, based on the destination image size.

Whenever graphics operations make use of the cached image, an implicit call to WBUpdateWindowWithImage() will be made within the call to WBEndPaint().

Header File: window_helper.h

See also
WBBeginPaint() WBEndPaint()

Definition at line 8181 of file window_helper.c.

◆ WBCopyRegion()

Region WBCopyRegion ( Region  rgnSource)

Simple utility to copy a region.

Parameters
rgnSourceA source region to copy
Returns
A region that is a union of the source region with itself; i.e. a copy

This function makes a simple copy of a region by doing a union with itself, returning the result. The caller must destroy the returned value using XDestroyRegion()

Header File: window_helper.h

Definition at line 7634 of file window_helper.c.

◆ WBDialogControlInvalidateGeom()

static __inline__ void WBDialogControlInvalidateGeom ( WBDialogControl pDialogControl,
const WB_GEOM pGeom,
int  bPaintFlag 
)
static

Convenience function, invalidates a Geom for a dialog box control.

Parameters
pDialogControlA pointer to the WBDialogControl structure that is associated with the dialog control window
pGeomA pointer to a WB_GEOM structure specifying the invalid area, or NULL (implying the entire window)
bPaintFlagA non-zero value to force re-paint by generating an Expose message. Zero simply invalidates the specified area

convenience function for calling WBInvalidateRegion() for a dialog box control

Header File: dialog_controls.h

Definition at line 340 of file dialog_controls.h.

◆ WBDialogControlInvalidateRegion()

static __inline__ void WBDialogControlInvalidateRegion ( WBDialogControl pDialogControl,
Region  rgn,
int  bPaintFlag 
)
static

Convenience function, invalidates a region for a dialog box control.

Parameters
pDialogControlA pointer to the WBDialogControl structure that is associated with the dialog control window
rgnA Region identifier specifying the invalid area, or None (implying the entire window)
bPaintFlagA non-zero value to force re-paint by generating an Expose message. Zero simply invalidates the specified area

convenience function for calling WBInvalidateRegion() for a dialog box control

Header File: dialog_controls.h

Definition at line 359 of file dialog_controls.h.

◆ WBDrawArc()

int WBDrawArc ( Display *  display,
Drawable  d,
WBGC  gc,
int  x,
int  y,
unsigned int  width,
unsigned int  height,
int  angle1,
int  angle2 
)

Wrapper for XDrawArc()

Parameters
pDisplayThe display associated with the specified window
dThe Drawable (or window) I'm painting. If a window, this may use the XImage cache
gcThe Graphics context of the operation
xThe origin x of the operation
yThe origin y of the operation
widthThe width of the arc's elipse
heightThe height of the arc's elipse
angle1The starting angle of the arc
angle2The ending angle of the arc
Returns
An integer indicating success or failure

This function draws an arc, similar to XDrawArc(), on the specified Drawable, with the specified graphics context indicating foreground and background colors.

Header File: window_helper.h

Definition at line 345 of file graphical_api.c.

◆ WBDrawLine()

int WBDrawLine ( Display *  display,
Drawable  d,
WBGC  gc,
int  x1,
int  y1,
int  x2,
int  y2 
)

Wrapper for XDrawLines()

Parameters
pDisplayThe display associated with the specified window
dThe Drawable (or window) I'm painting. If a window, this may use the XImage cache
gcThe Graphics context of the operation
x1The origin 'x' coordinate of the line
y1The origin 'y' coordinate of the line
x2The final 'x' coordinate of the line
y2The final 'y' coordinate of the line
Returns
An integer indicating success or failure

This function draws a line, similar to XDrawLines(), on the specified Drawable, with the specified graphics context indicating foreground and background colors.

Header File: window_helper.h

Definition at line 197 of file graphical_api.c.

◆ WBDrawLines()

int WBDrawLines ( Display *  display,
Drawable  d,
WBGC  gc,
XPoint *  points,
int  npoints,
int  mode 
)

Wrapper for XDrawLine()

Parameters
pDisplayThe display associated with the specified window
dThe Drawable (or window) I'm painting. If a window, this may use the XImage cache
gcThe Graphics context of the operation
pointsA pointer to an array of XPoint structures describing the line vertices
npointsThe number of entries in the 'points' array
modeA constant indicating the coordinate mode, either CoordModeOrigin or CoordModePrevious - see XDrawLines().
Returns
An integer indicating success or failure

This function draws one or more lines, similar to XDrawLines(), on the specified Drawable, with the specified graphics context indicating foreground and background colors.

Header File: window_helper.h

Definition at line 234 of file graphical_api.c.

◆ WBDrawPoint()

int WBDrawPoint ( Display *  display,
Drawable  d,
WBGC  gc,
int  x,
int  y 
)

Wrapper for XDrawPoint()

Parameters
pDisplayThe display associated with the specified window
dThe Drawable (or window) I'm painting. If a window, this may use the XImage cache
gcThe Graphics context of the operation
xThe origin 'x' coordinate of the line
yThe origin 'y' coordinate of the line
Returns
An integer indicating success or failure

This function draws a point, similar to XDrawPoint(), on the specified Drawable, with the specified graphics context indicating foreground and background colors.

Header File: window_helper.h

Definition at line 124 of file graphical_api.c.

◆ WBDrawPoints()

int WBDrawPoints ( Display *  display,
Drawable  d,
WBGC  gc,
XPoint *  points,
int  npoints,
int  mode 
)

Wrapper for XDrawPoints()

Parameters
pDisplayThe display associated with the specified window
dThe Drawable (or window) I'm painting. If a window, this may use the XImage cache
gcThe Graphics context of the operation
pointsA pointer to an array of XPoint structures describing the line vertices
npointsThe number of entries in the 'points' array
modeA constant indicating the coordinate mode, either CoordModeOrigin or CoordModePrevious - see XDrawLines().
Returns
An integer indicating success or failure

This function draws one or more points, similar to XDrawPoints(), on the specified Drawable, with the specified graphics context indicating foreground and background colors.

Header File: window_helper.h

Definition at line 160 of file graphical_api.c.

◆ WBDrawRectangle()

int WBDrawRectangle ( Display *  display,
Drawable  d,
WBGC  gc,
int  x,
int  y,
unsigned int  width,
unsigned int  height 
)

Wrapper for XDrawRectangle()

Parameters
pDisplayThe display associated with the specified window
dThe Drawable (or window) I'm painting. If a window, this may use the XImage cache
gcThe Graphics context of the operation
xThe origin x of the operation
yThe origin y of the operation
widthThe width of the rectangle
heightThe height of the rectangle
Returns
An integer indicating success or failure

This function draws a rectangle, similar to XDrawRectangle(), on the specified Drawable, with the specified graphics context indicating foreground and background colors.

Header File: window_helper.h

Definition at line 271 of file graphical_api.c.

◆ WBDrawString()

int WBDrawString ( Display *  display,
Drawable  d,
WBGC  gc,
int  x,
int  y,
const char *  string,
int  length 
)

wrapper for XDrawString()

Parameters
pDisplayA pointer to the display to use for rendering the text
dThe 'Drawable' object upon which to render the text
gcThe graphics context 'WBGC' for rendering the text
xThe 'x' coordinate for the text alignment (left)
yThe 'y' coordinate for the text alignment (bottom)
stringA const pointer to a UTF-8 or multi-byte string
lengthThe BYTE LENGTH of the UTF-8 or mult-byte string (not character length)
Returns
An integer indicating success or failure

Use this function in lieu of XDrawString() to draw text in a platform-independent manner, using the specified font, upon the specified 'Drawable'. This function is the equivalent of the X11 library's XDrawString(). Internally, it calls DTDrawString().

Header File: draw_text.h

Definition at line 458 of file graphical_api.c.

◆ WBEndPaint()

void WBEndPaint ( Window  wID,
WBGC  gc 
)

'Paint' helper, frees resources and marks the update region 'valid'

Parameters
wIDWindow ID associated with the Expose event and passed to WBBeginPaint()
gcThe WBGC (graphics context) returned by WBBeginPaint()

Call this function, following a call to WBBeginPaint(), once the invalid area of the window has been properly rendered. It will free resources and mark the invalid (update) region as 'valid'.

Additionally, if a cached XImage is being used for this window, the display will be updated using the cached image during the call to this function.

Header File: window_helper.h

See also
WBBeginPaint() WBAssignWindowImage()

Definition at line 8033 of file window_helper.c.

◆ WBFillArc()

int WBFillArc ( Display *  display,
Drawable  d,
WBGC  gc,
int  x,
int  y,
unsigned int  width,
unsigned int  height,
int  angle1,
int  angle2 
)

Wrapper for XFillArc()

Parameters
pDisplayThe display associated with the specified window
dThe Drawable (or window) I'm painting. If a window, this may use the XImage cache
gcThe Graphics context of the operation
xThe origin x of the operation
yThe origin y of the operation
widthThe width of the arc's elipse
heightThe height of the arc's elipse
angle1The starting angle of the arc
angle2The ending angle of the arc
Returns
An integer indicating success or failure

This function draws a filled arc, similar to XFillArc(), on the specified Drawable, with the specified graphics context indicating foreground, fill, and background colors.

Header File: window_helper.h

Definition at line 383 of file graphical_api.c.

◆ WBFillPolygon()

int WBFillPolygon ( Display *  display,
Drawable  d,
WBGC  gc,
XPoint *  points,
int  npoints,
int  shape,
int  mode 
)

Wrapper for XFillPolygon()

Parameters
pDisplayThe display associated with the specified window
dThe Drawable (or window) I'm painting. If a window, this may use the XImage cache
gcThe Graphics context of the operation
pointsA pointer to an array of XPoint structures describing the polygon line vertices
npointsThe number of entries in the 'points' array
shapeA constant indicating the general shape, either Convex, Nonconvex, or Complex - see XFillPolygon()
modeA constant indicating the coordinate mode, either CoordModeOrigin or CoordModePrevious - see XFillPolygon().
Returns
An integer indicating success or failure

This function draws a filled polygon, similar to XFillPolygon(), on the specified Drawable, with the specified graphics context indicating foreground, fill, and background colors.

Header File: window_helper.h

Definition at line 421 of file graphical_api.c.

◆ WBFillRectangle()

int WBFillRectangle ( Display *  display,
Drawable  d,
WBGC  gc,
int  x,
int  y,
unsigned int  width,
unsigned int  height 
)

Wrapper for XFillRectangle()

Parameters
pDisplayThe display associated with the specified window
dThe Drawable (or window) I'm painting. If a window, this may use the XImage cache
gcThe Graphics context of the operation
xThe origin x of the operation
yThe origin y of the operation
widthThe width of the rectangle
heightThe height of the rectangle
Returns
An integer indicating success or failure

This function draws a filled rectangle, similar to XFillRectangle(), on the specified Drawable, with the specified graphics context indicating foreground, fill, and background colors.

Header File: window_helper.h

Definition at line 308 of file graphical_api.c.

◆ WBGeomToRegion()

Region WBGeomToRegion ( const WB_GEOM pGeom)

'Paint' helper, converts a WB_GEOM structure to a Region.

Parameters
pGeomA const pointer to the WB_GEOM structure
Returns
A region that encompasses the area of the WB_GEOM structure, or None on error

This function converts a WB_GEOM structure to a Region. The caller must destroy the returned value using XDestroyRegion()

Header File: window_helper.h

Definition at line 7697 of file window_helper.c.

◆ WBGetInvalidRegion()

Region WBGetInvalidRegion ( Window  wID)

'Paint' helper, returns a copy of the invalid region for a window

Parameters
wIDWindow ID
Returns
Copy of 'invalid region' for this window, or None.

This function returns a copy of the current invalid region for the window, or None if the window is up-to-date. The caller must destroy the returned value using XDestroyRegion()

Header File: window_helper.h

Definition at line 7563 of file window_helper.c.

◆ WBGetPaintRegion()

Region WBGetPaintRegion ( Window  wID)

'Paint' helper, returns a copy of the current 'paint' region for the window

Parameters
wIDWindow ID
Returns
Copy of 'paint region' for this window, or None. not valid outside of BeginPaint() / EndPaint()

This function returns a copy of the current paint region for the window, or None if the window is up-to-date. The caller must destroy the returned value using XDestroyRegion()
This function is not valid outside of WBBeginPaint() / WBEndPaint() processing, typically part of an 'Expose' event handler.

Header File: window_helper.h

Definition at line 7605 of file window_helper.c.

◆ WBGetWindowImage()

XImage* WBGetWindowImage ( Display *  pDisplay,
Window  wID 
)

Obtain an XImage for the entire window.

Parameters
pDisplayThe display associated with the specified window
wIDThe window that receives the aWB_TIMER XClientEvent (None == application)
Returns
A pointer to an XImage, or NULL on error

Returns the cached XImage for the window. If none exists, one will be created and stored within the internal stuctures for the window. Actual changes to the image will not be reflected on the display until you call WBUpdateWindowWithImage().

NOTE: You should not destroy nor cache the XImage pointer returned by this function. It is owned by the window's internal structures.

Whenever graphics operations make use of the cached image, an implicit call to WBUpdateWindowWithImage() will be made within the call to WBEndPaint().

Header File: window_helper.h

See also
WBBeginPaint() WBEndPaint()

Definition at line 8112 of file window_helper.c.

◆ WBInvalidateGeom()

void WBInvalidateGeom ( Window  wID,
const WB_GEOM pGeom,
int  bPaintFlag 
)

'Paint' helper, invalidates a geometry for asynchronous Expose event generation

Parameters
wIDThe Window ID for the affected window
pGeomA pointer to a WB_GEOM structure specifying the invalid area, or NULL (implying the entire window)
bPaintFlagA non-zero value to force re-paint by generating an Expose message. Zero simply invalidates the specified area

In conjunction with WBProcessExposeEvent it adds a geometry to the 'invalid' region associated with the window, and optionally generates an asynchronous expose event if 'bPaintFlag' is non-zero.
For a zero 'bPaintFlag' the next Expose event will include this geometry as part of its update region.

Header File: window_helper.h

Definition at line 7324 of file window_helper.c.

◆ WBInvalidateRect()

static __inline__ void WBInvalidateRect ( Window  wID,
const WB_RECT pRCT,
int  bPaintFlag 
)
static

'Paint' helper, invalidates a WB_RECT for asynchronous Expose event generation

Parameters
wIDThe Window ID for the affected window
pRCTA const pointer to a WB_RECT structure specifying the invalid area, or NULL (implying the entire window)
bPaintFlagA non-zero value to force re-paint by generating an Expose message. Zero simply invalidates the specified area

In conjunction with WBProcessExposeEvent it adds a rectangle to the 'invalid' region associated with the window, and optionally generates an asynchronous expose event if 'bPaintFlag' is non-zero.
For a zero 'bPaintFlag' the next Expose event will include this geometry as part of its update region.

Header File: window_helper.h

Definition at line 2776 of file window_helper.h.

◆ WBInvalidateRegion()

void WBInvalidateRegion ( Window  wID,
Region  rgn,
int  bPaintFlag 
)

'Paint' helper, invalidates a region for asynchronous Expose event generation

Parameters
wIDThe Window ID for the affected window
rgnA Region identifier specifying the invalid area, or None (implying the entire window)
bPaintFlagA non-zero value to force re-paint by generating an Expose message. Zero simply invalidates the specified area

In conjunction with WBProcessExposeEvent it adds a region to the 'invalid' region associated with the window, and optionally generates an asynchronous expose event if 'bPaintFlag' is non-zero.
For a zero 'bPaintFlag' the next Expose event will include this region as part of its update region.

Header File: window_helper.h

Definition at line 7399 of file window_helper.c.

◆ WBIsMapped()

int WBIsMapped ( Display *  pDisplay,
Window  wID 
)

Returns non-zero if window has been mapped; zero otherwise.

Parameters
pDisplayA pointer to the Display
wIDThe Window ID for the window to check for visibility
Returns
A non-zero value if the window has been both registered and mapped (i.e. is visible), otherwise zero.

This function only works for windows that have been registered with a callback function. It checks the internal flags to see if the window has been mapped, and if it has, it returns a non-zero value. It can be helpful to avoid unnecessary signals from the X11 API.

Header File: window_helper.h

Definition at line 5533 of file window_helper.c.

◆ WBMapRaised()

int WBMapRaised ( Display *  pDisplay,
Window  wID 
)

wrapper for XMapRaised, makes window visible and moves to top

Parameters
pDisplayA pointer to the Display
wIDThe Window ID for the window to map (i.e. make visible) and Raise (bring to the front)
Returns
The return value from XMapRaised()

Use this function when 'raising' a window, rather than XMapRaised so that the internal state flags and other information can be updated

Header File: window_helper.h

Definition at line 5465 of file window_helper.c.

◆ WBMapWindow()

int WBMapWindow ( Display *  pDisplay,
Window  wID 
)

Wrapper for XMapWindow, makes window visible.

Parameters
pDisplayA pointer to the Display
wIDThe Window ID for the window to map (i.e. make visible)
Returns
The return value from XMapWindow()

Use this function when making a window visible, rather than XMapWindow so that the internal state flags and other information can be updated.

Header File: window_helper.h

Definition at line 5421 of file window_helper.c.

◆ WBRectToRegion()

Region WBRectToRegion ( const WB_RECT pRect)

'Paint' helper, converts a WB_RECT structure to a Region.

Parameters
pRectA const pointer to the WB_RECT structure
Returns
A region that encompasses the area of the WB_RECT structure, or None on error

This function converts a WB_RECT structure to a Region. The caller must destroy the returned value using XDestroyRegion()

Header File: window_helper.h

Definition at line 7664 of file window_helper.c.

◆ WBUnmapWindow()

int WBUnmapWindow ( Display *  pDisplay,
Window  wID 
)

wrapper for XUnmapWindow, makes window invisible without destroying it

Parameters
pDisplayA pointer to the Display
wIDThe Window ID for the window to unmap (i.e. make INvisible)
Returns
The return value from XUnmapWindow()

Use this function when making a window invisible, rather than XUnmapWindow so that the internal state flags and other information can be updated

Header File: window_helper.h

Definition at line 5508 of file window_helper.c.

◆ WBUpdateWindow()

void WBUpdateWindow ( Window  wID)

'Paint' helper, generates an asynchronous Expose event for non-empty 'invalid' region

Whenever the 'invalid' region is non-empty, you can generate an asynchronous Expose event using this function. This allows you to invalidate several geometries or regions during normal processing, with the paint flag set to 'false', and then generate a single Expose event after all of the processing has completed.

Header File: window_helper.h

Definition at line 7211 of file window_helper.c.

◆ WBUpdateWindowImmediately()

void WBUpdateWindowImmediately ( Window  wID)

'Paint' helper, generates an immediate Expose event for non-empty 'invalid' region

Whenever the 'invalid' region is non-empty, you can generate an immediate (synchronous) Expose event using this function. This is useful for a UI related event in which you need to re-paint portions of a window immediately.
You should make sure that the Expose handler does not cause recursion, since it will be called directly by this function.

Header File: window_helper.h

Definition at line 7271 of file window_helper.c.

◆ WBUpdateWindowWithImage()

void WBUpdateWindowWithImage ( Display *  pDisplay,
Window  wID 
)

Update the window's appearance with the contents of the cached XImage.

Parameters
pDisplayThe display associated with the specified window
wIDThe window that receives the aWB_TIMER XClientEvent (None == application)

Calling this function will update the window's display area with the contents of the cached image. If there is no cached image, this function will have no effect.

Whenever graphics operations make use of the cached image, an implicit call to WBUpdateWindowWithImage() will be made within the call to WBEndPaint().

Header File: window_helper.h

See also
WBBeginPaint() WBEndPaint()

Definition at line 8199 of file window_helper.c.

◆ WBValidateGeom()

void WBValidateGeom ( Window  wID,
const WB_GEOM pGeom 
)

'Paint' helper, validates a geometry for asynchronous Expose event generation

Parameters
wIDThe Window ID for the affected window
pGeomA pointer to a WB_GEOM structure specifying the valid area, or NULL (implying the entire window)

In conjunction with WBProcessExposeEvent it removes a geometry from the 'invalid' region associated with the window. If the resulting 'invalid' region is empty, no subsequent 'Expose' event will be generated, even if one had previously been in the queue, until the next Expose event or 'invalid' region exists for this window.

Header File: window_helper.h

Definition at line 7455 of file window_helper.c.

◆ WBValidateRect()

static __inline__ void WBValidateRect ( Window  wID,
WB_RECT pRCT 
)
static

'Paint' helper, validates a WB_RECT for asynchronous Expose event generation

Parameters
wIDThe Window ID for the affected window
pRCTA const pointer to a WB_RECT structure specifying the valid area, or NULL (implying the entire window)

In conjunction with WBProcessExposeEvent it removes a rectangle from the 'invalid' region associated with the window. If the resulting 'invalid' region is empty, no subsequent 'Expose' event will be generated, even if one had previously been in the queue, until the next Expose event or 'invalid' region exists for this window.

Header File: window_helper.h

Definition at line 2812 of file window_helper.h.

◆ WBValidateRegion()

void WBValidateRegion ( Window  wID,
Region  rgn 
)

'Paint' helper, validates a region for asynchronous Expose event generation

Parameters
wIDThe Window ID for the affected window
rgnA Region identifer specifying the valid area, or NULL (implying the entire window)

In conjunction with WBProcessExposeEvent it removes a region from the 'invalid' region associated with the window. If the resulting 'invalid' region is empty, no subsequent 'Expose' event will be generated, even if one had previously been in the queue, until the next Expose event or 'invalid' region exists for this window.

Header File: window_helper.h

Definition at line 7520 of file window_helper.c.