Reference for the Mosaic class Core::SlideTouchHandler
The class Core::SlideTouchHandler provides a special kind of a view able to react to touch screen events and to process slide gestures. Each time the user taps inside the area of the handler and drags the finger, the handler modifies the stored Offset value accordingly to the direction and distance the user has stroke. Each modification of this Offset value causes the handler to send a signal to a slot method stored in the property OnSlide. The intention of this handler is to cover the internal aspects of the cursor event handling.
This slide handler is very useful to add the scrolling functionality to GUI components containing large lists of items, text blocks, or other extensive contents. Even the classes Core::Outline, Core::HorizontalList, Core::VerticalList, Views::Text and Views::Image provide an interface to connect themselves with a such slide handler. In this manner the user can scroll their content by simply touching inside the handler area and dragging the finger.
The slide handler implements fancy animation effects to simulate movements similar to them in a real physical system with its inertia and the friction. For example, after the user has finished the interaction the sliding can continue running and its speed will decelerate accordingly to the Friction factor.
The handler provides several variables useful to query e.g. the current handler state (Sliding), or the current slide position (Offset), 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. This allows you to interact with the handlers during the design time.
var point Delta;
The variable 'Delta' stores the difference between the current value of the property Offset and its previous value. The variable reflects the last modification of Offset.
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.
property float Friction = 0.5;
The property 'Friction' determines the deceleration for the animated sliding after the user has finished the interaction. The value of this property can vary in the range 0.0 .. 1.0.
If Friction == 0.0, the sliding will continue without any deceleration until the lower MinOffset or the upper MaxOffset limit has been reached by the Offset property. If Friction == 1.0, no animated sliding will be performed. The sliding stops immediately after the user has finished the interaction.
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.
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 point MaxOffset = <0,0>;
The property 'MaxOffset' stores the upper limit for the Offset value. This property should be greater or equal to MinOffset.
property point MinOffset = <0,0>;
The property 'MinOffset' stores the lower limit for the Offset value. This property should be less or equal to MaxOffset.
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 slide 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 point Offset = <0,0>;
The property 'Offset' stores the current slide position. This value changes when the user strokes or taps the handler area. The value will also change during the deceleration animation.
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 and the deceleration animation is done.
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 Sliding, Offset, etc. can be evaluated. If this property is 'null', no method is invoked.
property slot OnSlide = null;
The property 'OnSlide' can refer to a slot method, which should be invoked by the handler when the value of the variable Offset changes. This can occur in response to direct user interactions or during the deceleration animation.
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 Offset, 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 adapts accordingly the value of the property Offset. At the end, when the user finishes the interaction and the deceleration animation is done, 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 Sliding, etc. can be evaluated. If this property is 'null', no method is invoked.
property int32 ResetDelay = 200;
The property 'ResetDelay' determines the time period how long the user has to touch the handler area in order to reset its current speed vector. This property is expressed in milliseconds.
In the slide touch handler the speed vector is calculated from consecutive slide (flick) gestures. Touching the slide touch handler for a period longer or equal to ResetDelay sets the vector to 0.
property int32 ResetSpace = -1;
The property 'ResetSpace' determines the radius of an area around the position where the user has started the touch interaction to reset the current speed vector if without leaving this area the user has released the finger again. This area is expressed as radius in pixel. If this property is negative (< 0) no reset operation is applied.
In the slide touch handler the speed vector is calculated from consecutive slide (flick) gestures. If the distance between the touch and the release position is less or equal to ResetSpace the speed vector is set to 0.
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 int32 RubberBandEffectDuration = 500;
The property 'RubberBandEffectDuration' determines how much time it takes to automatically scroll the content after the user has released it beyond the end of the possible scroll range. The value of this property is expressed in milliseconds.
Whether this animation effect is really performed is determined by the property RubberBandScrolling. With the property RubberBandEffectElasticity the timing of the animation can be controlled.
property float RubberBandEffectElasticity = 5.0;
The property 'RubberBandEffectElasticity' determines the timing of the scroll animation performed after the user has dragged and released the content beyond the end of the possible scroll range. The value of this property is valid in range 1.0 .. 100.0. The larger the value the more elastic the animation effect. Initializing this property with 1.0 results in the animation being performed with linear timing.
Whether this animation effect is really performed is determined by the property RubberBandScrolling. Additionally the property RubberBandEffectDuration controls the duration of this automatic scroll animation.
property bool RubberBandScrolling = true;
The property 'RubberBandScrolling' determines how the handler should behave when the user tries to scroll the content beyond the end of the possible range.
If this property is 'true' the user can drag the content beyond the end of the range with a kind of rubber band bounce effect. If this property is 'false' the rubber band effect is suppressed and scrolling stops.
You can control the duration and timing of the bounce effect by specifying the desired values in the properties RubberBandEffectDuration and RubberBandEffectElasticity.
property bool SlideHorz = true;
The property 'SlideHorz' determines whether the handler should be able to scroll horizontally. If this property is 'false', the handler ignores any horizontal drag user interactions.
property bool SlideVert = true;
The property 'SlideVert' determines whether the handler should be able to scroll vertically. If this property is 'false', the handler ignores any vertical drag user interactions.
var bool Sliding;
The variable 'Sliding' informs about the current state of the handler. If Sliding is 'false' the handler is in the standstill. It is 'true' during the user interaction and during the following deceleration animation.
property point SnapFirst = <0,0>;
The property 'SnapFirst' determines the first position where the sliding should automatically snap. The position is aligned relative to the top-left corner of the scrolled content. With the properties SnapNext and SnapLast further snap positions can be configured. If this property is 0, the snap position is ignored.
property point SnapLast = <0,0>;
The property 'SnapLast' determines the last position where the sliding should automatically snap. The position is aligned relative to the bottom-right corner of the scrolled content. With the properties SnapFirst and SnapNext further snap positions can be configured. If this property is 0, the snap position is ignored.
property point SnapNext = <0,0>;
The property 'SnapNext' determines an optional distance between consecutive snap positions. The snap positions are aligned relative to the top-left corner of the scrolled content. With the properties SnapFirst and SnapLast the first and the last snap position in the scrolled content can be configured explicitly. If this property is 0, the snap position is ignored.
property float SpeedLimit = 0.0;
The property 'SpeedLimit' limits the slide speed to the given value. This value is expressed in pixel per second. If this value is 0.0 no speed limitation is applied.