Classes Class XbpWindow() :gesture

Event XbpWindow():gesture Foundation

A touch gesture was performed.

Syntax 
:gesture := {|nId, aInfo, self| ... }
:gesture( nId, aInfo ) --> self
xbeP_Gesture (1048672)
Parameters
<nId>
The numeric identifier of the touch gesture which is executed.
<aInfo> := {aPos, aLastPos, aStartPos,xArgs,xLastArgs,xStartArgs,nState}
An array with seven elements which contain information about the touch gesture.
Return

This method returns the object executing the method (self).

Description

The operating system provides default behavior for touch gestures on computers featuring a touch digitizer. This allows the Xbase Parts to be operated with the finger in addition to the keyboard and mouse. In cases were the standard behavior provided by the system is insufficient or if a custom Xbase Part class is to be created which is to be made touch-aware, the xbeP_Gesture event can be used to implement custom behavior.

Support for gesture events must be explicitly enabled using the :inputMode member variable. Afterwards, an xbeP_Gesture event is generated by the system whenever a touch gesture is performed by the user.

The <nId> parameter specifies the kind of gesture which is executed. The system recognizes a number of predefined gestures which can be used to move, zoom or otherwise manipulate objects on the screen. The following table lists the touch gestures which are recognized by the system. The corresponding constants are defined in the xbp.ch include file.

Supported touch gestures
Gesture Identifier Description
XBP_GESTURE_ZOOM Identifies a two-finger gesture where the distance between the fingers is varied to indicate the scaling or zoom level of an element.
XBP_GESTURE_PAN Identifies a swipe gesture executed with one or two fingers which is used to move an element or scroll a window.
XBP_GESTURE_ROTATE Identifies a two-finger gesture where the fingers are rotated around a center point to indicate the angle of rotation of an element.
XBP_GESTURE_TWOFINGERTAP Identifies a tap gesture executed with two fingers.
XBP_GESTURE_PRESSANDTAP Identifies a two-finger gesture in which the first finger is brought down to select an element, and a tap is executed with the second finger. This gesture is often used to trigger a certain standard action on an element, such as opening a context menu.

For compatibility reasons, a (one fingered) tap gesture is reported as a left-button mouse click to the application, see :lbDown and :lbClick. The gesture configured as the equivalent to a right-button mouse click is reported as a mouse right-click, see :rbDown and :rbClick. No xbeP_Gesture events are generated in these cases.

The array in the <aInfo> parameter contains additional information about the touch gesture. The values contained in the elements of the array vary with each gesture.

Information associated with the Pan gesture
aInfo Array Element Description
XBP_GESTUREINFO_STARTPOS Indicates the position the pan gesture was begun at. The element contains an array with the x and y coordinate, specified relative to the desktop object see the AppDesktop() function).
XBP_GESTUREINFO_POS Indicates the current position of the pan.
XBP_GESTUREINFO_LASTPOS Indicates the position specified in the last xbeP_Gesture event.
XBP_GESTUREINFO_STARTARGS Indicates the distance between the two fingers when the gesture was begun. This element is 0 for one-finger pans.
XBP_GESTUREINFO_ARGS Specifies the distance between the two fingers executing the gesture. This element is 0 for one-finger pans.
XBP_GESTUREINFO_LASTARGS Indicates the distance specified in the last xbeP_Gesture event.
XBP_GESTUREINFO_STATE Contains information about the current state of the gesture. See the table below for more information.

Information associated with the Zoom gesture
aInfo Array Element Description
XBP_GESTUREINFO_STARTPOS Indicates the center point of the zoom. The element contains an array with the x and y coordinate, specified relative to the desktop object (see the AppDesktop() function).
XBP_GESTUREINFO_POS Contains the same information as the preview element and can be ignored.
XBP_GESTUREINFO_LASTPOS Contains the same information as the previous element and can be ignored.
XBP_GESTUREINFO_STARTARGS Indicates the distance between the two fingers when the gesture was begun.
XBP_GESTUREINFO_ARGS Indicates the distance between the two fingers executing the gesture. The ratio between the current and the start distance defines the current zoom level.
XBP_GESTUREINFO_LASTARGS Indicates the distance specified in the last xbeP_Gesture event.
XBP_GESTUREINFO_STATE Contains information about the current state of the gesture. See the table below for more information.

