Reference for the Mosaic class Core::SimpleTouchHandler
The class Core::SimpleTouchHandler provides a special kind of a view able to react to touch screen events. Each time the user taps inside the area of the handler view, the handler send signals to slot methods stored in its various properties. For example, if there is a slot method assigned to the property OnPress, the handler will send a signal to this slot method as soon as the user has touched the handler view area. The intention of this handler is to cover the internal aspects of the cursor event handling.
The simple touch handler recognizes the tap and drag operations only. More sophisticated gesture handlers are available in other classes, e.g. Core::RotateTouchHandler is able to recognize the rotation gesture.
The touch area can assume any quad shape (4 corners polygon). Each corner can be placed separately by the Point1 .. Point4 properties. In this manner fancy, non rectangular touch areas can be determined.
The handler provides several variables useful to query e.g. the current touch position (CurrentPos), etc. These variables can be simply evaluated in the implementation of the slot method.
If this handler is intended to process multi-touch events (the property EnableMultiTouch is 'true' and the target system can feed the application with multi-touch events) you should additionally evaluate the variable Finger, which helps you to distinguish the touch events. Alternatively, the handler can be configured to react to multi-touch gestures (e.g. two finger taps) performed by two or more fingers by specifying the expected number of fingers in the property NoOfFingers. With the property LimitToFinger the handler can be limited to react to events generated by a particular finger only.
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.
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 quads. 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 point CurrentPos;
The variable 'CurrentPos' stores the current cursor position. This position is valid in the coordinate space of the Owner of this handler.
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 EnableMultiTouch = false;
The property 'EnableMultiTouch' determines how the touch handler should behave when the user interacts with it by using more then one finger.
If this property is 'false' and the handler is actually involved in a user touch interaction then the handler will ignore all additional touch events. Such events can be thus handled by other handlers lying e.g. behind this handler.
If this property is 'true', the handler will receive all affected touch events. In order to distinguish the multiple taps and touches the variable Finger can be evaluated.
Please see also the property NoOfFingers with it you can configure the handler to react only when the user puts the expected number of fingers within the handler's area. Both features NoOfFingers and 'EnableMultiTouch' has to be used exclusively.
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 int32 Finger;
The variable 'Finger' stores the number of the finger associated with the current touch event. This can be useful if the handler is intended to handle multi-touch events. The fingers are numbered with values lying in the range 0 .. 9.
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 int32 HoldPeriod;
The variable 'HoldPeriod' stores the time in milliseconds how long the user is pressing the finger on the screen. This variable is useful if a delay between the tap and the reaction to the tap is desired. At the begin of the interaction Time == 0.
var bool Inside;
The variable 'Inside' informs whether the user currently 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 or the property EnableMultiTouch is 'true') you should leave the property 'LimitToFinger' initialized with the default value -1 otherwise the handler will ignore all events.
property int32 MaxStrikeCount = 1;
The property 'MaxStrikeCount' determines the upper limit for taps in series which will be considered by the handler. The value one corresponds to a single tap. The value two to a double tap, and so far. This is like a filter.
property int32 MinStrikeCount = 1;
The property 'MinStrikeCount' determines the lower limit for taps in series which will be considered by the handler. The value one corresponds to a single tap. The value two to a double tap, and so far. This is like a filter.
property int32 NoOfFingers = 1;
The property 'NoOfFingers' determines how many fingers are required for the touch interaction to be processed. This allows the handler to process taps generated by more than one finger. 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.
Please see also the property EnableMultiTouch with it you can configure the handler to react to all touch events generated within its boundary area. Such events can then be processed individually. Both features EnableMultiTouch and 'NoOfFingers' has to be used exclusively.
var point Offset;
The variable 'Offset' stores the cursor displacement since the last drag operation.
property slot OnDrag = null;
The property 'OnDrag' can refer to a slot method, which should be invoked by the handler after the user has touched the handler and dragged the finger.
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 CurrentPos, Inside, etc. can be evaluated. If this property is 'null', no method is invoked.
If this handler is intended to process multi-touch events (the property EnableMultiTouch is 'true' and the target system can feed the application with multi-touch events) you should additionally evaluate the variable Finger, which helps you to distinguish the touch events.
property slot OnEnter = null;
The property 'OnEnter' can refer to a slot method, which should be invoked by the handler when while dragging the finger the user has entered 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 CurrentPos, Inside, etc. can be evaluated. If this property is 'null', no method is invoked.
If this handler is intended to process multi-touch events (the property EnableMultiTouch is 'true' and the target system can feed the application with multi-touch events) you should additionally evaluate the variable Finger, which helps you to distinguish the touch events.
property slot OnHold = null;
The property 'OnHold' can refer to a slot method, which should be invoked by the handler during the entire touch interaction. The method is invoked periodically in constant intervals, like a continuous fire of taps.
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 CurrentPos, Inside, etc. can be evaluated. If this property is 'null', no method is invoked.
If this handler is intended to process multi-touch events (the property EnableMultiTouch is 'true' and the target system can feed the application with multi-touch events) you should additionally evaluate the variable Finger, which helps you to distinguish the touch events.
property slot OnLeave = null;
The property 'OnLeave' can refer to a slot method, which should be invoked by the handler when while dragging the finger the user has left 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 CurrentPos, Inside, etc. can be evaluated. If this property is 'null', no method is invoked.
If this handler is intended to process multi-touch events (the property EnableMultiTouch is 'true' and the target system can feed the application with multi-touch events) you should additionally evaluate the variable Finger, which helps you to distinguish the touch events.
property slot OnPress = null;
The property 'OnPress' can refer to a slot method, which should be invoked by the handler after the user has tapped it on the screen. This occurs at the beginning of the touch interaction. Afterwards the handler may invoke other methods referred by the properties OnDrag, OnEnter, OrLeave or OnHold. At the end, when the user finishes the interaction, the method stored in the property OnRelease 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 HittingPos, HoldPeriod, etc. can be evaluated. If this property is 'null', no method is invoked.
If this handler is intended to process multi-touch events (the property EnableMultiTouch is 'true' and the target system can feed the application with multi-touch events) you should additionally evaluate the variable Finger, which helps you to distinguish the touch events.
property slot OnRelease = null;
The property 'OnRelease' 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, HoldPeriod, AutoDeflected, etc. can be evaluated. If this property is 'null', no method is invoked.
If this handler is intended to process multi-touch events (the property EnableMultiTouch is 'true' and the target system can feed the application with multi-touch events) you should additionally evaluate the variable Finger, which helps you to distinguish the touch events.
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.
var int32 StrikeCount;
The variable 'StrikeCount' stores how often the user has tapped the handler in succession. It is one, if the user has single tapped it. It is two if a double tap took place, and so far.
Such series of taps are recognized only when the taps are performed very quickly and the user doesn't move the finger very much. The appropriate time delay and the valid range for the movement are determined by the properties CursorDragLimit and CursorSequelDelay of the class Core::Root.
var uint32 Time;
The variable 'Time' stores the time in milliseconds when the user has tapped the handler area or dragged the finger for the last time. This can be useful if you e.g. need to calculate the speed with which the user is dragging the finger, etc.