X11 Work Bench Toolkit  1.0
Event Handling

Typedefs

typedef int(* WBWinEvent )(Window wID, XEvent *pEvent)
 event callback function type for window events More...
 
typedef int(* WBAppEvent )(XEvent *pEvent)
 event callback function type for application events More...
 

Functions

Time WBGetLastEventTime (void)
 Main message loop, high level API to check for and retrieve the next event. More...
 
int WBCheckGetEvent (Display *pDisplay, XEvent *pEvent)
 Main message loop, high level API to check for and retrieve the next event. More...
 
void WBWaitForEvent (Display *pDisplay)
 Wait for an event, blocking indefinitely. More...
 
void WBDispatch (XEvent *pEvent)
 Generic Event Dispatcher, using message type to dispatch. More...
 
int WBAppDispatch (XEvent *pEvent)
 Dispatches an application XEvent. May be called directly. More...
 
int WBWindowDispatch (Window wID, XEvent *pEvent)
 Dispatches a window XEvent. May be called directly. More...
 
const char * WBEventName (int iEventID)
 debug function to return the name of an X11 event More...
 
int WBShowModal (Window wID, int bMenuSplashFlag)
 Shows a 'modal' window by processing events until the window closes. More...
 
void WBEndModal (Window wID, int iReturn)
 End a modal window with a specific return value. More...
 
int WBNextEvent (Display *pDisplay, XEvent *pEvent)
 low-level event queue wrapper. Implements the client-side event queue. Does not block if no events available. More...
 
int WBPostEvent (Window wID, XEvent *pEvent)
 Places a copy of the specified event at the end of the regular (internal) event queue. More...
 
int WBPostPriorityEvent (Window wID, XEvent *pEvent)
 Places a copy of the specified event at the end of the priority (internal) event queue. More...
 
void WBPostDelayedEvent (XEvent *pEvent, unsigned int nDelay)
 Delays placing a copy of the specified event at the end of the regular (internal) event queue by a specified number of milliseconds. More...
 
int WBPostAppEvent (XEvent *pEvent)
 Places a copy of the specified event at the end of the priority (internal) event queue. More...
 
void WBPostDelayedSetFocusAppEvent (Display *pDisplay, Window wID, Window wIDFrom, unsigned int nDelay)
 Creates a 'set focus' ClientMessage event for the application event handler. More...
 
void WBProcessExposeEvent (XExposeEvent *pEvent)
 low-level event processing, internal handling of Expose events More...
 
void WBMouseCancel (Display *pDisplay, Window wID)
 low-level event processing, internal handling of Expose events More...
 

Detailed Description

Event handling in X11 involves an event handler loop and methods by which the various events can be dispatched to window callback functions, or to the application's event handler. The X11workbench Toolkit API has provisinos for event prioritization, asynchronous processing, and the generation of 'internal events' (see aWM_CHAR, aWM_POINTER, aWM_TIMER).

Typedef Documentation

WBAppEvent

event callback function type for application events

Parameters
pEventA pointer to the XEvent structure passed to the callback function
Returns
Event-specific value. Typically returns zero if the event was not processed, non-zero if further processing is not necessary

An event callback for the application should be declared according to this defined type

Header File: window_helper.h

Definition at line 183 of file window_helper.h.

WBWinEvent

event callback function type for window events

Parameters
wIDThe Window ID for the window receiving the event notification
pEventA pointer to the XEvent structure passed to the callback function
Returns
Event-specific value. Typically returns zero if the event was not processed, non-zero if further processing is not necessary

Event callbacks for windows should be declared according to this defined type

Header File: window_helper.h

Definition at line 171 of file window_helper.h.

Function Documentation

int WBAppDispatch ( XEvent *  pEvent)

Dispatches an application XEvent. May be called directly.

Parameters
pEventA pointer to an XEvent structure to process

Application events have a window ID of None, and are dispatched to the registered Application callback. In the absence of a callback, default processing is performed.

Header File: window_helper.h

Definition at line 4617 of file window_helper.c.

