Reference for the Mosaic class WidgetSet::VerticalScrollbarConfig
This class implements the functionality permitting you to simply customize the look and feel of a 'vertical scrollbar' widget (WidgetSet::VerticalScrollbar). 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 vertical scrollbar widget. Thereupon the widgets will use the configuration information provided in the object.
During its lifetime the scrollbar remains always in one of the three states: 'disabled', 'default' and 'active'. The state 'disabled' is true for every not available scrollbar (the property 'Enabled' of the scrollbar is 'false'). Such scrollbars will ignore all user inputs. The state 'default' determines a scrollbar, which is ready to be touched by the user. Finally, the state 'active' is true, if the user actually interacts with the scrollbar (the scrollbar's thumb is pressed). With the configuration object you can specify the appearance of the scrollbar for every state individually. For this purpose you should know from which views the scrollbar is composed of:
With the properties AutoHideDelay and HideIfNotNeeded you can configure the behavior of the scrollbar, whether and when it should disappear automatically. If the scrollbar is configured to disappear and appear automatically, you can configure an opacity fade-in/out effect to be used for this operation by using the properties FadeInDuration and FadeOutDuration.
Whether the scrollbar should be able to react to user touch interactions or not can be configured in the property Touchable. If this property is 'true', the user can touch and drag the scrollbar thumb. If this property is 'false', the scrollbar serves as a pure passive widget.
With the properties WidgetMinSize and WidgetMaxSize you can configure size constraints for the widget itself. You can, for example, limit the scrollbar to not shrink below a specified width or height.
property int32 AutoHideDelay = 0;
The property 'AutoHideDelay' determines the period in milliseconds to hide the scrollbar automatically. When the scroll-range or position in the scrollbar changes or when the user touches within the scrollbar, the scrollbar appears again. When this property is 0 (zero), the scrollbar doesn't disappear automatically.
By configuring the properties FadeInDuration and FadeOutDuration you can determine whether the appearance/disappearance of the scrollbar should be performed with an opacity fade effect.
property int32 FadeInDuration = 0;
The property 'FadeInDuration' determines the duration of the opacity fade-in effect expressed in milliseconds to show the scrollbar again after it has been hidden in the past. If this property is 0 (zero), the scrollbar appears immediately without any effect.
The scrollbar can disappear and appear automatically only when the property HideIfNotNeeded is 'true' or the property AutoHideDelay is greater than 0.
property int32 FadeOutDuration = 0;
The property 'FadeOutDuration' determines the duration of the opacity fade-out effect expressed in milliseconds to hide the scrollbar. If this property is 0 (zero), the scrollbar disappears immediately without any effect.
The scrollbar can disappear and appear automatically only when the property HideIfNotNeeded is 'true' or the property AutoHideDelay is greater than 0.
property bool HideIfNotNeeded = false;
The property 'HideIfNotNeeded' controls how the scrollbar should behave, when the entire scrollable content can be presented at once without the necessity to scroll it. Setting this property to the value 'true' causes the scrollbar to disappear in such case. As soon as there is some content to scroll, the scrollbar appears again. If this property is 'false' and the scrollbar is not needed, the scrollbar remains visible with its track bitmap but without the thumb.
By configuring the properties FadeInDuration and FadeOutDuration you can determine whether the appearance/disappearance of the scrollbar should be performed with an opacity fade effect.
property int32 SnapDuration = 0;
The property 'SnapDuration' determines the duration in milliseconds of an animation effect to automatically adjust the scrollbar position to snap at predetermined snap position after the user has dragged the thumb and released it again. If this property is 0 (zero), the scrollbar adjusts the position immediately without the animation.
property Resources::Bitmap ThumbActive = null;
The property 'ThumbActive' determines the bitmap to be displayed horizontally centered at the actual thumb position when the scrollbar is in the 'active' state (the user is actually touching the scrollbar).
If the specified bitmap contains more than one frame (multi-frame bitmap), the desired frame number can be selected in the property ThumbFrameActive. If the selected bitmap is intended to be animated, ensure that the property ThumbFrameActive 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 ThumbTintActive. With the property ThumbTintActive you can also modulate the opacity of a regular bitmap.
Per default, the height of the displayed thumb does correspond to the ratio between the height of the visible area (view area) in the scrollable content and the entire height of the scrollable content. The maximal possible thumb height is limited by the actual height of the scrollbar minus the margins ThumbMarginBelow and ThumbMarginAbove.
The minimal thumb height is limited to the 2/3 of the original height of the used bitmap (the upper and lower edges of the bitmap without its interior area, see also Views::Frame). By setting the property ThumbSizeFixed, the thumb will assume permanently its minimal possible size.
property Resources::Bitmap ThumbDefault = null;
The property 'ThumbDefault' determines the bitmap to be displayed horizontally centered at the actual thumb position when the scrollbar is in the 'default' state.
If the specified bitmap contains more than one frame (multi-frame bitmap), the desired frame number can be selected in the property ThumbFrameDefault. If the selected bitmap is intended to be animated, ensure that the property ThumbFrameDefault 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 ThumbTintDefault. With the property ThumbTintDefault you can also modulate the opacity of a regular bitmap.
Per default, the height of the displayed thumb does correspond to the ratio between the height of the visible area (view area) in the scrollable content and the entire height of the scrollable content. The maximal possible thumb height is limited by the actual height of the scrollbar minus the margins ThumbMarginBelow and ThumbMarginAbove.
The minimal thumb height is limited to the 2/3 of the original height of the used bitmap (the upper and lower edges of the bitmap without its interior area, see also Views::Frame). By setting the property ThumbSizeFixed, the thumb will assume permanently its minimal possible size.
property Resources::Bitmap ThumbDisabled = null;
The property 'ThumbDisabled' determines the bitmap to be displayed horizontally centered at the actual thumb position when the scrollbar is in the 'disabled' state (property 'Enabled' of the scrollbar is 'false').
If the specified bitmap contains more than one frame (multi-frame bitmap), the desired frame number can be selected in the property ThumbFrameDisabled. If the selected bitmap is intended to be animated, ensure that the property ThumbFrameDisabled 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 ThumbTintDisabled. With the property ThumbTintDisabled you can also modulate the opacity of a regular bitmap.
Per default, the height of the displayed thumb does correspond to the ratio between the height of the visible area (view area) in the scrollable content and the entire height of the scrollable content. The maximal possible thumb height is limited by the actual height of the scrollbar minus the margins ThumbMarginBelow and ThumbMarginAbove.
The minimal thumb height is limited to the 2/3 of the original height of the used bitmap (the upper and lower edges of the bitmap without its interior area, see also Views::Frame). By setting the property ThumbSizeFixed, the thumb will assume permanently its minimal possible size.
property int32 ThumbFrameActive = -1;
The property 'ThumbFrameActive' determines the frame number within the bitmap ThumbActive. 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 ThumbActive bitmap is animated, the animation is automatically started as soon as the slider enters the 'active' state. If the bitmap is not animated and the property is -1, the frame with number 0 is displayed.
property int32 ThumbFrameDefault = -1;
The property 'ThumbFrameDefault' determines the frame number within the bitmap ThumbDefault. 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 ThumbDefault bitmap is animated, the animation is automatically started as soon as the scrollbar enters the 'default' state. If the bitmap is not animated and the property is -1, the frame with number 0 is displayed.
property int32 ThumbFrameDisabled = -1;
The property 'ThumbFrameDisabled' determines the frame number within the bitmap ThumbDisabled. 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 ThumbDisabled bitmap is animated, the animation is automatically started as soon as the scrollbar enters the 'disabled' state. If the bitmap is not animated and the property is -1, the frame with number 0 is displayed.
property int32 ThumbMarginAbove = 0;
The property 'ThumbMarginAbove' determines an additional gap in pixel between the upper edge of the scrollbar at the topmost position for the thumb. The thumb can't be moved beyond this position.
property int32 ThumbMarginBelow = 0;
The property 'ThumbMarginBelow' determines an additional gap in pixel between the lowermost position for the thumb and the bottom edge of the scrollbar. The thumb can't be moved beyond this position.
property bool ThumbSizeFixed = false;
The property 'ThumbSizeFixed' controls whether the thumb should retain its minimal possible height or whether its height should be adjusted according to the ratio between the height of the visible area (view area) in the scrollable content and the entire height of the scrollable content.
The maximal possible thumb height is limited by the actual height of the scrollbar minus the margins ThumbMarginBelow and ThumbMarginAbove. The minimal thumb height is limited to the 2/3 of the original height of the used bitmap (ThumbActive, ThumbDefault or ThumbDisabled) - means the top and bottom edges of the bitmap without its interior area (see also Views::Frame).
By setting the property 'ThumbSizeFixed', the thumb will assume permanently its minimal possible size.
property color ThumbTintActive = #FFFFFFFF;
The property 'ThumbTintActive' determines the color value to tint or modulate the bitmap specified in the property ThumbActive. The effect of this color value depends on the type of the bitmap:
property color ThumbTintDefault = #FFFFFFFF;
The property 'ThumbTintDefault' determines the color value to tint or modulate the bitmap specified in the property ThumbDefault. The effect of this color value depends on the type of the bitmap:
property color ThumbTintDisabled = #FFFFFFFF;
The property 'ThumbTintDisabled' determines the color value to tint or modulate the bitmap specified in the property ThumbDisabled. The effect of this color value depends on the type of the bitmap:
property bool Touchable = true;
The property 'Touchable' controls whether the user may touch and interact with the scrollbar. With this property initialized with the value 'false', the scrollbar is just a passive view.
property Resources::Bitmap TrackActive = null;
The property 'TrackActive' determines the bitmap to fill vertically the background of the scrollbar when the scrollbar is in the 'active' state (the user is actually touching the scrollbar). The bitmap is centered horizontally.
If the specified bitmap contains more than one frame (multi-frame bitmap), the desired frame number can be selected in the property TrackFrameActive. If the selected bitmap is intended to be animated, ensure that the property TrackFrameActive 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 TrackTintActive. With the property TrackTintActive you can also modulate the opacity of a regular bitmap.
property Resources::Bitmap TrackDefault = null;
The property 'TrackDefault' determines the bitmap to fill vertically the background of the scrollbar when the scrollbar is in the 'default' state. The bitmap is centered horizontally.
If the specified bitmap contains more than one frame (multi-frame bitmap), the desired frame number can be selected in the property TrackFrameDefault. If the selected bitmap is intended to be animated, ensure that the property TrackFrameDefault 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 TrackTintDefault. With the property TrackTintDefault you can also modulate the opacity of a regular bitmap.
property Resources::Bitmap TrackDisabled = null;
The property 'TrackDisabled' determines the bitmap to fill vertically the background of the scrollbar when the scrollbar is in the 'disabled' state (property 'Enabled' of the scrollbar is 'false'). The bitmap is centered horizontally.
If the specified bitmap contains more than one frame (multi-frame bitmap), the desired frame number can be selected in the property TrackFrameDisabled. If the selected bitmap is intended to be animated, ensure that the property TrackFrameDisabled 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 TrackTintDisabled. With the property TrackTintDisabled you can also modulate the opacity of a regular bitmap.
property int32 TrackFrameActive = -1;
The property 'TrackFrameActive' determines the frame number within the bitmap TrackActive. 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 TrackActive bitmap is animated, the animation is automatically started as soon as the scrollbar enters the 'active' state. If the bitmap is not animated and the property is -1, the frame with number 0 is displayed.
property int32 TrackFrameDefault = -1;
The property 'TrackFrameDefault' determines the frame number within the bitmap TrackDefault. 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 TrackDefault bitmap is animated, the animation is automatically started as soon as the scrollbar enters the 'default' state. If the bitmap is not animated and the property is -1, the frame with number 0 is displayed.
property int32 TrackFrameDisabled = -1;
The property 'TrackFrameDisabled' determines the frame number within the bitmap TrackDisabled. 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 TrackDisabled bitmap is animated, the animation is automatically started as soon as the scrollbar enters the 'disabled' state. If the bitmap is not animated and the property is -1, the frame with number 0 is displayed.
property color TrackTintActive = #FFFFFFFF;
The property 'TrackTintActive' determines the color value to tint or modulate the bitmap specified in the property TrackActive. The effect of this color value depends on the type of the bitmap:
property color TrackTintDefault = #FFFFFFFF;
The property 'TrackTintDefault' determines the color value to tint or modulate the bitmap specified in the property TrackDefault. The effect of this color value depends on the type of the bitmap:
property color TrackTintDisabled = #FFFFFFFF;
The property 'TrackTintDisabled' determines the color value to tint or modulate the bitmap specified in the property TrackDisabled. The effect of this color value depends on the type of the bitmap:
property point WidgetMaxSize = <0,0>;
The property 'WidgetMaxSize' determines the maximum allowed size of the widget. Accordingly, the scrollbar can't become bigger than the value specified in this property. By using this property you can configure the size constraints for the scrollbar.
property point WidgetMinSize = <0,0>;
The property 'WidgetMinSize' determines the minimal allowed size of the widget. Accordingly, the scrollbar can't become smaller than the value specified in this property. By using this property you can configure the size constraints for the scrollbar.