Reference for the Mosaic class WidgetSet::HorizontalScrollbar

WidgetSet::HorizontalScrollbar
Appearance
ContentArea
OnEnd
OnScroll
OnStart
OnUpdate
Position
SnapFirst
SnapLast
SnapNext
ViewArea
GetCurrentState()
GetTransitionEndState()
GetTransitionProgress()
GetTransitionStartState()
Core::Group
AlphaBlended
Buffered
ClipViews
DeriveEnabledState
Embedded
Enabled
Focus
Opacity
Visible
Add()
AddBehind()
BroadcastEvent()
BroadcastEventAtPosition()
CountDialogs()
CountViews()
DismissDialog()
DispatchEvent()
DrawBackground()
DrawForeground()
ExtendClipping()
FadeGroup()
FindActiveDialogByClass()
FindCurrentDialog()
FindDialogByClass()
FindNextView()
FindPrevView()
FindSiblingView()
FindViewAtPosition()
FindViewInDirection()
FindViewWithStackingPriority()
FindViewWithinArea()
GetContentArea()
GetDialogAtIndex()
GetIndexOfDialog()
GetIndexOfView()
GetMaximalSize()
GetMinimalSize()
GetViewAtIndex()
GlobalPosition()
HasViewState()
Init()
InvalidateArea()
InvalidateLayout()
InvalidateViewState()
IsActiveDialog()
IsCurrentDialog()
IsDialog()
LocalPosition()
ObtainFocus()
PresentDialog()
Remove()
RemoveAll()
Restack()
RestackBack()
RestackBehind()
RestackTop()
SwitchToDialog()
UpdateLayout()
UpdateViewState()
Core::RectView
Bounds
Core::View
Layout
Owner
StackingPriority
AdjustDrawingArea()
ArrangeView()
ChangeViewState()
CursorHitTest()
Draw()
GetClipping()
GetExtent()
GetRoot()
HandleEvent()
MoveView()

SEE ALSO

Using and customizing the Horizontal Scrollbar widget.

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.

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.

The scrollbar widget provides an additional set of methods useful to query the actual state of the widget (GetCurrentState(), GetTransitionStartState(), GetTransitionEndState(), GetTransitionProgress()). 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 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.

method WidgetSet::CommonState GetCurrentState();

The method GetCurrentState() returns the state of the widget (Default, Disabled or Active) according to the latest user interaction. The obtained state information is useful to update decorations associated to the widget if those should depend on the widget's current state. For more details concerning the decorations, see the property OnUpdate.

Please note, if the widget is configured to perform animations during state transitions, you can use the methods GetTransitionStartState(), GetTransitionEndState() and GetTransitionProgress() to obtain information concerning the animation.

method WidgetSet::CommonState GetTransitionEndState();

The method GetTransitionEndState() returns the state of the widget (Default, Disabled or Active) valid after the actual state transition will finish. This information, together with the values returned by the methods GetTransitionStartState() and GetTransitionProgress(), can be useful to calculate the state of decoration views which depend on the progress of the animation. For more details concerning the decorations, see the property OnUpdate.

If the widget is not configured to perform any state transitions with animations or there is no transition in progress, GetTransitionEndState() returns the widget's latest state equal to the value returned by the method GetCurrentState().

method float GetTransitionProgress();

The method GetTransitionProgress() returns a value in range 0.0..1.0 according to the progress of the actually performed state transition. The start and the end states for the transition can be queried by the methods GetTransitionStartState() and GetTransitionEndState(). The obtained information can be useful to calculate the state of decoration views which depend on the progress of the animation. For more details concerning the decorations, see the property OnUpdate.

If the widget is not configured to perform any state transitions with animations or there is no transition in progress, GetTransitionProgress() returns the value 0.0.

method WidgetSet::CommonState GetTransitionStartState();

The method GetTransitionStartState() returns the state of the widget (Default, Disabled or Active) valid just before the actual state transition begun. This information, together with the values returned by the methods GetTransitionEndState() and GetTransitionProgress(), can be useful to calculate the state of decoration views which depend on the progress of the animation. For more details concerning the decorations, see the property OnUpdate.

If the widget is not configured to perform any state transitions with animations or there is no transition in progress, GetTransitionStartState() returns the widget's latest state equal to the value returned by the method GetCurrentState().

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 slot OnUpdate = null;

The property 'OnUpdate' can refer to a slot method, which should be invoked by the widget when its state changes (or more generally, when the user interacts with the widget). This method is intended to update decorations associated to this scrollbar widget.

From the implementation of the slot method you can invoke the method GetCurrentState(), GetTransitionStartState(), GetTransitionEndState() and GetTransitionProgress() to query the current state information of the widget.

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.