int WBCheckGetEvent ( Display *  pDisplay,
XEvent *  pEvent 
)

Main message loop, high level API to check for and retrieve the next event.

Parameters
pDisplayA pointer to the Display to query events on
pEventA pointer to an XEvent structure to receive the event data
Returns
A non-zero value if there is an event to be processed, otherwise zero
Implementation of the X11workbench Toolkit API is centered around the API's event
loop processing.  The main application should implement its message loop by repeatedly
calling WBCheckGetEvent() or WBNextEvent() and passing any retrieved event to \ref WBDispatch().
Internally, WBCheckGetEvent() calls the X___CheckEvent functions correctly, dispatches Expose
events for asynchronous processing, translates keyboard and pointer events, and handles
internally queued events (such as timers and 'posted' events).

The function returns a non-zero value if there is an event is to be processed.

To correctly implement a message loop, your code should be similar to the following:\n
XEvent event;
while ( !bQuitFlag )
{
if( !WBCheckGetEvent(pX11Display, &event) )
{
// as needed, perform an iteration of background processing here
// With nothing else to do, SLEEP if there is no event in the message queue
// and no background processing to be performed.
// (alternately, you could use WBWaitForEvent() if you do not need periodic
// wake-up for background processing)
// implementations that support 'nanosleep' should use it
#ifdef HAVE_NANOSLEEP
struct timespec tsp;
tsp.tv_sec = 0;
tsp.tv_nsec = 1000000; // wait for 1 msec
nanosleep(&tsp, NULL);
#else // HAVE_NANOSLEEP
usleep(1000); // 1000 microsecs - a POSIX alternative to 'nanosleep'
#endif // HAVE_NANOSLEEP
continue;
}
WBDispatch(&event);
}

NOTE: If you do not want to do any background processing, consider using WBWaitForEvent() instead of 'usleep' or 'nanosleep'.

To only retrieve 'internally queued' events, see WBNextEvent()

Header File: window_helper.h

Definition at line 3762 of file window_helper.c.

void WBDispatch ( XEvent *  pEvent)

Generic Event Dispatcher, using message type to dispatch.

Parameters
pEventA pointer to an XEvent structure to process

Call this function to generically dispatch an XEvent. The application will need to check for a 'quit' state independently. See WBWindowDispatch(), WBAppDispatch()

Header File: window_helper.h

Definition at line 4717 of file window_helper.c.

void WBEndModal ( Window  wID,
int  iReturn 
)

End a modal window with a specific return value.

Parameters
wIDWindow ID of the window that must end its modal loop
iReturnThe 'return' value from the modal loop - see WBShowModal()

Call this function from within a modal window's event process to close the window and exit from WBShowModal with the specified value in 'iReturn'

Header File: window_helper.h

Definition at line 2224 of file window_helper.c.

const char* WBEventName ( int  iEventID)

debug function to return the name of an X11 event

Parameters
iEventIDAn event type identifier
Returns
A const pointer to an ASCII 0-byte terminated character string representing the event ID, or NULL

Intended primarily for debug messages, it returns a pointer to an ASCII string containing the name of the event, based on its event ID. The ID of the event is the value of 'type' within the XEvent structure.

Header File: window_helper.h

Definition at line 8714 of file window_helper.c.

Time WBGetLastEventTime ( void  )

Main message loop, high level API to check for and retrieve the next event.

Returns
The 'Time' value for the last event that had a server timestamp

In some cases it's necessary to know an approximate value of the X server's timestamp. The message loop will capture the timestamp value whenever it can. Use this function to return the best known server time value for the default Display.

Header File: window_helper.h

Definition at line 3755 of file window_helper.c.

void WBMouseCancel ( Display *  pDisplay,
Window  wID 
)

low-level event processing, internal handling of Expose events

Parameters
pDisplayThe display for the mouse activity. A value of NULL uses the default display, either for 'wID', or the system default if wID is 'None'.
wIDThe window to post the 'WB_POINTER_CANCEL' message to. This window should have the input focus. A value of 'None' indicates the window with the input focus.

