WtAddHandler Function
Registers the event handler function for a given widget.
Usage
status = WtAddHandler(widget, eventmask, handler[, client_data])
Input Parameters
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.
Returned Value
status — One (1) indicates success; zero (0) indicates failure.
Keywords
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.
Discussion
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.
 
note
Rogue Wave has ported a subset of the Widget Toolbox (Wt) functionality available for Motif to Microsoft Windows. Because the Widget Toolbox under Windows is not a complete implementation, we recommend that Windows developers use PV‑WAVE Widgets (Ww) layer or the VDA Tools when developing GUI applications.
Under Windows, Windows events are mapped to X events as shown in Table 19-3: Mapping Windows Events:
 
Mapping Windows Events
Windows Events
X Events
WM_KEYDOWN, WM_CHAR, WM_SYSCHAR
KeyPressMask
WM_KEYUP
KeyReleaseMask
WM_KILLFOCUS, WM_SETFOCUS
FocusChangeMask (FocusOut, FocusIn)
WM_LBUTTONDOWN, WM_MBUTTONDOWN,
WM_RBUTTONDOWN
ButtonPressMask
WM_LBUTTONUP, WM_MBUTTONUP,
WM_RBUTTONUP
ButtonReleaseMask
WM_NCHITTEST, WM_MOUSEMOVE
PointerMotionMask
WM_PAINT
ExposureMask
WM_SIZE, WM_WINDOWPOSCHANGED
StructureNotifyMask
WM_PALETTECHANGED,
WM_SYSCOLORCHANGE
ColormapChangeMask
Event Structure for Windows Platforms
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.
xx-coordinate of the mouse pointer.
yy-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.
Windows gestures in PV-WAVE Drawing Areas
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.
 
note
By default, all PV-WAVE widgets on touch-enabled devices have the ability to interpret single finger touches as mouse events to manipulate scroll bars, select buttons, and re-position windows with no special event handlers required.
The following table shows the supported gestures and their associated event masks:
 
Supported Gestures and Event Masks
Gesture Name
Event Mask
Panning
GesturePanMask
Press and Tap
GesturePressAndTapMask
Zoom
GestureZoomMask
Rotate
GestureRotateMask
Two Finger Tap
GestureTwoFingerTapMask
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.
PV-WAVE GestureInfo structure
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.
 
Warning
Windows uses the upper left corner of the screen as the origin (device coordinates 0, 0). PV-WAVE uses the lower left corner of the drawing area as the origin of its coordinate system.
For an example dealing with these different origins, please see tap_Demo.pro in the <RW_DIR>\wave\demo\gestures directory.
Example
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
X Event Handler Procedure Example
PRO handler, widget, data, nparams, mask, event
  ...
END
See Also
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.