Reference for the Mosaic class Core::WipeTouchHandler
The class Core::WipeTouchHandler provides a special kind of a view able to react to touch screen events and to recognize wipe gestures. Each time the user taps inside the area of the handler view and drags the finger in a direction the handler sends a signal to a slot method corresponding to this direction. For example, if there is a slot method assigned to the property OnRight, the handler will send a signal to this slot method as soon as the user has touched the handler and dragged his finger to the right. The intention of this handler is to cover the internal aspects of the cursor event handling.
The handler provides several variables useful to query e.g. the current handler state (Down), or the recognized direction (Direction). These variables can be simply evaluated in the implementation of the slot method.
The property Enabled can be used to activate/deactivate the touch handler. Disabled handler will not react to user taps.
With the properties RetargetCondition, RetargetOffset and RetargetDelay the handler can be configured to automatically deflect the current event processing to another handler as soon as the user has performed a simple gesture, e.g. wipe down. Using these properties several handler can cooperate during an active user interaction even if these handler overlap each other. For example, one handler can process horizontal gestures while another handler will limit to vertical gestures, etc.
The handler can be configured to react to multi-touch gestures performed by two or more fingers. In such case the expected number of fingers can be specified in the property NoOfFingers. With the property LimitToFinger the handler can be limited to react to events generated by a particular finger only.
Due to its ancestry from the Core::View class, the touch handler can be arranged within its Owner or if Embedded == 'true' within the boundary area of an Core::Outline view in the same manner as it is done with all regular views.
The touch handler itself is invisible except the Embedded Wizard Composer, where all handler appear as semitransparent rectangles. This allows you to interact with the handlers during the design time.
var bool AutoDeflected;
The variable 'AutoDeflected' is 'true', if the interaction with the handler has been terminated by deflecting the cursor event flow to another target. This can occur if method Core::Root.DeflectCursor(), Core::Root.RetargetCursor() or Core::Root.RetargetCursorWithReason() was used. These methods make possible to hand over the cursor from the current target view to another view.
var Core::Direction Direction;
The variable 'Direction' stores the successfully recognized wipe direction or Core::Direction.None if there is still no recognized gesture. The property Threshold determines the sensitivity of the gesture handler. It corresponds to the distance the user has to stroke before the handler can consider the gesture as recognized.
var bool Down;
The variable 'Down' determines whether the user is still touching the screen. If this variable == 'false' the user has finished the interaction.
property bool Embedded = false;
The property 'Embedded' controls how the handler should behave within its superior Owner. If this property == 'true', the affected handler will be embedded (limited) to the boundary of a preceding Core::Outline sibling view. This is as if the handler had been embedded within this outline. Handler areas lying outside the outline boundary are therefore not touchable.
If this property is 'false', the handler is considered as a regular view of its Owner - it doesn't belong to any outline.
property bool Enabled = true;
The property 'Enabled' determines whether the handler is able to react to user taps. Disabled handlers will ignore any user interactions and will not send any signals to the assigned slot methods.
var point HittingPos;
The variable 'HittingPos' stores the position where the user has touched the screen at the beginning of the interaction. This position is valid in the coordinate space of the Owner of this handler.
var bool Inside;
The variable 'Inside' informs whether the user does point with his finger inside the handler area or not. If 'true' the users finger lies inside the area. Dragging the finger outside the area will change the variable to 'false'.
property int32 LimitToFinger = -1;
The property 'LimitToFinger' determines a filter for which finger the handler may receive events. The value identifies the finger (or in case of a mouse device the mouse button) in range 0 .. 9. If this property is -1 no filter is applied.
Please note, if the handler is configured to process multi-touch gestures (property NoOfFingers > 1) you should leave the property 'LimitToFinger' initialized with the default value -1 otherwise the handler will ignore all events.
property int32 NoOfFingers = 1;
The property 'NoOfFingers' determines how many fingers are required for the gesture to be processed. This allows the handler to process multi-touch wipe gestures. For example, if 'NoOfFingers' is initialized with the value 3, the handler reacts when the user touches it simultanously with three (or more) fingers. Otherwise the handler ignores the events. This property can assume a value lying in range 1 .. 5.
Please note, even if the handler is configured to react to multi-touch gestures, the handler always limits to process events generated by the last finger only. The movement of other fingers involved into the actual gesture is simply ignored.
Furthermore, in case of the handler being configured to process multi-touch gestures you should leave the property LimitToFinger initialized with its default value -1 otherwise the handler will ignore all events.
property slot OnBottom = null;
The property 'OnBottom' can refer to a slot method, which should be invoked by the handler when a 'wipe down' gesture has been recognized.
It's up to you to provide the slot method and to fill it with the desired behavior. Within the slot method the current state of the handler variables like Inside, Direction, etc. can be evaluated. If this property is 'null', no method is invoked.
property slot OnBottomLeft = null;
The property 'OnBottomLeft' can refer to a slot method, which should be invoked by the handler when a 'wipe left down' gesture has been recognized.
It's up to you to provide the slot method and to fill it with the desired behavior. Within the slot method the current state of the handler variables like Inside, Direction, etc. can be evaluated. If this property is 'null', no method is invoked.
property slot OnBottomRight = null;
The property 'OnBottomRight' can refer to a slot method, which should be invoked by the handler when a 'wipe right down' gesture has been recognized.
It's up to you to provide the slot method and to fill it with the desired behavior. Within the slot method the current state of the handler variables like Inside, Direction, etc. can be evaluated. If this property is 'null', no method is invoked.
property slot OnEnd = null;
The property 'OnEnd' can refer to a slot method, which should be invoked by the handler after the user has finished the touch interaction or the cursor event flow was redirected to another target view by an explicit invocation of the method Core::Root.DeflectCursor(), Core::Root.RetargetCursor() or Core::Root.RetargetCursorWithReason().
It's up to you to provide the slot method and to fill it with the desired behavior. Within the slot method the current state of the handler variables like Inside, Down, AutoDeflected, etc. can be evaluated. If this property is 'null', no method is invoked.
property slot OnLeft = null;
The property 'OnLeft' can refer to a slot method, which should be invoked by the handler when a 'wipe left' gesture has been recognized.
It's up to you to provide the slot method and to fill it with the desired behavior. Within the slot method the current state of the handler variables like Inside, Direction, etc. can be evaluated. If this property is 'null', no method is invoked.
property slot OnRight = null;
The property 'OnRight' can refer to a slot method, which should be invoked by the handler when a 'wipe right' gesture has been recognized.
It's up to you to provide the slot method and to fill it with the desired behavior. Within the slot method the current state of the handler variables like Inside, Direction, etc. can be evaluated. If this property is 'null', no method is invoked.
property slot OnStart = null;
The property 'OnStart' can refer to a slot method, which should be invoked by the handler at the beginning of the user interaction - when the user has touched the handler area. Afterwards the handler evaluates user finger movements and tries to recognize wipe gestures. At the end, when the user finishes the interaction, the method stored in the property OnEnd is invoked.
It's up to you to provide the slot method and to fill it with the desired behavior. Within the slot method the current state of the handler variables like Down, etc. can be evaluated. If this property is 'null', no method is invoked.
property slot OnTop = null;
The property 'OnTop' can refer to a slot method, which should be invoked by the handler when a 'wipe up' gesture has been recognized.
It's up to you to provide the slot method and to fill it with the desired behavior. Within the slot method the current state of the handler variables like Inside, Direction, etc. can be evaluated. If this property is 'null', no method is invoked.
property slot OnTopLeft = null;
The property 'OnTopLeft' can refer to a slot method, which should be invoked by the handler when a 'wipe left up' gesture has been recognized.
It's up to you to provide the slot method and to fill it with the desired behavior. Within the slot method the current state of the handler variables like Inside, Direction, etc. can be evaluated. If this property is 'null', no method is invoked.
property slot OnTopRight = null;
The property 'OnTopRight' can refer to a slot method, which should be invoked by the handler when a 'wipe right up' gesture has been recognized.
It's up to you to provide the slot method and to fill it with the desired behavior. Within the slot method the current state of the handler variables like Inside, Direction, etc. can be evaluated. If this property is 'null', no method is invoked.
property Core::RetargetReason RetargetCondition = Core::RetargetReason[];
The property 'RetargetCondition' determines whether while interacting with the touch handler, this handler may automatically resign and deflect the current processing of events (the current grab cycle) to another handler.
With this property you specify gestures, which after being performed by the user should cause the handler to search for another handler willing to take over the further event processing of the actual interaction. In other words, you use this property to specify gestures the handler is NOT interested to process and thus should retarget to other handler.
Please note the properties RetargetOffset and RetargetDelay, with them you can configure the gestures more precisely.
property int32 RetargetDelay = 1000;
The property 'RetargetDelay' is used if the gesture Core::RetargetReason.LongPress is enabled in RetargetCondition. It determines the time how long the user has to press the touch handler before the LongPress gesture is recognized. The value of this property is expressed in milliseconds.
property int32 RetargetOffset = 8;
The property 'RetargetOffset' determines the minimal distance the user has to drag the finger (or the mouse pointer) vertically or horizontally in order to recognize the WipeUp, WipeDown, WipeLeft or WipeRight gestures, which are enabled in RetargetCondition property. The value of this property is expressed in pixel.
property float Threshold = 0.25;
The property 'Threshold' determines the sensitivity of the gesture handler. It defines the minimal distance the user has to stroke in proportion to the size of the handler area. For example the value 0.25 means that the user has to stroke a distance of at least 25% of the handler width and/or 25% of the handler height.