Reference for the Mosaic class Core::RotateTouchHandler
The class Core::RotateTouchHandler provides a special kind of a view able to react to touch screen events and to recognize rotation gestures. Each time the user taps inside the area of the handler and drags the finger around its center (resulting from the property CenterOffset), the handler sends signals to the slot method stored in the property OnRotate. 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 current rotation angle (Angle), etc. 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 with a cross at the resulting center position. This allows you to interact with the handlers during the design time.
var int32 Angle;
The variable 'Angle' stores the absolute angle corresponding to the position where the user is currently touching the handler area. The angle is calculated relative to the center of the handler area and is expressed in degrees 0 .. 360°.
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 or Core::Root.RetargetCursorWithReason() was used. These methods make possible to hand over the cursor from the current target view to another view.
property point CenterOffset = <0,0>;
The property 'CenterOffset' determines the displacement in pixel for the center position around it the user will perform the gesture. Per default, the gestures are processed around the center of the handler's area. By specifying a value for the property 'CenterOffset' this position moves accordingly - always relative to center of the handler.
var int32 Delta;
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 rotate 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 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 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 OnRotate = null;
The property 'OnRotate' can refer to a slot method, which should be invoked by the handler after the user has dragged the finger around the center of the handler area.
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, Angle, Delta, Relative, 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 rotation 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.
var int32 Radius;
The variable 'Radius' stores the distance in pixel between the actual touch position and the center of the handler area.
var int32 Relative;
The variable 'Relative' stores the relative modification of the angle since the user interaction began. Each time the user rotates clockwise, the value of this variable is decremented by the corresponding number of degrees. If the user performs an counter-clockwise rotation, the variable is incremented accordingly. At the beginning of the interaction, the value is zero.
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.
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.