Registers the event handler function for a given widget.

widget — The ID of the widget to add the event handler to (long).

eventmask — The value of the X Event mask (long). See the wtxlib.pro file in the Standard Library and the Xlib Reference Manual (O'Reilly & Associates, Inc., 1989) for more information on this parameter.

handler — A string containing the X event handler procedure name.

client_data — A variable. The value of this variable is passed to the callback routine.

status — One (1) indicates success; zero (0) indicates failure.

Nonmaskable — If present and nonzero, nonmaskable events are intercepted by the event handler. Such events include GraphicsExpose, NoExpose, SelectionClear, SelectionRequest, SelectionNotify, ClientMessage, and MappingNotify.

Noparams — If nonzero, calls the event handler procedure with three parameters; widget (the widget ID), client_data, and the event structure.

An event handler is a PV‑WAVE 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.

Under Windows, Windows events are mapped to X events as shown in Mapping Windows Events:

The event structure returned by the event handler (or callback) procedure on Windows platforms contains the following tag fields:

event — Event handle.

type — Event type (ButtonPress, KeyPress etc., as listed in the file wtxlib.pro in the Standard Library).

hwnd — Windows window handle.

message — Windows message ID.

wParam — Windows WPARAM.

lParam — Windows LPARAM.

time — Time of the event.

x — x-coordinate of the mouse pointer.

y — y-coordinate of the mouse pointer.

state — Indicates the state of all of the buttons and modifier keys at the time of the event, represented by a mask of the button and modifier key symbols.

button — Indicates which button changed state to trigger this event.

GestureInfo — A structure containing gesture-specific event information. See Windows gestures in PV-WAVE Drawing Areas for additional information.

For information on the requirements for writing event handler procedures, see Adding Event Handlers.

A subset of the Windows gesture interface has been enabled for the PV-WAVE Drawing Area widget on touch screen enabled devices. The Windows gesture interface adds the ability to capture and interpret a more complex set of predefined gestures within PV-WAVE applications. Gestures are only accepted by the Drawing Area widget and require event handlers to be registered by the PV-WAVE application using WtAddHandler.

The following table shows the supported gestures and their associated event masks:

It is important to note that the gesture names are simply descriptions of the gesture motions and do not necessarily describe what a PV-WAVE application does when it receives a gesture event. The one exception is the Panning gesture, which causes a Drawing Area widget to pan in the direction of the finger motion. The Panning event is also passed to a Drawing Area if a Panning event handler is registered.

An in-depth discussion of each gesture along with a drawing of the motion required and the elements of the GestureInfo structure affected by each is available by searching for "Windows Touch Gesture Overview" at msdn.microsoft.com. We strongly recommend that interested gesture developers examine the information provided at that site and the PV-WAVE code examples and a developer-oriented README file found in <RW_DIR>\wave\demo\gestures.

The PV-WAVE GestureInfo structure differs from the Windows GESTUREINFO structure. This is to make it easier for PV-WAVE users to extract the relevant event information in their application or to remove elements used only by the operating system.

dwFlags — The state of the gesture.

ptsLocation_x — The X coordinates associated with the gesture in device coordinates.

ptsLocation_y — The Y coordinates associated with the gesture in device coordinates.

ullArguments — A PV-WAVE LONG variable containing additional info for certain gestures.

dwID — The identifier of the gesture command.

radian_start — The starting angle, in radians, of the beginning of a rotate gesture.

radian_end — The angle change, in radians, since the rotate gesture started.

The following code fragments demonstrate the use of WtAddHandler.

.

.

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

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

  ...

END

For more information about how to write an application program based on the PV‑WAVE Widget Toolbox, refer to Using the Widget Toolbox in the PV‑WAVE Application Developer’s Guide.