Reference for the Mosaic class WidgetSet::GaugeConfig
This class implements the functionality permitting you to simply customize the look and feel of a 'gauge' widget (WidgetSet::Gauge). In the practice, you will create an instance of this class, configure its properties with bitmaps, colors and other relevant attributes according to your design expectations and assign such prepared configuration object to the property 'Appearance' of every affected gauge widget. Thereupon the widgets will use the configuration information provided in the object.
Since with the configuration object you determine the appearance of the gauge you should know from which views the gauge is composed of:
The gauge widget can rotate the needle with a smooth animation. This can be configured in the properties SwingDuration and SwingElastic.
All above mentioned views are arranged one above the other whereby the resulting stacking order can be configured by using the properties ScaleStackingPriority, TrackLeftStackingPriority, TrackRightStackingPriority, NeedleStackingPriority and CoverStackingPriority. The view with higher priority will appear in front of other views with lower priority.
To further enhance the widgets, a slot method can be assigned to the property OnUpdate. Within the slot method new decoration views can be added to the widgets and updated according to the current state of the widget.
With the properties WidgetMinSize and WidgetMaxSize you can configure size constraints for the widget itself. You can, for example, limit the gauge to not shrink below a specified width or height.
property point CenterOffset = <0,0>;
The property 'CenterOffset' determines a displacement common for the needle bitmap (NeedleBitmap) and all views belonging to the left and right tracks. The resulting position serves as the center around it the needle bitmap is rotated and the track arcs are calculated. Per default, the center position corresponds to the center of the widget. By specifying a value for the property 'CenterOffset' this position moves accordingly. The value is expressed in pixel.
property Resources::Bitmap CoverBitmap = null;
The property 'CoverBitmap' determines the bitmap to display centered in the foreground of the gauge widget.
If the specified bitmap contains more than one frame (multi-frame bitmap), the desired frame number can be selected in the property CoverFrame. If the selected bitmap is intended to be animated, ensure that the property CoverFrame is -1.
If the specified bitmap contains opacity information only (Alpha8 bitmap), you can tint the bitmap by specifying the desired color in the property CoverTint. With the property CoverTint you can also modulate the opacity of a regular bitmap.
property int32 CoverFrame = -1;
The property 'CoverFrame' determines the frame number within the bitmap CoverBitmap. This property is applicable for multi-frame bitmaps only (see also Resources::Bitmap). If the desired frame is not available in the bitmap, no bitmap is shown.
If the property is initialized with the value -1 and the CoverBitmap bitmap is animated, the animation is automatically started. If the bitmap is not animated and the property is -1, the frame with number 0 is displayed.
property int32 CoverStackingPriority = 5;
The property 'CoverStackingPriority' determines the Z-order position of the view destined to display the cover bitmap. Per default the cover view is arranged in front of all other views within the gauge. By configuring this property the arrangement of the views within the widget can be changed whereby views with larger priority will be arranged in front of views with lower priority. For example, to bring the cover view in background of the gauge, configure the property with a smaller value.
property color CoverTint = #FFFFFFFF;
The property 'CoverTint' determines the color value to tint or modulate the bitmap specified in the property CoverBitmap. The effect of this color value depends on the type of the bitmap:
property Resources::Bitmap NeedleBitmap = null;
The property 'NeedleBitmap' determines the bitmap to display rotated around the center of the gauge widget. It serves as the pointer in the analog display.
If the specified bitmap contains more than one frame (multi-frame bitmap), the desired frame number can be selected in the property NeedleFrame. If the selected bitmap is intended to be animated, ensure that the property NeedleFrame is -1.
If the specified bitmap contains opacity information only (Alpha8 bitmap), you can tint the bitmap by specifying the desired color in the property NeedleTint. With the property NeedleTint you can also modulate the opacity of a regular bitmap.
With the properties CenterOffset, NeedleRadius and NeedlePivot you adjust the position around it the needle bitmap should rotate. The possible rotation range is determined by the properties NeedleMinAngle and NeedleMaxAngle. To simplify the configuration of NeedleMinAngle and NeedleMaxAngle we recommend to design the needle bitmap for 0 degrees rotation relative to the positive X-axis.
property int32 NeedleFrame = -1;
The property 'NeedleFrame' determines the frame number within the bitmap NeedleBitmap. This property is applicable for multi-frame bitmaps only (see also Resources::Bitmap). If the desired frame is not available in the bitmap, no bitmap is shown.
If the property is initialized with the value -1 and the NeedleBitmap bitmap is animated, the animation is automatically started. If the bitmap is not animated and the property is -1, the frame with number 0 is displayed.
property float NeedleMaxAngle = 45;
The property 'NeedleMaxAngle' determines the rotation angle for the needle bitmap (NeedleBitmap) corresponding to 'MaxValue' specified in the gauge widget. The angle is expressed in degree, counted counterclockwise with 0 degree at the positive X-axis.
At the runtime, when the value stored in the gauge widget changes, the needle will move (rotate) accordingly in the range between the angle position NeedleMinAngle and 'NeedleMaxAngle'. The rotation occurs around the center position of the gauge widget unless a displacement has been specified in the property CenterOffset. The rotation radius is determined by the property NeedleRadius.
Please note, the value specified in 'NeedleMaxAngle' has to be less than the value specified in NeedleMinAngle.
property float NeedleMinAngle = 135;
The property 'NeedleMinAngle' determines the rotation angle for the needle bitmap (NeedleBitmap) corresponding to 'MinValue' specified in the gauge widget. The angle is expressed in degree, counted counterclockwise with 0 degree at the positive X-axis.
At the runtime, when the value stored in the gauge widget changes, the needle will move (rotate) accordingly in the range between the angle position 'NeedleMinAngle' and NeedleMaxAngle. The rotation occurs around the center position of the gauge widget unless a displacement has been specified in the property CenterOffset. The rotation radius is determined by the property NeedleRadius.
Please note, the value specified in 'NeedleMinAngle' has to be greater than the value specified in NeedleMaxAngle.
property point NeedlePivot = <0,0>;
The property 'NeedlePivot' specifies the pivot position (the anchor) in the needle bitmap (NeedleBitmap) around it the bitmap should be rotated. The position is expressed in pixel relative to the top-left corner of the needle bitmap.
Please note, we recommend to design the needle bitmap for 0 degrees rotation relative to the positive X-axis. See also NeedleRadius, NeedleRotate and CenterOffset.
property float NeedleRadius = 0.0;
The property 'NeedleRadius' specifies the radius of the circle segment along which the needle should be moved. The value is expressed in pixel. The center of the circle segment corresponds to the position resulting from the property CenterOffset. The movement range is determined by the properties NeedleMinAngle and NeedleMaxAngle. Please see also NeedlePivot and NeedleRotate.
property bool NeedleRotate = true;
The property 'NeedleRotate' determines whether the needle bitmap (NeedleBitmap) should appear rotated or not. If this property is 'true', the bitmap is rotated around its NeedlePivot and moved along the circle segment with radius NeedleRadius. If this property is 'false', the bitmap is only moved along the circle segment without being rotated itself.
property int32 NeedleStackingPriority = 4;
The property 'NeedleStackingPriority' determines the Z-order position of the view destined to display the needle bitmap. Per default the needle view is arranged in front of the views belonging to the left and right tracks. By configuring this property the arrangement of the views within the widget can be changed whereby views with larger priority will be arranged in front of views with lower priority. For example, to place the needle in background of the gauge, configure the property with a smaller value.
property color NeedleTint = #FFFFFFFF;
The property 'NeedleTint' determines the color value to tint or modulate the bitmap specified in the property NeedleBitmap. The effect of this color value depends on the type of the bitmap:
property slot OnUpdate = null;
The property 'OnUpdate' can refer to a slot method, which should be invoked by widgets connected to this configuration object when the widget's state changes. This method is intended to add and update custom widget decorations.
The usage of this property is equal to the homonymous property explained in WidgetSet::Gauge. See its description for more details.
Please note, when the slot method is invoked, the method's parameter 'sender' refers the widget instance causing the invocation. In this manner, by using 'sender' the implementation of the slot method can access the widget to add and manipulate decoration views.
property Resources::Bitmap ScaleBitmap = null;
The property 'ScaleBitmap' determines the bitmap to display centered in the background of the gauge widget.
If the specified bitmap contains more than one frame (multi-frame bitmap), the desired frame number can be selected in the property ScaleFrame. If the selected bitmap is intended to be animated, ensure that the property ScaleFrame is -1.
If the specified bitmap contains opacity information only (Alpha8 bitmap), you can tint the bitmap by specifying the desired color in the property ScaleTint. With the property ScaleTint you can also modulate the opacity of a regular bitmap.
property int32 ScaleFrame = -1;
The property 'ScaleFrame' determines the frame number within the bitmap ScaleBitmap. This property is applicable for multi-frame bitmaps only (see also Resources::Bitmap). If the desired frame is not available in the bitmap, no bitmap is shown.
If the property is initialized with the value -1 and the ScaleBitmap bitmap is animated, the animation is automatically started. If the bitmap is not animated and the property is -1, the frame with number 0 is displayed.
property int32 ScaleStackingPriority = 1;
The property 'ScaleStackingPriority' determines the Z-order position of the view destined to display the scale bitmap. Per default the scale view is arranged in the background of the gauge behind all other views. By configuring this property the arrangement of the views within the widget can be changed whereby views with larger priority will be arranged in front of views with lower priority. For example, to bring the scale view in front of the gauge, configure the property with a larger value.
property color ScaleTint = #FFFFFFFF;
The property 'ScaleTint' determines the color value to tint or modulate the bitmap specified in the property ScaleBitmap. The effect of this color value depends on the type of the bitmap:
property int32 SwingDuration = 500;
The property 'SwingDuration' determines the time in milliseconds the gauge widget should take when repositioning the needle between the both end positions NeedleMinAngle and NeedleMaxAngle. At the runtime, when the needle is rotated, the rotation is performed with a smooth animation.
Initializing this property with the value 0 (zero) deactivates the animation effect so that the rotation angle of the needle is adapted immediately when the corresponding value in the gauge widget changes.
If enabled, the animation is performed with the FastIn_EasyOut or BackOut timing (see Effects::Timing) depending on the configuration of the property SwingElastic.
property bool SwingElastic = true;
The property 'SwingElastic' controls the timing of the animation effect used to smoothly rotate the needle when the value in the gauge widget changes. This animation is enabled when the property SwingDuration is greater than 0 (zero).
Initializing the property 'SwingElastic' with the value 'false' causes the animation to be performed with the FastIn_EaseOut timing. If the property is 'true', the animation is performed with the BackOut timing resulting in the animation to be more elastic. See also Effects::Timing.
property color TrackLeftBorderColor = #FFFFFFFF;
The property 'TrackLeftBorderColor' determines the color of the border surrounding the circle segment displayed usually on the left (clockwise) of the actual needle position. To determine the thickness of the border use the property TrackLeftBorderWidth. See also TrackLeftRadius, TrackLeftThickness, TrackLeftRoundedEnd, TrackLeftRoundedStart, TrackLeftMarginEnd and TrackLeftMarginStart.
property float TrackLeftBorderWidth = 0.0;
The property 'TrackLeftBorderWidth' determines the thickness of the border surrounding the circle segment displayed usually on the left (clockwise) of the actual needle position. The value is expressed in pixel. To determine the color of the border use the property TrackLeftBorderColor. See also TrackLeftRadius, TrackLeftThickness, TrackLeftRoundedEnd, TrackLeftRoundedStart, TrackLeftMarginEnd and TrackLeftMarginStart.
property color TrackLeftColor = #FFFFFFFF;
The property 'TrackLeftColor' determines the color of the circle segment displayed usually on the left (clockwise) of the actual needle position. See also TrackLeftRadius, TrackLeftThickness, TrackLeftRoundedEnd, TrackLeftRoundedStart, TrackLeftMarginEnd and TrackLeftMarginStart.
property float TrackLeftMarginEnd = 0.0;
The property 'TrackLeftMarginEnd' adjusts the end position of the left track relative to the end of the needle movement range. The movement range is determined by the properties NeedleMinAngle and NeedleMaxAngle. Configuring this property with a negative value causes the track to end beyond (outside) the needle movement range. The margin is expressed in degree.
Usually the end of the left track corresponds to the actual needle position. When the needle is moved, the length of the track is adjusted accordingly. By using this property, the tracks's end position can be limited to not exceed the predetermined angle. To adjust the start position of the track, use the property TrackLeftMarginStart.
The left track (composed of a filled arc and border surrounding it) is arranged relative to the center position of the gauge widget with radius configured in the property TrackLeftRadius. An optional displacement can be specified in the property CenterOffset. With the property TrackLeftStatic the left track can be configured to not depend on the actual needle position.
property float TrackLeftMarginStart = 0.0;
The property 'TrackLeftMarginStart' adjusts the start position of the left track relative to the start of the needle movement range. The movement range is determined by the properties NeedleMinAngle and NeedleMaxAngle. Configuring this property with a negative value causes the track to start beyond (outside) the needle movement range. The margin is expressed in degree.
The left track (composed of a filled arc and border surrounding it) is arranged relative to the center position of the gauge widget with radius configured in the property TrackLeftRadius. An optional displacement can be specified in the property CenterOffset.
property float TrackLeftRadius = 0.0;
The property 'TrackLeftRadius' specifies the radius of the circle segment displayed usually on the left (clockwise) of the actual needle position. The thickness of the track is determined in the property TrackLeftThickness.
The center of the circle segment corresponds to the position around which the needle is rotated (CenterOffset). See also TrackLeftMarginEnd, TrackLeftMarginStart, TrackLeftRoundedEnd and TrackLeftRoundedStart.
property bool TrackLeftRoundedEnd = false;
The property 'TrackLeftRoundedEnd' determines the appearance at the end of the left track (corresponding to the actual needle position). If this property is 'true', the cap at the track end is rounded otherwise it is flat. See also TrackLeftMarginEnd, TrackLeftRadius, TrackLeftThickness, TrackLeftRoundedStart.
property bool TrackLeftRoundedStart = false;
The property 'TrackLeftRoundedStart' determines the appearance at the beginning of the left track (corresponding to the leftmost rotation position (clockwise) of the needle). If this property is 'true', the cap at the track begin is rounded otherwise it is flat. See also TrackLeftMarginStart, TrackLeftRadius, TrackLeftThickness, TrackLeftRoundedEnd.
property int32 TrackLeftStackingPriority = 3;
The property 'TrackLeftStackingPriority' determines the Z-order position of the views destined to display the left track (filled arc and border surrounding it). Per default all left track views are arranged in front of the scale and right track views. By configuring this property the arrangement of the views within the widget can be changed whereby views with larger priority will be arranged in front of views with lower priority. For example, to place the left track views behind the right track, configure the property with a smaller value.
property bool TrackLeftStatic = false;
The property 'TrackLeftStatic' controls the size calculation of the area destined to display views belonging to the left track (filled arc and border surrounding it). If this property is 'false', the left track ends automatically at the actual position of the needle. When the needle is moved, the length of the track is adjusted accordingly.
By initializing this property with the value 'true', the track assumes its maximum possible length determined in the property TrackLeftMarginEnd. Now, the length of the track does not correspond anymore to the position of the needle. The track has a static length.
property float TrackLeftThickness = 0.0;
The property 'TrackLeftThickness' specifies the thickness of the circle segment displayed usually on the left (clockwise) of the actual needle position. The radius of the track is determined in the property TrackLeftRadius.
The center of the circle segment corresponds to the position around which the needle is rotated (CenterOffset). See also TrackLeftMarginEnd, TrackLeftMarginStart, TrackLeftRoundedEnd and TrackLeftRoundedStart.
property color TrackRightBorderColor = #FFFFFFFF;
The property 'TrackRightBorderColor' determines the color of the border surrounding the circle segment displayed usually on the right (clockwise) of the actual needle position. To determine the thickness of the border use the property TrackRightBorderWidth. See also TrackRightRadius, TrackRightThickness, TrackRightRoundedEnd, TrackRightRoundedStart, TrackRightMarginEnd and TrackRightMarginStart.
property float TrackRightBorderWidth = 0.0;
The property 'TrackRightBorderWidth' determines the thickness of the border surrounding the circle segment displayed usually on the right (clockwise) of the actual needle position. The value is expressed in pixel. To determine the color of the border use the property TrackRightBorderColor. See also TrackRightRadius, TrackRightThickness, TrackRightRoundedEnd, TrackRightRoundedStart, TrackRightMarginEnd and TrackRightMarginStart.
property color TrackRightColor = #FFFFFFFF;
The property 'TrackRightColor' determines the color of the circle segment displayed usually on the right (clockwise) of the actual needle position. See also TrackRightRadius, TrackRightThickness, TrackRightRoundedEnd, TrackRightRoundedStart, TrackRightMarginEnd and TrackRightMarginStart.
property float TrackRightMarginEnd = 0.0;
The property 'TrackRightMarginEnd' adjusts the end position of the right track relative to the end of the needle movement range. The movement range is determined by the properties NeedleMinAngle and NeedleMaxAngle. Configuring this property with a negative value causes the track to end beyond (outside) the needle movement range. The margin is expressed in degree.
The right track (composed of a filled arc and border surrounding it) is arranged relative to the center position of the gauge widget with radius configured in the property TrackRightRadius. An optional displacement can be specified in the property CenterOffset.
property float TrackRightMarginStart = 0.0;
The property 'TrackRightMarginStart' adjusts the start position of the right track relative to the start of the needle movement range. The movement range is determined by the properties NeedleMinAngle and NeedleMaxAngle. Configuring this property with a negative value causes the track to start beyond (outside) the needle movement range. The margin is expressed in degree.
Usually the start of the right track corresponds to the actual needle position. When the needle is moved, the length of the track is adjusted accordingly. By using this property, the tracks's start position can be limited to not exceed the predetermined angle. To adjust the end position of the track, use the property TrackRightMarginEnd.
The right track (composed of a filled arc and border surrounding it) is arranged relative to the center position of the gauge widget with radius configured in the property TrackRightRadius. An optional displacement can be specified in the property CenterOffset. With the property TrackRightStatic the right track can be configured to not depend on the actual needle position.
property float TrackRightRadius = 0.0;
The property 'TrackRightRadius' specifies the radius of the circle segment displayed usually on the right (clockwise) of the actual needle position. The thickness of the track is determined in the property TrackRightThickness.
The center of the circle segment corresponds to the position around which the needle is rotated (CenterOffset). See also TrackRightMarginEnd, TrackRightMarginStart, TrackRightRoundedEnd and TrackRightRoundedStart.
property bool TrackRightRoundedEnd = false;
The property 'TrackRightRoundedEnd' determines the appearance at the end of the right track (corresponding to the rightmost rotation position (clockwise) of the needle). If this property is 'true', the cap at the track end is rounded otherwise it is flat. See also TrackRightMarginEnd, TrackRightRadius, TrackRightThickness, TrackRightRoundedStart.
property bool TrackRightRoundedStart = false;
The property 'TrackRightRoundedStart' determines the appearance at the start of the right track (corresponding to the actual needle position). If this property is 'true', the cap at the track start is rounded otherwise it is flat. See also TrackRightMarginStart, TrackRightRadius, TrackRightThickness, TrackRightRoundedEnd.
property int32 TrackRightStackingPriority = 2;
The property 'TrackRightStackingPriority' determines the Z-order position of the views destined to display the right track (filled arc and border surrounding it). Per default all right track views are arranged in front of the scale view just behind the left track. By configuring this property the arrangement of the views within the widget can be changed whereby views with larger priority will be arranged in front of views with lower priority. For example, to place the right track views in front of the left track, configure the property with a larger value.
property bool TrackRightStatic = false;
The property 'TrackRightStatic' controls the size calculation of the area destined to display views belonging to the right track (filled arc and border surrounding it). If this property is 'false', the right track starts automatically at the actual position of the needle. When the needle is moved, the length of the track is adjusted accordingly.
By initializing this property with the value 'true', the track assumes its maximum possible length determined in the property TrackRightMarginStart. Now, the length of the track does not correspond anymore to the position of the needle. The track has a static length.
property float TrackRightThickness = 0.0;
The property 'TrackRightThickness' specifies the thickness of the circle segment displayed usually on the right (clockwise) of the actual needle position. The radius of the track is determined in the property TrackRightRadius.
The center of the circle segment corresponds to the position around which the needle is rotated (CenterOffset). See also TrackRightMarginEnd, TrackRightMarginStart, TrackRightRoundedEnd and TrackRightRoundedStart.
property point WidgetMaxSize = <0,0>;
The property 'WidgetMaxSize' determines the maximum allowed size of the gauge widget. Accordingly, the widget can't become bigger than the value specified in this property. By using this property you can configure the size constraints for the gauge widget.
property point WidgetMinSize = <0,0>;
The property 'WidgetMinSize' determines the minimal allowed size of the gauge widget. Accordingly, the widget can't become smaller than the value specified in this property. By using this property you can configure the size constraints for the gauge widget.
