Reference for the Mosaic class WidgetSet::RotaryKnob

WidgetSet::RotaryKnob
Appearance
CurrentValue
MaxValue
MinValue
OnChange
OnEnd
OnStart
OnUpdate
Outlet
StepSize
GetCenterPosition()
GetCurrentState()
GetThumbAngle()
GetThumbMaxAngle()
GetThumbMinAngle()
GetTransitionEndState()
GetTransitionProgress()
GetTransitionStartState()
Core::Group
AlphaBlended
Buffered
ClipViews
DeriveEnabledState
Embedded
Enabled
Focus
Opacity
Visible
Add()
AddBehind()
BroadcastEvent()
BroadcastEventAtPosition()
CountDialogs()
CountViews()
DismissDialog()
DispatchEvent()
DrawBackground()
DrawForeground()
ExtendClipping()
FadeGroup()
FindActiveDialogByClass()
FindCurrentDialog()
FindDialogByClass()
FindNextView()
FindPrevView()
FindSiblingView()
FindViewAtPosition()
FindViewInDirection()
FindViewWithStackingPriority()
FindViewWithinArea()
GetContentArea()
GetDialogAtIndex()
GetIndexOfDialog()
GetIndexOfView()
GetMaximalSize()
GetMinimalSize()
GetViewAtIndex()
GlobalPosition()
HasViewState()
Init()
InvalidateArea()
InvalidateLayout()
InvalidateViewState()
IsActiveDialog()
IsCurrentDialog()
IsDialog()
LocalPosition()
ObtainFocus()
PresentDialog()
Remove()
RemoveAll()
Restack()
RestackBack()
RestackBehind()
RestackTop()
SwitchToDialog()
UpdateLayout()
UpdateViewState()
Core::RectView
Bounds
Core::View
Layout
Owner
StackingPriority
AdjustDrawingArea()
ArrangeView()
ChangeViewState()
CursorHitTest()
Draw()
GetClipping()
GetExtent()
GetRoot()
HandleEvent()
MoveView()

SEE ALSO

Using and customizing the Rotary Knob widget.

This class implements a 'rotary knob' widget. When the user touches the thumb and rotates it, the widget'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 rotary knob.

Alternatively the property Outlet can refer to any other 'int32' property the rotary knob widget should remain synchronized with. When the user rotates the thumb, the affected property is automatically updated to reflect the widget's current value. On the other hand, when the referred property is modified by another one, the rotary knob is automatically notified to remain in sync with the property.

This approach follows the Model-View-Controller (MVC) programming paradigm. Here the rotary knob represents the 'View' and 'Controller' and the property referred via 'Outlet' can be seen as a part of the 'Model'.

During its lifetime the rotary knob remains always in one of the four states: 'disabled', 'default', 'focused' and 'active'. The state 'disabled' is true for every not available rotary knob widget (the property Enabled of the widget is 'false'). Such widgets will ignore all user inputs. The state 'default' determines a rotary knob widget, which is ready to be touched by the user or ready to become focused. As soon as the rotary knob widget becomes focused, it switches in the state 'focused'. In this state the user can control the widget by pressing keys on the keyboard. Finally, the state 'active' is true, if the user actually interacts with the widget (the thumb is pressed).

The exact look and feel of the rotary knob is determined by the 'Rotary Knob Configuration' object assigned to the property Appearance. The configuration object provides bitmaps, colors and other configuration parameters needed to construct and display the rotary knob widget. Usually, you will manage in your project your own configuration objects and customize the rotary knob widgets according to your design expectations.

If the rotary knob widget is actually focused, it can also be controlled by pressing the keyboard keys Core::KeyCode.Left and Core::KeyCode.Right causing the thumb to be rotated counterclockwise (key Left) or clockwise (key Right). In the configuration object you can specify another key codes, if desired. To prevent the widget from being able to be focused, specify in the configuration object the Core::KeyCode.NoKey as codes to control the rotary knob. With the property StepSize you can specify a raster in which the rotary knob changes the value when user interacts with it.

The rotary knob widget provides an additional set of methods useful to query the widget's state (GetCurrentState(), GetTransitionStartState(), GetTransitionEndState(), GetTransitionProgress()), the actual rotation angle of the thumb, its possible rotation range and the position around which the thumb is rotated (GetCenterPosition(), GetThumbAngle(), GetThumbMaxAngle(), GetThumbMinAngle()). 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 rotary knob widget. For example, you can arrange a Views::Text view to follow the thumb and to display the actual value of the widget (CurrentValue).

For more details regarding the customization of the rotary knob widget see the description of WidgetSet::RotaryKnobConfig class.

property WidgetSet::RotaryKnobConfig Appearance = null;

The property 'Appearance' refers to a 'Rotary Knob Config' object containing bitmaps, colors and further configuration attributes to customize this rotary knob widget. By assigning a configuration object to the property 'Appearance', the rotary knob widget automatically assumes the look and feel as determined in the properties of the configuration object.

If there is no configuration object associated to the rotary knob widget (the property 'Appearance' is 'null') the widget appears empty (transparent).

Please note, configuration objects can be shared among multiple rotary knob widgets. When the properties of the configuration object change, all rotary knob 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 rotary knob widget. This value corresponds to the rotation angle of the 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 (rotates) on the thumb or (if the widget is actually focused) the user controls the rotary knob by using keyboard. In such case the rotary knob automatically adjusts the CurrentValue to be a multiple of the value specified in the property StepSize.

method point GetCenterPosition();

