Unit WidgetSet: WidgetSet::Gauge

Reference for the Mosaic class WidgetSet::Gauge

WidgetSet::Gauge
Appearance CurrentValue MaxValue MinValue OnUpdate Outlet
GetCenterPosition() GetNeedleAngle() GetNeedleMaxAngle() GetNeedleMinAngle()

Core::Group

AlphaBlended
Buffered
Embedded
Enabled
Focus
Opacity
Visible

Add()
AddBehind()
BroadcastEvent()
BroadcastEventAtPosition()
CountDialogs()
CountViews()
DismissDialog()
DispatchEvent()
FadeGroup()
FindActiveDialogByClass()
FindCurrentDialog()
FindDialogByClass()
FindNextView()
FindPrevView()
FindSiblingView()
FindViewAtPosition()
FindViewInDirection()
FindViewWithinArea()
GetContentArea()
GetDialogAtIndex()
GetIndexOfDialog()
GetIndexOfView()
GetViewAtIndex()
GlobalPosition()
HasViewState()
Init()
InvalidateArea()
InvalidateViewState()
IsActiveDialog()
IsCurrentDialog()
IsDialog()
LocalPosition()
ObtainFocus()
PresentDialog()
Remove()
RemoveAll()
Restack()
RestackBack()
RestackBehind()
RestackTop()
SwitchToDialog()
UpdateLayout()
UpdateViewState()

Core::RectView
Bounds

Core::View
Layout Owner StackingPriority
ArrangeView() ChangeViewState() CursorHitTest() Draw() GetExtent() GetRoot() HandleEvent() MoveView()

SEE ALSO

Using and customizing the Gauge widget.

This class implements an 'analog instrument' (circular gauge), intended to display a value as a needle that rotates above a scale. The rotation of the needle corresponds to the value specified in the property CurrentValue, which lies in range determined by the properties MinValue and MaxValue.

Alternatively the property Outlet can refer to any other 'int32' property the widget should remain synchronized with. When the referred property is modified by another one, the widget is automatically notified to remain in sync with the property.

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

The exact look and feel of the gauge is determined by the 'Gauge Configuration' object assigned to the property Appearance. The configuration object provides bitmaps, colors and other configuration parameters needed to construct and display the gauge widget. Usually, you will manage in your project your own configuration objects and customize the gauge widgets according to your design expectations. Depending on the information provided in the associated configuration object, the gauge widget will be composed of following views:

'Scale' is an image view (Views::Image) displayed centered in the background within the widget area. In the configuration object you can specify the desired bitmap, its opacity, frame number (if the bitmap is multi-frame) and tint color (if the bitmap contains Alpha8 information only). The gauge widget can automatically play animated bitmaps.
'TrackLeft' is a vector graphic view (Views::FillPath) displaying a circle segment between the needle's leftmost position (clockwise) and its actual position. From this results the effect of a track behind the needle. In the configuration object you can specify the track thickness, color and the appearance of its caps.
'TrackRight' is a vector graphic view (Views::FillPath) displaying a circle segment between the actual position of the needle and its rightmost position (clockwise). From this results the effect of a track behind the needle. In the configuration object you can specify the track thickness, color and the appearance of its caps.
'Needle' is a warp image view (Views::WarpImage) displayed and rotated around predetermined pivot position. In the configuration object you can specify the desired bitmap, its opacity, frame number (if the bitmap is multi-frame) and tint color (if the bitmap contains Alpha8 information only). The gauge widget can automatically play animated bitmaps. The desired rotation range (the angles corresponding to the values MinValue and MaxValue) and the pivot position are also specify in the configuration object.
'Cover' is an image view (Views::Image) displayed centered within the widget area and covering so eventually the scale and needle images. In the configuration object you can specify the desired bitmap, its opacity, frame number (if the bitmap is multi-frame) and tint color (if the bitmap contains Alpha8 information only). The gauge widget can automatically play animated bitmaps.

The gauge widget implements a 'swing' animation effect to rotate the needle smoothly. You can configure the duration and the timing of this effect in the configuration object. Gauge widgets are not intended to be controlled by the user. The widget ignores all touch and keyboard events and it can't be focused.

The gauge widget provides an additional set of methods useful to query the actual rotation angle of the needle, its possible rotation range and the position around which the needle is rotated (GetCenterPosition(), GetNeedleAngle(), GetNeedleMaxAngle(), GetNeedleMinAngle()). 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 gauge widget. For example, you can arrange a Views::Text view to follow the needle and to display the actual value of the widget (CurrentValue).

For more details regarding the customization of the gauge widget see the description of WidgetSet::GaugeConfig class.

property WidgetSet::GaugeConfig Appearance = null;

The property 'Appearance' refers to a 'Gauge Config' object containing bitmaps, colors and further configuration attributes to customize this gauge widget. By assigning a configuration object to the property 'Appearance', the gauge 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 gauge widget (the property 'Appearance' is 'null') the widget appears empty (transparent).

Please note, configuration objects can be shared among multiple gauge widgets. When the properties of the configuration object change, all gauge 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 gauge widget. This value corresponds to the rotation angle of the needle and it is limited to be always within the range specified in the properties MinValue and MaxValue.

method point GetCenterPosition();

The method GetCenterPosition() returns the position around which the needle 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 (GetNeedleAngle(), GetNeedleMinAngle() and GetNeedleMaxAngle()) you can simply arrange other views as decoration for the gauge widget. See also the property OnUpdate.

method float GetNeedleAngle();

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

method float GetNeedleMaxAngle();

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

method float GetNeedleMinAngle();

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

property int32 MaxValue = 100;

The property 'MaxValue' determines the boundary for CurrentValue when the needle 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 needle is rotated counterclockwise to the left stop position. 'MinValue' together with MaxValue limit the range for 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 needle rotates). This method is intended to update decorations associated to this gauge widget.

From the implementation of the slot method you can invoke the methods GetNeedleAngle(), GetNeedleMinAngle() and GetNeedleMaxAngle() to get the diverse rotation angles of the needle. With the method GetCenterPosition() you can query the position around which the needle is rotated.

property ^int32 Outlet = null;

The property 'Outlet' can refer to any other 'int32' property the gauge widget should remain synchronized with. When the referred property is modified, the gauge 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 Mode-View-Controller (MVC) programming paradigm. Here the gauge represents the 'View' and the property referred via 'Outlet' can be seen as a part of the 'Model'.