Information associated with the Rotate gesture
aInfo Array Element Description
XBP_GESTUREINFO_STARTPOS Indicates the center point of the rotation. The element contains an array with the x and y coordinate, specified relative to the desktop object (see the AppDesktop() function).
XBP_GESTUREINFO_POS Contains the same information as the previous element and can be ignored.
XBP_GESTUREINFO_LASTPOS Contains the same information as the previous element and can be ignored.
XBP_GESTUREINFO_STARTARGS Indicates the start angle of the rotation. This element is always 0 for rotate gestures.
XBP_GESTUREINFO_ARGS Indicates the current angle of rotation. Positive values indicate a counter-clockwise direction.
XBP_GESTUREINFO_LASTARGS Indicates the rotation angle specified in the last xbeP_Gesture event.
XBP_GESTUREINFO_STATE Contains information about the current state of the gesture. See the table below for more information.

Information associated with the Two-Finger Tap gesture
aInfo Array Element Description
XBP_GESTUREINFO_STARTPOS Indicates the center point between the two fingers. The element contains an array with the x and y coordinate, specified relative to the desktop object (see the AppDesktop() function).
XBP_GESTUREINFO_POS Contains the same information as the previous element and can be ignored.
XBP_GESTUREINFO_LASTPOS Contains the same information as the previous element and can be ignored.
XBP_GESTUREINFO_STARTARGS Indicates the distance between the two fingers executing the gesture.
XBP_GESTUREINFO_ARGS Contains the same information as the previous element and be ignored.
XBP_GESTUREINFO_LASTARGS Contains the same information as the previous element and can be ignored.
XBP_GESTUREINFO_STATE Contains information about the current state of the gesture. See the table below for more information.

Information associated with the Press and Tap gesture
aInfo Array Element Description
XBP_GESTUREINFO_STARTPOS Indicates the position the first finger comes down on. The element contains an array with the x and y coordinate, specified relative to the desktop object (see the AppDesktop() function).
XBP_GESTUREINFO_POS Contains the same information as the first element. The element can be ignored for the press and tap gesture.
XBP_GESTUREINFO_LASTPOS Contains the same information as the first element. The element can be ignored for the press and tap gesture.
XBP_GESTUREINFO_STARTARGS Indicates the distance between the first and the second finger.
XBP_GESTUREINFO_ARGS Contains the same information as the previous element. Can be ignored for the press and tap gesture.
XBP_GESTUREINFO_LASTARGS Contains the same information as the previous element. Can be ignored for the press and tap gesture.
XBP_GESTUREINFO_STATE Contains information about the current state of the gesture. See the table below for more information.

The last array element (XBP_GESTUREINFO_STATE) contains information about the current state of the gesture. The element contains a combination of the constants listed in the following table.

Gesture state information (XBP_GESTUREINFO_STATE)
Constant Description
XBP_GESTURESTATE_BEGIN The xbeP_Gesture event marks the beginning of the gesture.
XBP_GESTURESTATE_END The gesture is finished. The xbeP_Gesture event is the last for the current gesture.
XBP_GESTURESTATE_HASINERTIA The gesture has triggered inertia. In this case, the system continues to generate xbeP_Gesture events after the gesture is finished. Inertiagenerated events have this state flag set.

In Xbase++, Xbase Parts are created and maintained by a special system thread called the UI thread. Both the :gesture() callback method and the :gesture callback code block are executed on that thread. Therefore, during processing of an xbeP_Gesture event, the application must assume all thread-local settings to be at their default values. A work area opened previously may not be available, for example. To prevent thread-dependencies and to allow for a speedy processing of a xbeP_Gesture event, it is recommended for the application to prepare data required for processing touch gestures before the window object is created.

Touch gestures are supported on Windows 7 and newer operating systems.

Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.