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 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.
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 in the in the PV‑WAVE Application Developer’s Guide.
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:
|
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.
|
Note: |
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.
