Reference for the Mosaic class WidgetSet::GaugeConfig

WidgetSet::GaugeConfig
CenterOffset
Cover
CoverFrame
CoverTint
Needle
NeedleFrame
NeedleMaxAngle
NeedleMinAngle
NeedlePivot
NeedleRadius
NeedleRotate
NeedleTint
Scale
ScaleFrame
ScaleTint
SwingDuration
SwingElastic
TrackLeftColor
TrackLeftRadius
TrackLeftRoundedEnd
TrackLeftRoundedStart
TrackLeftThickness
TrackRightColor
TrackRightRadius
TrackRightRoundedEnd
TrackRightRoundedStart
TrackRightThickness
WidgetMaxSize
WidgetMinSize
WidgetSet::WidgetConfig

SEE ALSO

Using and customizing the Gauge widget.

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.

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 the displacement in pixel for the position around it the needle bitmap (Needle) should rotate. Per default, the needle is rotated around the center of widget. By specifying a value for the property 'CenterOffset' this position moves accordingly - always relative to center of the widget.

property Resources::Bitmap Cover = null;

The property 'Cover' 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 Cover. 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 Cover 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 color CoverTint = #FFFFFFFF;

The property 'CoverTint' determines the color value to tint or modulate the bitmap specified in the property Cover. The effect of this color value depends on the type of the bitmap:

property Resources::Bitmap Needle = null;

The property 'Needle' 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 Needle. 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 Needle 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 (Needle) corresponding to 'MaxValue' specified in the gauge widget. The angle is expressed in degree, counted counterclockwise with 0 degree at the positive X-axis.

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 (Needle) corresponding to 'MinValue' specified in the gauge widget. The angle is expressed in degree, counted counterclockwise with 0 degree at the positive X-axis.

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 (Needle) 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. Please see also NeedlePivot and NeedleRotate.

property bool NeedleRotate = true;

The property 'NeedleRotate' determines whether the needle bitmap (Needle) 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 color NeedleTint = #FFFFFFFF;

The property 'NeedleTint' determines the color value to tint or modulate the bitmap specified in the property Needle. The effect of this color value depends on the type of the bitmap:

property Resources::Bitmap Scale = null;

The property 'Scale' 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 Scale. 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 Scale 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 color ScaleTint = #FFFFFFFF;

The property 'ScaleTint' determines the color value to tint or modulate the bitmap specified in the property Scale. 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 TrackLeftColor = #FFFFFFFF;

The property 'TrackLeftColor' determines the color of the circle segment displayed on the left (clockwise) of the actual needle position. See also TrackLeftRadius, TrackLeftThickness, TrackLeftRoundedEnd and TrackLeftRoundedStart.

property float TrackLeftRadius = 0.0;

The property 'TrackLeftRadius' specifies the radius of the circle segment displayed 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 TrackLeftColor, 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 straight. See also TrackLeftRadius, TrackLeftThickness, TrackLeftColor, 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 straight. See also TrackLeftRadius, TrackLeftThickness, TrackLeftColor, TrackLeftRoundedEnd.

property float TrackLeftThickness = 0.0;

The property 'TrackLeftThickness' specifies the thickness of the circle segment displayed 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 TrackLeftColor, TrackLeftRoundedEnd and TrackLeftRoundedStart.

property color TrackRightColor = #FFFFFFFF;

The property 'TrackRightColor' determines the color of the circle segment displayed on the right (clockwise) of the actual needle position. See also TrackRightRadius, TrackRightThickness, TrackRightRoundedEnd and TrackRightRoundedStart.

property float TrackRightRadius = 0.0;

The property 'TrackRightRadius' specifies the radius of the circle segment displayed 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 TrackRightColor, 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 straight. See also TrackRightRadius, TrackRightThickness, TrackRightColor, 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 straight. See also TrackRightRadius, TrackRightThickness, TrackRightColor, TrackRightRoundedEnd.

property float TrackRightThickness = 0.0;

The property 'TrackRightThickness' specifies the thickness of the circle segment displayed 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 TrackRightColor, 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.