Adding Event Handlers

Application Developer Guide > Using the Widget Toolbox > Adding Event Handlers

An event handler is a procedure that is executed when a specific type of event occurs within a widget. Some, all, or no X events can be handled using one or more event handlers. To register an event handler for events that occur in a widget use the system function WtAddHandler:

status = WtAddHandler(wid, eventmask, handler, [client_data])

This function registers a callback procedure specified by the handler parameter (a string) as an event handler for the events specified by the eventmask parameter. The eventmask parameter must be one of the standard event masks defined in the file wtxlib.pro in the Standard Library. The wid parameter is the ID of the widget to add the handler to.

You can register event handlers for multiple event masks using the OR operator. For example, ButtonUp and ButtonDown are combined with ButtonUp OR ButtonDown, causing the event to be triggered when the mouse button is pressed and when it is released.

The application can optionally use the client_data parameter to specify some application-defined data to be passed to the event handler procedure when the callback is invoked. If client_data is a local variable (defined only in the current procedure), a copy of that variable is created and passed (by value). If client_data is a global variable (defined in a Common Block), it is passed by reference.

note

Rogue Wave has ported a subset of the Widget Toolbox (Wt) functionality that is available for Motif to Microsoft Windows. Because the Widget Toolbox under Windows is not a complete implementation, we recommend that Windows developers use the PV-WAVE 10.0 Widgets (Ww) layer or the VDA Tools when developing GUI applications.

The form of Widget Toolbox event handlers is:

PRO EventHandlerProc, widget, client_data, $
nparams, eventmask, event

where:

widget—The widget ID.

client_data—The client_data passed to WtAddHandler.

nparams—The number of event handler-specific parameters after nparams. (This number is always 2, for the eventmask and event parameters.)

eventmask—One of the standard event masks defined in the file wtxlib.pro in the Standard Library. For a description of event masks, see Appendix E, “Event Reference”, of the Xlib Reference Manual, Volume 2, (O’Reilly & Associates, Inc., 1989).

event—Structure containing all the fields as defined for the Xlib XEvent structure. If you are developing under Motif, see Appendix E, “Event Reference”, of the Xlib Reference Manual, Volume 2, (O’Reilly & Associates, Inc., 1989) for a description of event structures.

Example

pane=WtCreate('menu', PopupMenuWidget, parent)

status = WtAddHandler(pane, ButtonPressMask, 'PostMenu', parent)

PRO PostMenu, wid, parent, nparams, mask, event

@wtxlib

status=WtPointer("GetLocation", wid, state)

if (Button3Mask AND state(6)) ne 0 then $
status=WtSet(pane,POPUP=event)

END

X Event Handler Procedure Example

PRO handler, widget, data, nparams, mask, event

...

END

Version 2017.0