Reference for the Mosaic class WidgetSet::HorizontalScrollbar
This class implements a 'horizontal scrollbar' widget. The widget is intended to show the horizontal scroll position and the size of the actually visible area (view) within the body of a large document (content). The size of the entire scrollable content and the size of the actually visible area are specified in the properties ContentArea and ViewArea. The current scroll position is determined by the property Position. The scrollbar calculates from these values the size and the position of the scrollbar thumb.
If the scrollbar is configured to handle user inputs (see below) and the user touches the thumb and drags it horizontally, the scrollbar current scroll position (Position) is adjusted and signal is sent to the slot method stored in the property OnScroll. 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 scrollbar. With the properties SnapFirst, SnapNext and SnapLast the scrollbar can be configured to automatically snap at predetermined positions when the user finishes the scroll interaction.
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).
The exact look and feel of the scrollbar is determined by the 'Horizontal Scrollbar Configuration' object assigned to the property Appearance. The configuration object provides bitmaps, colors and other configuration parameters needed to construct and display the scrollbar. Usually, you will manage in your project your own configuration objects and customize the scrollbars according to your design expectations. Depending on the information provided in the associated configuration object, the scrollbar will be composed of following views:
In the configuration object the scrollbar can be configured to disappear automatically when it is not needed (e.g. when the ViewArea is greater than or equal to the ContentArea) or it has not been used for a while. In the last case, the scrollbar appears again automatically when one of the properties Position, ContentArea or ViewArea has changed or the user has touched within the scrollbar area and the scrollbar is enabled for user interactions. Furthermore, the show and hide operation can be configured to be performed with an opacity fade-in/out effect.
In the configuration object you can determine, whether the scrollbar should be able to react to user touch interactions or not. If this mode is enabled, the user can touch and drag the thumb as described above. If this mode is not enabled, the scrollbar serves as a pure passive widget.
For more details regarding the customization of the scrollbar see the description of WidgetSet::HorizontalScrollbarConfig class.
property WidgetSet::HorizontalScrollbarConfig Appearance = null;
The property 'Appearance' refers to a 'Horizontal Scrollbar Config' object containing bitmaps, colors and further configuration attributes to customize this scrollbar widget. By assigning a configuration object to the property 'Appearance', the scrollbar automatically assumes the look and feel as determined in the properties of the configuration object.
If there is no configuration object associated to the scrollbar (the property 'Appearance' is 'null') the scrollbar appears empty (transparent).
Please note, configuration objects can be shared among multiple scrollbar widgets. When the properties of the configuration object change, all scrollbar widgets (connected actually to it) are notified and updated to assume the new appearance.
property int32 ContentArea = 100;
The property 'ContentArea' determines the size of the entire content to scroll. This usually corresponds to the width of the document (image, text, etc.) you want to present to the user.
In the usual application case, the value 'ContentArea' is greater than ViewArea. If 'ContentArea' is less than or equal to ViewArea, there is nothing to scroll and the scrollbar is not necessary. With the configuration object associated to the property Appearance you can configure the scrollbar to automatically disappear in such case.
Please note, the ratio between ViewArea and 'ContentArea' determines the width of the scrollbar's thumb. Accordingly, from the size of the thumb and the size of the scrollbar widget itself the user can deduce how much content is available to scroll.
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 scrollbar. 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 scrollbar. In the associated slot method you can evaluate the scrollbar's current value Position and e.g. adjust the position of the scrolled content accordingly.
property slot OnScroll = null;
The property 'OnScroll' can refer to a slot method, which will receive a signal each time the user drags the scrollbar's thumb.
Thereupon the method's logic will be executed. In the associated slot method you can evaluate the scrollbar's current value Position and e.g. adjust the position of the scrolled content accordingly.
property slot OnStart = null;
The property 'OnStart' can refer to a slot method, which will receive a signal as soon as the user touches the scrollbar's thumb. 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 scrollbar. In the associated slot method you can evaluate the scrollbar's current value Position.
property int32 Position = 0;
The property 'Position' determines the current scroll position within the entire content. This value corresponds to the horizontal position of the scrollbar's thumb and it is limited to be always within the range 0 .. ( ContentArea - ViewArea ).
If the scrollbar is allowed to react to user interactions (property Enabled is 'true'), the value of 'Position' is updated automatically while the user drags on the scrollbar's thumb. In such case the scrollbar automatically adjusts the 'Position' to be a multiple of the value specified in the property SnapNext.
property int32 SnapFirst = 0;
The property 'SnapFirst' determines the first position where the scrollbar should automatically snap after the user terminates the scrolling. The snap positions are aligned relative to the left edge of the scrolled content. With the properties SnapNext and SnapLast further snap positions can be configured. If this property is 0, the snap position is ignored.
property int32 SnapLast = 0;
The property 'SnapLast' determines the last position where the scrollbar should automatically snap after the user terminates the scrolling. The position is aligned relative to the right edge of the scrolled content. With the properties SnapFirst and SnapNext further snap positions can be configured. If this property is 0, the snap position is ignored.
property int32 SnapNext = 0;
The property 'SnapNext' determines an optional distance between consecutive snap positions the scrollbar should snap after the user terminates the scrolling. The snap positions are aligned relative to the left edge of the scrolled content. With the properties SnapFirst and SnapLast the first and the last snap position in the scrolled content can be configured explicitly. If this property is 0, the snap position is ignored.
property int32 ViewArea = 10;
The property 'ViewArea' determines the size of the visible portion of the entire content. This usually corresponds to the width of the viewport where the user can see the document (the image, text, etc.).
In the usual application case, the value 'ViewArea' is less than ContentArea. If 'ViewArea' is greater than or equal to ContentArea, there is nothing to scroll and the scrollbar is not necessary. With the configuration object associated to the property Appearance you can configure the scrollbar to automatically disappear in such case.
Please note, the ratio between 'ViewArea' and ContentArea determines the width of the scrollbar's thumb. Accordingly, from the size of the thumb and the size of the scrollbar widget itself the user can deduce how much content is available to scroll.