The method GetCenterPosition() returns the position around which the thumb is rotated. The position is expressed in pixel relative to the top-left corner of the Owner component this widget belongs to. Knowing this position and the rotation angles (GetThumbAngle(), GetThumbMinAngle() and GetThumbMaxAngle()) you can simply arrange other views as decoration for the rotary knob widget. See also the property OnUpdate.

method WidgetSet::CommonState GetCurrentState();

The method GetCurrentState() returns the state of the widget (Default, Disabled, Focused or Active) according to the latest user interaction. The obtained state information is useful to update decorations associated to the widget if those should depend on the widget's current state. For more details concerning the decorations, see the property OnUpdate.

Please note, if the widget is configured to perform animations during state transitions, you can use the methods GetTransitionStartState(), GetTransitionEndState() and GetTransitionProgress() to obtain information concerning the animation.

method float GetThumbAngle();

The method GetThumbAngle() returns the actual rotation angle of the thumb expressed in degree counterclockwise relative to the positive X axis. Knowing this angle and the position around it the thumb is rotated (GetCenterPosition()) you can simply arrange other views as decoration for the rotary knob widget. See also the property OnUpdate.

method float GetThumbMaxAngle();

The method GetThumbMaxAngle() returns the maximal rotation angle of the thumb expressed in degree counterclockwise relative to the positive X axis. This corresponds to the rightmost position (clockwise) of the thumb. Knowing this angle and the position around it the thumb is rotated (GetCenterPosition()) you can simply arrange other views as decoration for the rotary knob widget. See also the property OnUpdate.

method float GetThumbMinAngle();

The method GetThumbMinAngle() returns the minimal rotation angle of the thumb expressed in degree counterclockwise relative to the positive X axis. This corresponds to the leftmost position (clockwise) of the thumb. Knowing this angle and the position around it the thumb is rotated (GetCenterPosition()) you can simply arrange other views as decoration for the rotary knob widget. See also the property OnUpdate.

method WidgetSet::CommonState GetTransitionEndState();

The method GetTransitionEndState() returns the state of the widget (Default, Disabled, Focused or Active) valid after the actual state transition will finish. This information, together with the values returned by the methods GetTransitionStartState() and GetTransitionProgress(), can be useful to calculate the state of decoration views which depend on the progress of the animation. For more details concerning the decorations, see the property OnUpdate.

If the widget is not configured to perform any state transitions with animations or there is no transition in progress, GetTransitionEndState() returns the widget's latest state equal to the value returned by the method GetCurrentState().

method float GetTransitionProgress();

The method GetTransitionProgress() returns a value in range 0.0..1.0 according to the progress of the actually performed state transition. The start and the end states for the transition can be queried by the methods GetTransitionStartState() and GetTransitionEndState(). The obtained information can be useful to calculate the state of decoration views which depend on the progress of the animation. For more details concerning the decorations, see the property OnUpdate.

If the widget is not configured to perform any state transitions with animations or there is no transition in progress, GetTransitionProgress() returns the value 0.0.

method WidgetSet::CommonState GetTransitionStartState();

The method GetTransitionStartState() returns the state of the widget (Default, Disabled, Focused or Active) valid just before the actual state transition begun. This information, together with the values returned by the methods GetTransitionEndState() and GetTransitionProgress(), can be useful to calculate the state of decoration views which depend on the progress of the animation. For more details concerning the decorations, see the property OnUpdate.

If the widget is not configured to perform any state transitions with animations or there is no transition in progress, GetTransitionStartState() returns the widget's latest state equal to the value returned by the method GetCurrentState().

property int32 MaxValue = 100;

The property 'MaxValue' determines the boundary for CurrentValue when the thumb is rotated clockwise to the right stop position. '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 rotated counterclockwise to the left stop position. '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 rotary knob widget is changed due to a direct user interaction (when the user drags (rotates) the thumb or, if the widget is actually focused, the user presses a key on the keyboard to increment or decrement the widget's value).

Thereupon the method's logic will be executed. In the associated slot method you can evaluate the widget'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 widget or, if the widget 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 rotary knob widget. In the associated slot method you can evaluate the widget'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 within the widget area or (if the widget is actually focused) presses a key on the keyboard to increment/decrement the widget'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 rotary knob widget. In the associated slot method you can evaluate the widget'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 rotates). This method is intended to update decorations associated to this rotary knob widget.

From the implementation of the slot method you can invoke the methods GetCurrentState(), GetTransitionStartState(), GetTransitionEndState(), GetTransitionProgress(), GetThumbAngle(), GetThumbMinAngle() and GetThumbMaxAngle() to get the diverse state informations and rotation angles of the thumb. With the method GetCenterPosition() you can query the position around which the thumb is rotated.

property ^int32 Outlet = null;

The property 'Outlet' can refer to any other 'int32' property the widget should remain synchronized with. When the user moves (rotates) the thumb, the affected property is automatically updated to reflect the widget's current value. On the other hand, when the referred property is modified by another one, the widget 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 rotary knob widget represents the 'View' and 'Controller' and the property referred via 'Outlet' can be seen as a part of the 'Model'.

property int32 StepSize = 1;

The property 'StepSize' determines the raster in which the rotary knob may change its value (increment or decrement the property CurrentValue) while the user drags (rotates) the thumb or (if the widget 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 rotary knob is restricted to rest at values from the serie ... -28, -21, -14, -7, 0, 7, 14, 21, and so far. Please note, that the current value of the rotary knob is also limited by the range resulting from the properties MinValue .. MaxValue.