Reference for the Mosaic class WidgetSet::VerticalSlider
This class implements a 'vertical slider' widget. When the user touches the slider's thumb and drags it vertically, the slider's current value represented by the int32 property CurrentValue is changed and signal is sent to the slot method stored in the property OnChange. The valid range for CurrentValue is determined by the properties MinValue and MaxValue. By connecting further slot methods to the properties OnStart and OnEnd you can react to other events triggered while the user starts and ends the interaction with the slider.
Alternatively the property Outlet can refer to any other 'int32' property the slider widget should remain synchronized with. When the user drags the slider's thumb, the affected property is automatically updated to reflect the slider's current value. On the other hand, when the referred property is modified by another one, the slider is automatically notified to remain in sync with the property.
This approach follows the Model-View-Controller (MVC) programming paradigm. Here the slider represents the 'View' and 'Controller' and the property referred via 'Outlet' can be seen as a part of the 'Model'.
During its lifetime the slider remains always in one of the four states: 'disabled', 'default', 'focused' and 'active'. The state 'disabled' is true for every not available slider (the property Enabled of the slider is 'false'). Such sliders will ignore all user inputs. The state 'default' determines a slider, which is ready to be touched by the user or ready to become focused. As soon as the slider becomes focused, it switches in the state 'focused'. In this state the user can control the slider by pressing keys on the keyboard. Finally, the state 'active' is true, if the user actually interacts with the slider (the slider's thumb is pressed).
The exact look and feel of the slider is determined by the 'Vertical Slider Configuration' object assigned to the property Appearance. The configuration object provides bitmaps, colors and other configuration parameters needed to construct and display the slider. Usually, you will manage in your project your own configuration objects and customize the sliders according to your design expectations. Depending on the information provided in the associated configuration object, the slider will be composed of following views:
In particular application cases you can instruct the slider to automatically resign and retarget the actual touch interaction to another touch handler (e.g. another widget) after the user has performed a horizontal wipe gesture (ResignAfterHorizontalWipe). Using this property several widgets can cooperate during an active user interaction even if these handler overlap each other.
If the slider is actually focused, it can also be controlled by pressing the keyboard keys Core::KeyCode.Down and Core::KeyCode.Up causing the slider's thumb to be moved down or up. In the configuration object you can specify another key codes, if desired. To prevent the slider from being able to be focused, specify in the configuration object the Core::KeyCode.NoKey as codes to control the slider. With the property StepSize you can specify a raster in which the slider changes the value when user interacts with it.
If there is no thumb bitmap provided for the slider, the entire slider area is touchable permitting the user so to interact with and control the slider.
The slider widget provides an additional set of methods useful to query the actual position of the thumb and its possible movement range (GetThumbMaxPosition(), GetThumbMinPosition(), GetThumbPosition()). These methods can be invoked from a slot method assigned to the property OnUpdate. In this manner you can automatically arrange and updated additional decoration according to the actual state of the slider widget. For example, you can arrange a Views::Text view to follow the thumb and to display the actual value of the slider (CurrentValue).
For more details regarding the customization of the slider see the description of WidgetSet::VerticalSliderConfig class.
property WidgetSet::VerticalSliderConfig Appearance = null;
The property 'Appearance' refers to a 'Vertical Slider Config' object containing bitmaps, colors and further configuration attributes to customize this slider widget. By assigning a configuration object to the property 'Appearance', the slider automatically assumes the look and feel as determined in the properties of the configuration object.
If there is no configuration object associated to the slider (the property 'Appearance' is 'null') the slider appears empty (transparent).
Please note, configuration objects can be shared among multiple slider widgets. When the properties of the configuration object change, all slider widgets (connected actually to it) are notified and updated to assume the new appearance.
property int32 CurrentValue = 50;
The property 'CurrentValue' stores the momentary value of the slider. This value corresponds to the vertical position of the slider's thumb and it is limited to be always within the range specified in the properties MinValue and MaxValue.
'CurrentValue' is updated automatically while the user drags on the slider's thumb or (if the slider is actually focused) the user controls the slider by using keyboard. In such case the slider automatically adjusts the CurrentValue to be a multiple of the value specified in the property StepSize.
method point GetThumbMaxPosition();
The method GetThumbMaxPosition() returns the topmost possible position of the thumb center (upper end of the thumb movement range). The position is expressed in pixel relative to the top-left corner of the Owner component this slider widget belongs to. Knowing this position you can simply arrange other views as decoration for the slider widget. See also the property OnUpdate.
method point GetThumbMinPosition();
The method GetThumbMinPosition() returns the bottommost possible position of the thumb center (lower end of the thumb movement range). The position is expressed in pixel relative to the top-left corner of the Owner component this slider widget belongs to. Knowing this position you can simply arrange other views as decoration for the slider widget. See also the property OnUpdate.
method point GetThumbPosition();
The method GetThumbPosition() returns the actual position of the thumb center expressed in pixel relative to the top-left corner of the Owner component this slider widget belongs to. Knowing this position you can simply arrange other views as decoration for the slider widget. See also the property OnUpdate.
property int32 MaxValue = 100;
The property 'MaxValue' determines the boundary for CurrentValue when the thumb is moved to the top edge of the slider widget. 'MaxValue' together with MinValue limit the range for CurrentValue.
property int32 MinValue = 0;
The property 'MinValue' determines the boundary for CurrentValue when the thumb is moved to the bottom edge of the slider widget. 'MinValue' together with MaxValue limit the range for CurrentValue.
property slot OnChange = null;
The property 'OnChange' can refer to a slot method, which will receive a signal each time the value of the slider is changed due to a direct user interaction (when the user drags on the slider's thumb or, if the slider is actually focused, the user presses a key on the keyboard to increment or decrement the slider's value).
Thereupon the method's logic will be executed. In the associated slot method you can evaluate the slider's current value CurrentValue.
property slot OnEnd = null;
The property 'OnEnd' can refer to a slot method, which will receive a signal as soon as the user lifts the finger from the slider or, if the slider was activated by preceding keyboard event, the user releases the key again. Thereupon the method's logic will be executed.
In other words, this event is triggered at the end of the interaction between user and the slider. In the associated slot method you can evaluate the slider's current value CurrentValue.
property slot OnStart = null;
The property 'OnStart' can refer to a slot method, which will receive a signal as soon as the user touches the slider's thumb or (if the slider is actually focused) presses a key on the keyboard to increment/decrement the slider's value. Thereupon the method's logic will be executed.
In other words, this event is triggered at the beginning of the interaction between user and the slider. In the associated slot method you can evaluate the slider's current value CurrentValue.
property slot OnUpdate = null;
The property 'OnUpdate' can refer to a slot method, which should be invoked by the widget when its CurrentValue or Bounds changes (more generally, when the thumb moves). This method is intended to update decorations associated to this slider widget.
From the implementation of the slot method you can invoke the methods GetThumbPosition(), GetThumbMinPosition() and GetThumbMaxPosition() to get the diverse positions of the thumb.
property ^int32 Outlet = null;
The property 'Outlet' can refer to any other 'int32' property the widget should remain synchronized with. When the user moves the slider's thumb, the affected property is automatically updated to reflect the slider's current value. On the other hand, when the referred property is modified by another one, the slider is automatically notified to remain in sync with the property (the property CurrentValue is updated to the value of the property referred in Outlet).
This approach follows the Model-View-Controller (MVC) programming paradigm. Here the slider represents the 'View' and 'Controller' and the property referred via 'Outlet' can be seen as a part of the 'Model'.
property bool ResignAfterHorizontalWipe = false;
The property 'ResignAfterHorizontalWipe' determines whether while interacting with the slider, the slider may automatically resign and deflect the current processing of touch events (the current grab cycle) to another touch handler.
If this property is 'true' and the user performs a horizontal wipe gesture within the slider area, the slider searches for another touch handler (e.g. another widget) willing to take over the further event processing of the actual interaction. In other words, you use this property to specify that the slider is NOT interested to process the horizontal wipe gestures and thus other handler should take over.
property int32 StepSize = 1;
The property 'StepSize' determines the raster in which the slider may change its value (increment or decrement the property CurrentValue) while the user drags on the slider's thumb or (if the slider is actually focused) the user controls it by pressing keys on the keyboard. The raster is calculated relative to the value 0 in the positive and in the negative direction.
For example, if the property 'StepSize' is 7, the slider is restricted to rest at values from the series ... -28, -21, -14, -7, 0, 7, 14, 21, and so far. Please note, that the current value of the slider is also limited by the range resulting from the properties MinValue .. MaxValue.