Gesturing Overview

From RAD Studio
Jump to: navigation, search

Go Up to VCL

VCL and FireMonkey use the RAD Studio gesturing framework, which is separately implemented in the FireMonkey and VCL libraries. The gesturing-related VCL and FMX classes, methods, and properties are parallel in the two libraries, although the unit names might differ (Vcl.Controls vs. FMX.Types, for example). On all platforms, both VCL and FireMonkey support the use of the standard gestures, as well as interactive gestures (Vcl.Controls.TInteractiveGesture and FMX.Types.TInteractiveGesture).

For more information about using gestures, see the videos RAD Studio 2010 Touch Gesture Capabilities and Delphi 2010, Using Touch Features and Gestures.

What Is a Gesture

The gesturing framework enables your VCL and FireMonkey applications to use gestures (alternative input mechanisms provided by touch hardware). A gesture is a motion performed using a touch device that triggers an event or an action.

The primary touch devices used are:

  • Finger
  • Pen
  • Mouse

Component Options for Gesturing

Most components that derive from TControl publish the Touch property and have gesturing options. After you assign a GestureManager to your component, you can see the standard gesturing options in the Object Inspector, listed under the Touch property. For more details, see Using Gesturing in Your Applications.

Standard Gestures

The Standard library of gestures consists of over 30 gestures such as Left, Right, Scratchout, Circle, and ChevronUp. These gestures are associated with the enumeration FMX.Types.TStandardGesture or Vcl.Controls.TStandardGesture.

For an illustrated list of all the standard gestures, see TStandardGesture Enum.

Interactive Gestures

Interactive gestures are multi-touch gestures which trigger the OnGesture event continuously as the gesture is performed. These gestures include panning, zooming, rotating, two-finger tap and tap-and-press. The EventInfo parameter of the OnGesture event provides additional information about the gesture being performed, such as the location of touch point, angle of rotation, inertia of a panning motion, and so forth. Interactive gestures require a multi-touch enabled operating system, and can only be invoked by a touch input device. Interactive gestures are associated with the enumeration FMX.Types.TInteractiveGesture or Vcl.Controls.TInteractiveGesture.

The supported InteractiveGestures are: "Zoom", "Pan", "Rotate", "Two Finger Tap", "Long Tap", "Double Tap", and "Press And Tap".

InteractiveGestureOptions (VCL Only)

InteractiveGestureOptions are associated with the Vcl.Controls.TInteractiveGestureOption enumeration and allow you to control specific attributes of interactive gestures.

The supported InteractiveGestureOptions are:

  • igoPanSingleFingerHorizontal
  • igoPanSingleFingerVertical
  • igoPanInertia
  • igoPanGutter
  • igoParentPassThrough

TabletOptions

TabletOptions are supported only in the VCL framework. These options, specifically for finger or pen input, are associated with the enumeration Vcl.Controls.TTabletOption. TabletOptions are supported on the Tablet PC and Windows 7.

The supported TabletOptions are:

  • toPressAndHold
  • toPenTapFeedback
  • toPenBarrelFeedback
  • toTouchUIForceOn
  • toTouchUIForceOff
  • toTouchSwitch
  • toFlicks
  • toSmoothScrolling
  • toFlickFallbackKeys

The OnGesture Event

Every VCL or FireMonkey component that supports gesturing also supports either the Vcl.Controls.TControl.OnGesture or the FMX.Controls.TControl.OnGesture event.

The OnGesture event is triggered in two cases:

  • When the gesture engine recognizes a gesture, as follows:
    • Standard gestures (the library of 34 gestures available through the Gesture Manager)
    • Your own custom gestures (created using the Custom Gesture Designer)
    • Registered gestures (gestures stored in a package or DLL)
  • When your application uses an Interactive Gesture

OnGesture is triggered after the gesture engine attempts a match. The event is also fired when the match fails with a gesture ID, which you should handle (such as Vcl.Controls.TCustomGestureCollectionItem.GestureID or FMX.Types.TCustomGestureCollectionItem.GestureID).

You associate actions with specific gestures in the Object Inspector. For consistency, use the same gestures for the same actions across all applicable components in your application and among your applications.

For more information, see either Vcl.Controls.TControl.OnGesture or FMX.Controls.TControl.OnGesture.

Code Examples

The TGestureManager Component

Every component that uses Standard Gestures or Custom Gestures needs to be associated with a Gesture Manager, such as FMX.Gestures.TGestureManager or Vcl.Touch.GestureMgr.TGestureManager. In order to use Interactive Gestures such as zoom and rotate in a component, you do not need to associate the component with a Gesture Manager.

When selecting the component to use, keep in mind that large components (such as panel and list components) work better with gesturing, while smaller components like buttons or checkboxes are typically not well adapted to using gestures.

First, add a TGestureManager to your panel or list component (on the Tool Palette, select TGestureManager from the Gestures category).

The abstract base for all VCL gesture manager components is Vcl.Controls.TCustomTouchManager.GestureManager.

Selecting Gestures with the Gesturing Property Editor

You can access the gesturing property editor when a GestureManager is assigned to the currently selected design element. On the Object Inspector, open the Touch node and then the Gestures node. To open the gesturing property editor, click the ellipsis (ProjectOptionsEllipsis.jpg) associated with the Gestures node. While you work, you can keep the property editor window open as a reference, gesture palette, and test screen.

On the property editor window (entitled Select Gestures) you can:

  • Select the gestures you want to include in your application and assign an action to each gesture.
  • Access the Custom Gestures dialog box, which allows you to manage and create custom gestures.

Note: The Select Gestures window is not supported by FireMonkey.

Assigning Actions to Gestures

You can add actions quickly to your gestures by adding either TActionList or TActionManager to your form. Then assign actions to each gesture by using the Gesturing property editor (Select Gestures) and the Object Inspector, or just the Object Inspector, as follows:

  • In the Select Gestures dialog box, select a gesture that you want to use and then assign an action to the gesture by using the dropdown list in the Object Inspector.
  • In the Object Inspector, select a gesture that you want to use (or find a gesture that you enabled in the Select Gestures dialog box). The dropdown list in the value column lists available actions, in particular New Standard Actions. Select an action from the list to be associated with the gesture.

Note: If you do not add TActionList or TActionManager to your form, you cannot choose from New Standard Actions, and you must write your own event handler for the OnGesture event.

Creating Custom Gestures (VCL Only)

Creating custom gestures is only supported in the VCL framework. You can create your own custom gestures in the Custom Gesture Designer.

If a gesture that you draw on the Custom Gestures dialog box is too similar to any of the other gestures used in the application, a warning is displayed, and you can review the conflict. Conflicts with existing gestures can cause errors in your application. You can also adjust the sensitivity of the comparison between the custom gesture you are creating or viewing and the other gestures.

You can manage your custom gestures on the Custom Gestures dialog box. Buttons enable you to edit, delete, import, and export gestures. For more information, see Creating Custom Gestures.

Other Gesturing Components

  • TGestureListView can be associated with a TGestureManager to display a list of the gestures in the gesture manager. Gestures can also be programatically added or removed to allow customization.
  • TGesturePreview is the same preview control used in the IDE (by double-clicking a gesture in the Select Gestures dialog box) and displays an animation of how to perform the gesture.
  • TGestureRecorder is a surface to draw a gesture and record it for use later. You can use this component to build applications that allow your customers to customize the gestures associated with certain actions.

See Also