X11 Work Bench Toolkit  1.0
Exposure and Mapping/Visibility

Functions

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...
 
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...
 
GC WBBeginPaint (Window wID, XExposeEvent *pEvent, WB_GEOM *pgRet)
 'Paint' helper, creates a GC for use in updating the window in an Expose event handler More...
 
GC WBBeginPaintGeom (Window wID, WB_GEOM *pgBounds)
 'Paint' helper, creates a GC for use in updating the window for a specified rectangular area More...
 
void WBEndPaint (Window wID, GC gc)
 'Paint' helper, frees resources and marks the update region 'valid' More...
 
void WBClearWindow (Window wID, GC 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...
 

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

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

'Paint' helper, creates a GC 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 GC (graphics context) to be used in handling the Expose event

When processing Expose events, you should call WBBeginPaint to obtain the GC 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 GC. 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 7710 of file window_helper.c.

GC WBBeginPaintGeom ( Window  wID,
WB_GEOM pgBounds 
)

'Paint' helper, creates a GC 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 GC (graphics context) to be used in painting the specific rectangular region

When processing Expose events, you should call WBBeginPaint() to obtain the GC 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 7739 of file window_helper.c.

void WBClearWindow ( Window  wID,
GC  gc 
)

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

Parameters
wIDWindow ID associated with the Expose event
gcThe GC (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 7895 of file window_helper.c.

void WBEndPaint ( Window  wID,
GC  gc 
)

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

Parameters
wIDWindow ID associated with the Expose event and passed to WBBeginPaint()
gcThe GC (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'

Header File: window_helper.h

Definition at line 7959 of file window_helper.c.

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 7679 of file window_helper.c.

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 7584 of file window_helper.c.

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 7609 of file window_helper.c.

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 7393 of file window_helper.c.

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 2857 of file window_helper.h.

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 7458 of file window_helper.c.

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 5588 of file window_helper.c.

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 5520 of file window_helper.c.

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 5476 of file window_helper.c.

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 7650 of file window_helper.c.

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 5563 of file window_helper.c.

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 7290 of file window_helper.c.

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 7346 of file window_helper.c.

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 7485 of file window_helper.c.

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 2889 of file window_helper.h.

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 7543 of file window_helper.c.