Call this function to effectively 'cancel' any operation involving the mouse. This will un-do any 'drag' operations and send a WM_POINTER Client Message event with the 'WB_POINTER_CANCEL', and optionally un-grab the mouse (and keyboard, as needed). In the case of a Modal operation, this may differ from normal Asynchronous operations. Additionally, if there are any mouse messages already in the queue, this will not remove them. It will be up to the caller to deal with that. This function ONLY fixes the status and capture of the mouse.

Header File: window_helper.h

Definition at line 5390 of file window_helper.c.

int WBNextEvent ( Display *  pDisplay,
XEvent *  pEvent 
)

low-level event queue wrapper. Implements the client-side event queue. Does not block if no events available.

Parameters
pDisplayThe Display pointer to query events on
pEventA pointer to an XEvent structure to receive event info
Returns
a non-zero value if an event was obtained, or zero if no event was available

Similar to XNextEvent, this function checks the internal event queues for an event. Unlike XNextEvent it does not wait for an event to be available before returning. The function returns zero if there are no events to be processed.

This function will not pull events out of the X server's event queue. It ONLY manages 'internal' queued events, prioritizing them as needed.

See WBCheckGetEvent(), WBWaitForEvent()

Header File: window_helper.h

Definition at line 8577 of file window_helper.c.

int WBPostAppEvent ( XEvent *  pEvent)

Places a copy of the specified event at the end of the priority (internal) event queue.

Parameters
pEventA pointer to an XEvent structure containing the event info
Returns
A non-zero value on error, or zero if successful

The preferred method of event processing between windows is to post them to one of the internal event queues, rather than using XSendEvent or calling WBDispatch directly.
Use WBPostAppEvent for application events (where the window ID is 'None')

Header File: window_helper.h

Definition at line 8616 of file window_helper.c.

void WBPostDelayedEvent ( XEvent *  pEvent,
unsigned int  nDelay 
)

Delays placing a copy of the specified event at the end of the regular (internal) event queue by a specified number of milliseconds.

Parameters
pEventA pointer to an XEvent structure containing the event info
nDelayThe number of milliseconds to delay posting the event

Use this function to effectively delay an event's posting to the internal queue for a specified period of time, in milliseconds. For application messages, specify 'None' for the Window ID in the XEvent structure (otherwise specify the correct Window ID). After the time delay, the event will be retrieved and returned via WBCheckGetEvent(), or WBNextEvent(), similar to a timer message. If the window specified in the message is destroyed before the timeout, the message will be ignored.

Header File: window_helper.h

Definition at line 8595 of file window_helper.c.

void WBPostDelayedSetFocusAppEvent ( Display *  pDisplay,
Window  wID,
Window  wIDFrom,
unsigned int  nDelay 
)

Creates a 'set focus' ClientMessage event for the application event handler.

Parameters
pDisplayThe Display pointer, or 'None' to use default
wIDThe Window ID of the window to be set active, raised, and mapped
wIDFromThe previous window that was active, or None
nDelayThe delay in milliseconds before this action takes place (useful to prevent race conditions)

Causes (reliable) 'Set Active' 'Set Input Focus' 'Raise Window' and 'Map Window' events to be applied to a particular window. In many cases window managers may differ in their handling of things like 'XSetFocus' to set focus to a window. By handling this in the application event queue, it is possible to delay events asynchronously in a manner that avoids a race condition from the window manager. Clicking on a window, or using ALT+Tab, or switching desktops may cause unexpected 'things' to take place. By forcing the window to be ACTIVE and also using the normal 'XSetInputFocus' function, as well as 'Raising' and mapping the window, THIS method is likely to work everywhere, and in a consistent manner.

Header File: window_helper.h

Definition at line 8629 of file window_helper.c.

int WBPostEvent ( Window  wID,
XEvent *  pEvent 
)

Places a copy of the specified event at the end of the regular (internal) event queue.

