Event Handling

Modules
	ClientMessage Atoms
	Data Types, Enumerations, and Definitions
	Keyboard Event Handling
	Mouse Pointer Event Handling

Macros
#define	WB_STANDARD_INPUT_MASK   (FocusChangeMask | PropertyChangeMask | ExposureMask | StructureNotifyMask | VisibilityChangeMask | SubstructureNotifyMask)
	'Standard' input mask, bit flag for window creation More...
#define	WB_KEYBOARD_INPUT_MASK   (KeyPressMask | KeyReleaseMask)
	'Keyboard' input mask, bit flag for window creation More...
#define	WB_MOUSE_INPUT_MASK   (ButtonPressMask | ButtonReleaseMask | PointerMotionMask | EnterWindowMask | LeaveWindowMask)
	'Mouse' input mask, bit flag for window creation More...

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 definition 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 aWB_CHAR, aWB_POINTER, aWB_TIMER).

Macro Definition Documentation

WB_KEYBOARD_INPUT_MASK

#define WB_KEYBOARD_INPUT_MASK   (KeyPressMask | KeyReleaseMask)

'Keyboard' input mask, bit flag for window creation

'Keyboard' input mask. Use this as a parameter to XSelectInput to enable keyboard events to be sent to the window
This bit mask may be 'or'd with other bit masks as needed.

Definition at line 976 of file window_helper.h.

WB_MOUSE_INPUT_MASK

#define WB_MOUSE_INPUT_MASK   (ButtonPressMask | ButtonReleaseMask | PointerMotionMask | EnterWindowMask | LeaveWindowMask)

'Mouse' input mask, bit flag for window creation

'Mouse' input mask. Use this as a parameter to XSelectInput to enable mouse events to be sent to the window
This bit mask may be 'or'd with other bit masks as needed.

Definition at line 984 of file window_helper.h.

WB_STANDARD_INPUT_MASK

#define WB_STANDARD_INPUT_MASK   (FocusChangeMask | PropertyChangeMask | ExposureMask | StructureNotifyMask | VisibilityChangeMask | SubstructureNotifyMask)

'Standard' input mask, bit flag for window creation

'Standard' input mask. Use this as a parameter to XSelectInput to enable standard events to be sent to the window
This bit mask may be 'or'd with other bit masks as needed.

Definition at line 968 of file window_helper.h.

Typedef Documentation

WBAppEvent

WBAppEvent

event callback function type definition for application events

typedef int (* WBAppEvent)(XEvent *pEvent);

Parameters

pEvent

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

WBWinEvent

WBWinEvent

event callback function type for window events

typedef int (* WBWinEvent)(Window wID, XEvent *pEvent);

Parameters

wID	The Window ID for the window receiving the event notification
pEvent	A 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 221 of file window_helper.h.

Function Documentation

WBAppDispatch()

int WBAppDispatch

(

XEvent *

pEvent

)

Dispatches an application XEvent. May be called directly.

Parameters

pEvent

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

WBCheckGetEvent()

int WBCheckGetEvent	(	Display *	pDisplay,
		XEvent *	pEvent
	)

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

Parameters

pDisplay	A pointer to the Display to query events on
pEvent	A 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 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:

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)

    WBDelay(100);  // 100 microsecs - 0.1 millisecond

    continue;
  }

  WBDispatch(&event);
}

NOTE: If you do not want to do any background processing, consider using WBWaitForEvent() instead of WBDelay()

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

Header File: window_helper.h

Definition at line 3725 of file window_helper.c.

WBDispatch()

void WBDispatch

(

XEvent *

pEvent

)

Generic Event Dispatcher, using message type to dispatch.

Parameters

pEvent

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

WBEndModal()

void WBEndModal	(	Window	wID,
		int	iReturn
	)

End a modal window with a specific return value.

Parameters

wID	Window ID of the window that must end its modal loop
iReturn	The '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 2165 of file window_helper.c.

WBEventName()

const char* WBEventName

(

int

iEventID

)

debug function to return the name of an X11 event

Parameters

iEventID

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

WBGetLastEventTime()

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

WBMouseCancel()

void WBMouseCancel	(	Display *	pDisplay,
		Window	wID
	)

low-level event processing, internal handling of Expose events

Parameters

pDisplay	The display for the mouse activity. A value of NULL uses the default display, either for 'wID', or the system default if wID is 'None'.
wID	The 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 WB_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 5335 of file window_helper.c.

WBNextEvent()

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

pDisplay	The Display pointer to query events on
pEvent	A 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 8839 of file window_helper.c.

WBPostAppEvent()

int WBPostAppEvent

(

XEvent *

pEvent

)

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

Parameters

pEvent

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

WBPostDelayedEvent()

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

pEvent	A pointer to an XEvent structure containing the event info
nDelay	The 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 8857 of file window_helper.c.

WBPostDelayedSetFocusAppEvent()

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

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

Parameters

pDisplay	The Display pointer, or 'None' to use default
wID	The Window ID of the window to be set active, raised, and mapped
wIDFrom	The previous window that was active, or None
nDelay	The 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 'XSetInputFocus' 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 8891 of file window_helper.c.

WBPostEvent()

int WBPostEvent	(	Window	wID,
		XEvent *	pEvent
	)

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

Parameters

wID	The Window ID of the event to be posted. The default 'Display *' will be used
pEvent	A 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 8844 of file window_helper.c.

WBPostPriorityEvent()

int WBPostPriorityEvent	(	Window	wID,
		XEvent *	pEvent
	)

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

Parameters

wID	The Window ID of the event to be posted. The default 'Display *' will be used
pEvent	A 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 8862 of file window_helper.c.

WBProcessExposeEvent()

void WBProcessExposeEvent

(

XExposeEvent *

pEvent

)

low-level event processing, internal handling of Expose events

Parameters

pEvent

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

WBShowModal()

int WBShowModal	(	Window	wID,
		int	bMenuSplashFlag
	)

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

Parameters

wID	Window to be made modal
bMenuSplashFlag	Tri-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 1862 of file window_helper.c.

WBWaitForEvent()

void WBWaitForEvent

(

Display *

pDisplay

)

Wait for an event, blocking indefinitely.

Parameters

pDisplay

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

WBWindowDispatch()

int WBWindowDispatch	(	Window	wID,
		XEvent *	pEvent
	)

Dispatches a window XEvent. May be called directly.

Parameters

wID	The Window ID that will be 'dispatched' the event, regardless of the event structure contents
pEvent	A pointer to an XEvent structure to process

Returns

The integer value returned by the window's event callback

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 window handle a particular type of event (rather than the destined window).

Header File: window_helper.h

Definition at line 4678 of file window_helper.c.