gesture-event

Arguments: window target gesture x y distance beginning ending inertia

This generic function is called one or more times for any touchscreen gesture on a window, unless register-touch-window has been called to switch that window to the touch interface (in which case touch-event will be called instead). This function will be called once for each different position of one or more fingers during the gesture. This is the somewhat higher-level interface that figures out which type of gesture is being done for you, though only five standard gestures are supported.

An application can supply methods for this generic function to handle gestures. If a method handles a gesture, it should return true. Otherwise it should return nil to pass the event up to the parent window if any, or else to perform the default behavior that's built into Windows. The default method on basic-pane does nothing and returns nil.

window is the window to which Windows is sending an event, while target is the window where the current gesture began (even if the user has dragged out of that window). Initially these will be the same window. But if the method returns nil and there is a parent window, then gesture-event will be called again where window is the parent window while target is still the window where the gesture began. Similarly, if the method for that window returns nil then gesture-event will be called yet again where window is the grandparent window (if there is one), while target is still the same target window.

This design could be used, for example, by defining a method that specializes the window parameter on a dialog subclass. If the user touches a widget on that dialog and drags across the dialog, then each position during the drag would first call gesture-event with window and target being the widget-window, in which case the default method will return nil, causing gesture-event to be called again where window is the dialog. You could then handle the gesture in your method that specializes on the dialog, even though the user intially touched a child widget.

x and y are the coordinates of the current center position of the one or more fingers that are currently on the screen, measured in pixels. These are stream coordinates of window, which means relative to the upper left corner of the canvas that is being scrolled in window if it scrolls, or else relative to the upper left of the interior of window.

gesture is a keyword that indicates which of the several standard high-level gestures is being performed. This is one of :pan, :zoom, :rotate, :two-finger-tap, or :press-and-tap. Here are their meanings:

• :pan - one or two fingers are being dragged, typically to scroll the window
• :zoom - two fingers are either moving closer to each other or farther apart (a pinch or a spread)
• :rotate - two fingers are moving in a circular manner around a central point
• :two-finger-tap - two fingers touched the screen and were removed without dragging
• :press-and-tap - one finger touched the screen and then another touched the screen while the first was still down

distance is the distance between the two fingers, measured in pixels. This will be zero if only one finger is touching the screen. For a :rotate gesture, this is instead an angle measured in radians, referring to the angle of a line that goes through both finger positions.

beginning is true if this is the first call to gesture-event for this gesture, and nil otherwise. The first call is made for the first finger that touches the screen, though only after a partial drag indicates which type of gesture is being performed.

ending is true if this is the last call to gesture-event for this gesture, and nil otherwise. The last call is made when the last finger stops touching the screen (or the last inertia event comes in after all fingers have left the screen).

inertia is true if this call results from inertia after all fingers have left the screen, and nil otherwise. This applies only to the :pan gesture, and will always be nil for other gestures. If inertia is enabled for this window (see configure-gestures), and all fingers leave the screen during a drag, then calls will continue to be made to gesture-event for a brief period, as if the user had continued to drag until gradually coming to a halt. An application typically can simply ignore the fact that no fingers are still on the screen and scroll the window according to the changing x and y values as usual, and then the scrolling will come to a gradual halt after the user makes a fling gesture.

See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.htm, where there is a complete example.

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.