Parameters
wIDThe Window ID of the event to be posted. The default 'Display *' will be used
pEventA pointer to an XEvent structure containing the event info
Returns
A non-zero value on error, or zero if successful

The preferred method of event processing between windows is to post them to one of the internal event queues, rather than using XSendEvent() or calling WBDispatch() or WBWindowDispatch() directly.
You should always use this function for asynchronously posting non-priority events, such as notifications and timers, or when recursion may occur. Note that any pointers or X11 resources that are passed using XEvent may not be valid by the time they are received. If you must pass volatile data to a window, use WBDispatch() or WBWindowDispatch() instead.

Header File: window_helper.h

Definition at line 8582 of file window_helper.c.

int WBPostPriorityEvent ( Window  wID,
XEvent *  pEvent 
)

Places a copy of the specified event at the end of the priority (internal) event queue.

Parameters
wIDThe Window ID of the event to be posted. The default 'Display *' will be used
pEventA pointer to an XEvent structure containing the event info
Returns
A non-zero value on error, or zero if successful

The preferred method of event processing between windows is to post them to one of the internal event queues, rather than using XSendEvent() or calling WBDispatch() or WBWindowDispatch() directly.
Use WBPostPriorityEvent for priority events, such as UI handling (where performance is critical)

Header File: window_helper.h

Definition at line 8600 of file window_helper.c.

void WBProcessExposeEvent ( XExposeEvent *  pEvent)

low-level event processing, internal handling of Expose events

Parameters
pEventA pointer to an XExposeEvent structure for an Expose event

Instead of passing Expose events directly along to the respective window, they are first consolidated, and then re-prioritized for optimimum display performance.
Expose events typically come in bunches, and all too frequently. By delaying their processing, AND consolidating them into a single event, it is possible to minimize the un-necessary re-drawing of windows and improve the 'apparent speed' of your applicatino. Normally this is done within WBCheckGetEvent() automatically. If you decide to implement the message prioritization yourself, you can use this function to handle Expose events for you, and correctly prioritize them.

Header File: window_helper.h

Definition at line 5371 of file window_helper.c.

int WBShowModal ( Window  wID,
int  bMenuSplashFlag 
)

Shows a 'modal' window by processing events until the window closes.

Parameters
wIDWindow to be made modal
bMenuSplashFlagTri-state boolean indicating menu/splash/normal. A value of 0 is normal, > 0 menu, < 0 splash
Returns
-1 on error, or the dialog box's 'WBEndModal()' iReturn value

Use this function to show a 'modal' window. The function returns when the window is closed. 'bMenuFlag' is > 0 if menu semantics need to be applied to the modal window, or < 0 if splash semantics need to be applied. Otherwise, it is treated as a NORMAL (dialog) window.

The return value is -1 on error, or the value specified by 'iReturn' in the call to WBEndModal().

Header File: window_helper.h

Definition at line 1925 of file window_helper.c.

void WBWaitForEvent ( Display *  pDisplay)

Wait for an event, blocking indefinitely.

Parameters
pDisplaya pointer to the Display on which to wait for events

Call this function to wait until a new event is available in the event queue. This function will block indefinitely until such an event is available.
NOTE: if 'bQuitFlag' is set, this function will return immediately.

See WBNextEvent(), WBCheckGetEvent()

Header File: window_helper.h

Definition at line 3767 of file window_helper.c.

int WBWindowDispatch ( Window  wID,
XEvent *  pEvent 
)

Dispatches a window XEvent. May be called directly.

Parameters
wIDThe Window ID that will be 'dispatched' the event, regardless of the event structure contents
pEventA pointer to an XEvent structure to process

Dispatches an XEvent for the specified window. Normally, WBDispatch will call this function using the window ID from the XEvent itself, and pass that ID as the first parameter. A caller may choose to send the event to a different window, specifying its window ID instead. This is similar to a modal 'Event Send' and can be useful to have a parent or child widnow handle a particular type of event (rather than the destined window).

Header File: window_helper.h

Definition at line 4737 of file window_helper.c.