Using Widgets: Vertical Scrollbar

The Mosaic class WidgetSet::VerticalScrollbar implements a GUI component intended to serve as a Vertical Scrollbar widget. This widget can be used to compose the appearance of other more complex GUI components, in particular to add to them controls intended to show the vertical scroll position and the height of the actually visible area (view) within the body of a large document (content). Each time the user interacts with a Vertical Scrollbar, the widget sends signals to associated slot methods where your particular implementation is executed. Controlling the scrollbars via keyboard or hardware buttons is not intended.

If desired, the scrollbars can also be configured to act as pure passive widgets which then ignore any touch events. Such configured scrollbars are predestined to only show to the user the current position within the scrolled content. To allow the user to scroll the contents another technique (for example the Slide Touch Handler or Key Press Handler) has to be used. Scrollbars can also be configured to disappear automatically when these are not needed, e.g. if the content is already entirely visible so the user has nothing to scroll.

The exact appearance and behavior of the Vertical Scrollbar is determined by a Vertical Scrollbar Config object. This configuration object provides bitmaps, colors and other configuration parameters needed to construct and display the affected Vertical Scrollbar. Embedded Wizard is delivered with a set of prepared Vertical Scrollbar Config objects you can use instantly as they are. However, if desired, you can create your own configuration objects and so customize the Vertical Scrollbar widgets according to your particular design expectations. The following screenshot demonstrates few examples of how Vertical Scrollbars appear in the canvas area of Composer (and accordingly on the screen in your target device):

The following sections are intended to provide you an introduction and useful tips of how to work with and how to customize the Vertical Scrollbars. For the complete reference please see the documentation of the WidgetSet::VerticalScrollbar and WidgetSet::VerticalScrollbarConfig classes.

Add new Vertical Scrollbar

To add a new Vertical Scrollbar widget just at the design time of a GUI component do following:

First ensure that the Templates window is visible.

In Templates window switch to the folder Widgets.

In the folder locate the template Vertical Scrollbar.

Drag & Drop the template into the canvas area of the Composer window:

Eventually name the new added Vertical Scrollbar widget.

Inspect the Vertical Scrollbar

As long as the Vertical Scrollbar widget is selected you can inspect and modify its properties conveniently in the Inspector window as demonstrated with the property Bounds in the screenshot below:

This is in so far worth mentioning as all following sections describe diverse features of the Vertical Scrollbar widget by explicitly referring to its corresponding properties. If you are not familiar with the concept of a property and the usage of Inspector window, please read first the preceding chapter Compositing component appearance.

Arrange the Vertical Scrollbar

Once added, you can freely move the Vertical Scrollbar, or you simply grab one of its corners and resize it in this way. You can control the position and the size of the widget also by directly modifying its property Bounds. If you want the Vertical Scrollbar to appear behind other views you can reorder it explicitly.

Select the appearance for the Vertical Scrollbar

The appearance and partially also the behavior of the Vertical Scrollbar widget can be configured according to your particular design expectation. For demonstration purpose and to help you to quickly create new product prototypes, Embedded Wizard contains nine ready to use configurations. The configurations are provided in two different designs we named Mono and Lime. In each design there are three different sizes Small, Medium and Large. In case of the Lime design there is an additional Mini version available. The following figure demonstrates all available default configurations at once:

The configurations are divided in two sets, every with three sizes small, medium and large. The first set is predestined to be used wherever you need an interactive scrollbar. The user can touch and drag their thumbs. The second set (called Mini) presents a thinner variant of the scrollbars. These are not interactive and they are configured to automatically disappear when not needed.

TIP

The design Mono is new in Embedded Wizard 13. This design uses simple visual elements like rounded rectangles and shadows. These can be configured concerning their size and colors in a simple manner. The Lime design, in turn, is based on images. In this case, the size and colors are imposed by the used bitmap resources. On the other hand, by using bitmaps, the configurations can be more expressive and colorful.

To use the desired appearance configuration you have to select it in the property Appearance of the affected Vertical Scrollbar widget as demonstrated in the screenshot below. You can use the integrated Inspector Assistant window to conveniently select the right configuration. If you like the provided default configurations then you can use them as they are:

If you prefer to adapt the appearance of the Vertical Scrollbar by yourself, then you have to create a new Vertical Scrollbar Config object and specify in it all the bitmaps, colors as well as other parameters to customize your individual Vertical Scrollbar. Once your configuration object is available, you can select it in the property Appearance exactly as you select one of the configurations provided per default with Embedded Wizard.

Understand the states of the Vertical Scrollbar

During its life time, the Vertical Scrollbar remains always in one of its three possible states. While the user interacts with the widget, the scrollbar switches between the states fourth and back. Understanding these states is especially essential when you intend to customize your own individual Vertical Scrollbar. The following table provides an overview of all Vertical Scrollbar states:

State name

Example

Description

Default

The state Default determines a scrollbar, which is ready to be touched by the user. This is also the case if the scrollbar has been configured as a passive widget not intended to handle any user inputs.

Active

The state Active is true, if the user actively touches the scrollbar's thumb. You can imagine, in the Active state, the user interacts with the scrollbar.

Disabled

The state Disabled is true for every not available scrollbar (the property Enabled of the scrollbar is false). Such scrollbars will ignore any user inputs.

Determine the scrollbar's current scroll position and scroll range

The Vertical Scrollbar widget is intended to show the scroll position and the height of the actually visible area (the view) within the body of a large document (the content). The height of the entire content and the height of its actually visible area are specified in the corresponding properties ContentArea and ViewArea, both as positive integer values. The current scroll position is determined by the property Position as distance relative to the begin of the content. Based on these values the scrollbar calculates the size and the position for its thumb. The following figure demonstrates the relations between the three properties:

Accordingly, the value of the property Position moves in the range between 0 and ContentArea-ViewArea. If you modify the property Position, ViewArea or ContentArea, the affected scrollbar will implicitly update the position and/or height of its thumb. In turn, if the scrollbar is configured as interactive and the user drags on its thumb, the scrollbar adapts the value of its property Position. By evaluating this property you can simply query which position is actually set in the affected scrollbar.

Please note, if desired, the scrollbar can be configured to not adapt the height of the thumb. In this mode, the thumb will always appear with the smallest possible, fixed height regardless of the actual ratio between the values of the properties ViewArea and ContentArea. Only the vertical position of the thumb changes.

The following example demonstrates how you work with the above mentioned properties. The example contains a Vertical List and a Slide Touch Handler connected together so the user can scroll the list's contents conveniently by simply touching within the list's area. The example contains an additional Vertical Scrollbar intended to show to the user the actual scroll position. Every time the list is scrolled, the scrollbar's properties are updated and the user can recognize the actual position within the list. Please note, this example uses the Mini variant of the per default provided scrollbars. These scrollbars are configured to not react to touch events and to automatically disappear after a short delay:

DOWNLOAD EXAMPLE

Please note, the example presents eventually features available as of version 9.00

Implement scrollbar's slot methods

While the user interacts with a Vertical Scrollbar widget and this scrollbar is configured as interactive, the widget sends signals to associated slot methods. Within the slot method your particular implementation can react and process the event. The slot methods are connected to the widget by simply storing them in the for this purpose available properties. The following table describes them:

Property

Description

OnStart

Slot method associated to this property receives a signal as soon as the user touches the scrollbar's thumb. In other words, this event is triggered at the beginning of the interaction between user and the scrollbar.

OnEnd

Slot method associated to this property receives a signal as soon as the user lifts the finger from the Vertical Scrollbar. In other words, this event is triggered at the end of the interaction between user and the scrollbar.

OnScroll

Slot method associated to this property receives a signal as soon as the user has dragged the scrollbar's thumb causing the scrollbar's position to be changed.

The following sequence diagram demonstrates a typical order in which the slot methods receive signals while the user interacts with the Vertical Scrollbar. Please note, that every interaction starts with a signal sent to the OnStart and ends with a signal sent to the OnEnd slot method. In between, the widget will send signals to OnScroll slot method, every time the user drags the thumb:

Providing slot methods for all properties is not obligatory. In typical application cases it is sufficient to implement the slot method for the OnScroll event only leaving all other properties initialized with the value null. You can initialize the properties with already existing slot methods or you add a new one and implement it as desired. The following steps describe how to do this:

First add a new slot method to your GUI component.

Assign the slot method to the corresponding property of the affected Vertical Scrollbar widget (e.g. to the property OnScroll).

Open the slot method for editing.

In the Code Editor implement your desired operation to execute when the event occurs.

Usually, in the implementation of the slot method you will evaluate the scrollbar's position. You can, for example, use it to adjust the scroll position of the content associated to the scrollbar. The following code demonstrates:

// Adjust the scroll position of a 'Vertical List' to correspond to the position // determined by the scrollbar. VerticalList.ScrollOffset = -Scrollbar.Position;

The following example project demonstrates how the Vertical Scrollbar is used to scroll the content of a Vertical List. Every time the user touches inside the scrollbar's thumb and drags the finger, the thumb is moved and the slot method associated to the property OnScroll is signaled. The slot method, in turn, contains code to accordingly adjust the scroll position of the list:

DOWNLOAD EXAMPLE

Please note, the example presents eventually features available as of version 9.00

Configure scrollbar's snap positions

Per default, the Vertical Scrollbar's position can lie anywhere inside the possible range. For example, when the scrollbar is used to scroll items within a Vertical List, the resulting scroll offset can become a value lying in the middle of an item, which then appears ugly clipped:

By using the property SnapNext you can instruct the scrollbar to automatically stop at positions, which are always a multiple of the value stored in SnapNext property. From the user's point of view, the Vertical Scrollbar snaps at those positions when the user after dragging on scrollbar's thumb releases it again. For example, initializing SnapNext with the value 40 will cause the scrollbar to snap at scroll positions 0, 40, 80, 120, ...

With the above described example of a Vertical Scrollbar used to scroll the items within a Vertical List, you can configure the property SnapNext with a value corresponding to the height of a single list item. Later when the user uses the scrollbar to scroll the list, the scrollbar will snap at the borders lying between two items. The first visible list item is not clipped anymore:

If your application case it requires, with the properties SnapFirst and SnapLast you can configure different values for the first and the last snap position. Accordingly, the Vertical Scrollbar will snap first after a distance determined by SnapFirst, then after every further distance determined by SnapNext. The last snap position lies SnapLast far away from the end of the scroll range.

The following example demonstrates how you use the snap positions. The example contains a Vertical List and a Vertical Scrollbar. The user can touch and drag on the scrollbar's thumb causing the list to scroll accordingly. When the user releases the finger, the scrollbar snaps at the next available position:

DOWNLOAD EXAMPLE

Please note, the example presents eventually features available as of version 9.00

Combine the Scrollbar with decoration views

The appearance of the Scrollbar is limited to visual elements that compose it. Even if it is possible to customize the Vertical Scrollbar, the number of available visual elements can become a limiting factor when your design requires the widget to appear with complex decorations. In such case, please use the available views. For example, you can add a Text view and arrange it on the side of the Scrollbar. Such view could then be used to display e.g. the current scroll position, etc.

Usually, doing this, you will want the additional decoration views to be automatically arranged at predetermined positions or to appear according to the current state of the widget. The WidgetSet::VerticalScrollbar class provides for such application cases various useful methods. The following table gives you a short overview of them:

Method

Description

GetCurrentState()

Returns the state of the widget according to the latest user interaction.

GetTransitionStartState()

Returns the state of the widget valid just before the actual state transition animation begun.

GetTransitionEndState()

Returns the state of the widget valid after the actual state transition animation will finish.

GetTransitionProgress()

Returns a value in range 0.0..1.0 according to the progress of the actually performed state transition animation.

You can call those methods whenever your GUI component implementation requires the corresponding information. More sophisticated, however, is to join the update mechanism provided natively by the Vertical Scrollbar widget. Precisely, when you assign a slot method to the scrollbar's property OnUpdate, the slot method will receive postsignals every time the state of the widget changes.

Accordingly, within the slot method you can react on this notification and e.g. arrange position of other views or update their appearance to correspond to the current state of the widget. The following steps describe how to do this:

First add a new slot method to your GUI component.

Assign the slot method to the property OnUpdate of the Vertical Scrollbar widget.

Open the slot method for editing.

In the Code Editor implement your desired arrangement algorithm by using the values returned from the above described Vertical Scrollbar methods.

Assuming, your GUI component contains a Vertical Scrollbar named Scrollbar and a Text view named PositionText. Furthermore let's assume you want the Text view to appear arranged centered on the right of the scrollbar and it should display the current scroll position. The Text view should be visible during active touch interaction only. In such application case implement the slot method with following Chora code:

// Adjust the position of the view to appear centered on the right of the scrollbar PositionText.Bounds.origin = Scrollbar.Bounds.center + point( 10, -PositionText.Bounds.orect.center.y ); // Update the text displayed in the Text view PositionText.String = string( Scrollbar.Position ) + " pixel"; // Display the additional text only during the 'ACTIVE' state. PositionText.Visible = Scrollbar.GetCurrentState() == WidgetSet::CommonState.Active;

The following example project demonstrates this application case. When you download and open the example, you will see two Vertical Scrollbars with their associated and automatically updated Text views:

DOWNLOAD EXAMPLE

Please note, the example presents eventually features available as of version 13.00

Disable the Vertical Scrollbar

If the Vertical Scrollbar is configured to be interactive, it can sometimes be necessary to disable the scrollbar, so that it ignores temporarily any touch events. You achieve this by setting the property Enabled of the affected scrollbar to the value false. Thereupon the Vertical Scrollbar enters in the Disabled state and its appearance changes to indicate to the user, that the associated function is actually not available. Please read the section Control the Enabled state of nested components for further details and more precise explanation.

In the case, the Vertical Scrollbar is already configured to not handle any user inputs, the scrollbar will behave as a passive widget. Such scrollbar will ignore any user inputs regardless of whether it is enabled or not.

Control the visibility of the Vertical Scrollbar

If desired, you can hide the Vertical Scrollbar so it is not visible to the user. You achieve this by setting the property Visible of the affected scrollbar to the value false. Please read the section Control the visibility of nested components for further details and more precise explanation. In more sophisticated cases, you can configure the scrollbar to disappear automatically, when it is not needed.

Customize your own Vertical Scrollbar

Newly added Vertical Scrollbars use an appearance configuration provided per default with Embedded Wizard installation. As described above these default configurations are available in two different designs, variants and multiple sizes you can select easily. If you like them, you can use them as they are. However, should the scrollbars in your GUI design have another appearance or behavior, then you will need to provide your own appearance configuration.

To provide a new configuration you create an object of the class WidgetSet::VerticalScrollbarConfig and initialize its properties with all the bitmaps, colors and other parameters particular to your own design. Once this object is available, you can assign it to every Vertical Scrollbar you want to appear with this configuration similarly as you select one of the per default provided configurations. If necessary, you can create several different configuration objects and use them simultaneously within your application. You can even customize every Vertical Scrollbar instance individually.

Before you start to customize your own Vertical Scrollbars you should understand two important aspects. As first recall the section Vertical Scrollbar states. When you customize a Vertical Scrollbar, you will specify for every possible scrollbar state individual parameters. Understanding these states is thus essential. Furthermore, you have to understand from which views (visual elements) the Vertical Scrollbars are composed of. In the configuration object you can individually specify parameters for every view. The following table provides an overview of the views existing internally within every Vertical Scrollbar:

Visual element

Description

Track

A visual element composed of bitmap frame view, filled rectangle and border views filling horizontally centered the entire height in the background of the scrollbar. The bitmap, colors, border width and the width of the track can be configured for each scrollbar state individually.

Thumb

A visual element composed of a bitmap frame view, filled rectangle, border and shadow views filling horizontally centered the foreground of the scrollbar at vertical position and with its height adjusted to correspond to the current scroll position and scroll range. The bitmap, colors, border width and the width of the thumb can be configured for each scrollbar state individually.

The following figure demonstrates once more the above described views existing internally in every Vertical Scrollbar. Please note how the visual elements are arranged one above the other. Per default, the visual element Track resides in the background of the widget:

Please note, the set of views existing within the Vertical Scrollbar is finished implemented in the Vertical Scrollbar component and can't be modified. With the configuration object you can customize the appearance of the affected views only. If you expect the Vertical Scrollbar to appear and behave beyond our default implementation, you will need to implement your own scrollbar component. Please see the section Widgets versus Component templates.

TIP

Eventually (and depending on your desired design) also possible could be to Enhance the Vertical Scrollbar configuration by additional decoration views.

The following sections are intended to provide you an introduction and useful tips of how to work with the Vertical Scrollbar Config object. For the complete reference please see the documentation of the WidgetSet::VerticalScrollbarConfig class.

Add new Vertical Scrollbar Config object

Depending on your application case, you have the option to add the configuration object as an embedded object directly to a GUI component or to add it as an autoobject to a unit. The first case is suitable if you want the configuration object to be used only by Vertical Scrollbars existing locally within the GUI component. The second case, in turn, is appropriate if you intend to share the configuration object among multiple GUI components like a kind of common resource.

To add a new Vertical Scrollbar Config object do following:

Depending on your preferred option switch to the Composer page for the respective GUI component class or the unit where you want to add the Vertical Scrollbar Config object.

Then ensure that the Templates window is visible.

In Templates window switch to the folder Resources.

In the folder locate the template Vertical Scrollbar Config.

Drag & Drop the template into the Composer window:

Eventually name the new added Vertical Scrollbar Config object.

Inspect the Vertical Scrollbar Config object

As long as the Vertical Scrollbar Config object is selected you can inspect and modify its properties conveniently in the Inspector window as demonstrated with the property TrackBitmapDefault in the screenshot below. Please note, for better overview the below screenshot has been made with Inspector window being configured to sort the properties by categories:

This is in so far worth mentioning as the following sections describe diverse features of the Vertical Scrollbar Config object by explicitly referring to its corresponding properties. If you are not familiar with the concept of a property and the usage of Inspector window, please read first the preceding chapter Compositing component appearance.

Specify bitmaps and colors for the scrollbar's track image

As explained in the section above the Track view occupies horizontally centered the entire height in the background of every Vertical Scrollbar. With the following properties you specify the bitmap resources as well as other parameters to be used by this view depending on the scrollbar's actual state. In other words, you use them to configure the appearance of the Vertical Scrollbar's background:

Property

Description

TrackBitmapDefault

TrackBitmapActive

TrackBitmapDisabled

With these properties you specify the bitmap resource the Vertical Scrollbar has to display in its background Track view. You have to specify the bitmaps individually for every possible scrollbar state. If you leave one property initialized with the value null, the background remains empty (transparent) as long as the scrollbar is in the corresponding state.

TrackFrameDefault

TrackFrameActive

TrackFrameDisabled

These properties are relevant only if the bitmap resource specified in the corresponding above described property TrackBitmapDefault, TrackBitmapActive or TrackBitmapDisabled contains more than one frame. In such case you use them to determine the desired frame number. Is one of the bitmaps additionally configured as containing an animated sequence you can initialize the corresponding TrackFrame... property with the value -1 to instruct the Vertical Scrollbar to automatically play the animation as long as the scrollbar remains in this state.

TrackTintDefault

TrackTintActive

TrackTintDisabled

The effect of these three properties depends on the type of the bitmap resource specified in the corresponding above described property TrackBitmapDefault, TrackBitmapActive or TrackBitmapDisabled. In case of alpha-only bitmaps you use the properties to determine the colors to tint the bitmaps. In all other cases you can use the alpha value of the corresponding TrackTint... property to simply modulate the opacity of the affected bitmap.

The specified bitmaps will fill horizontally centered the entire height of the Vertical Scrollbar. This is achieved by so-called 9-slice image scaling technique where the intended destination area is filled with slices copied from the original bitmap. In case of the Vertical Scrollbar, however, the slices are copied vertically only. In the horizontal direction, the bitmaps retain their original width and they are just centered within the background area. Therefore, if you want the Vertical Scrollbar to be flexibly resizable, you have to ensure that the used Face bitmaps are composed of three equally sized slices arranged in a single column as shown in the following figure. You should consider this aspect when designing the bitmaps in a graphic editor:

In turn, if the bitmaps in the background of your Vertical Scrollbar are intended to always have the same fixed height, you can ignore the above bitmap design restrictions. Just design your desired bitmaps and explicitly define size constraints for the widget itself to ensure, that its height is fixed and it corresponds to the of the used Track bitmaps.

If you leave all three properties TrackBitmapDefault, TrackBitmapActive and TrackBitmapDisabled initialized with null, the Vertical Scrollbar will appear without any background.

Configure the shape of the Scrollbar's track (as scalable vector graphic)

Starting with version 13, the Vertical Scrollbar enhances its visual element Track by a rectangle and border views. Those new views display the track using scalable vector graphic so that the Vertical Scrollbar is not restricted anymore to use bitmap resources only. To configure the area and the shape of the new views, following properties are available:

Property

Description

TrackThicknessDefault

TrackThicknessActive

TrackThicknessDisabled

These properties determine the width in pixel of a filled rectangle and border belonging to the track when the scrollbar is in the corresponding state. That means, the properties control the width of the track.

TrackCornerRadiusDefault

TrackCornerRadiusActive

TrackCornerRadiusDisabled

These properties control the rounding at corners of the track views when the scrollbar is in the corresponding state. Normally, the track views have the shape of a rectangle with sharp corners. Specifying a value greater than 0 in these properties rounds the corners. The larger the value, the bigger the rounding effect.

The following figure demonstrates the effect of diverse property combinations. The gray thin borders indicate the areas of the resulting Scrollbar. For demonstration purpose the track views are configured to appear with rounded corners:

Please note, per default the track is centered horizontally within the area of the Vertical Scrollbar. As explained in the section Specify the offset and margins for the Scrollbar's track this horizontal position as well as the top and bottom margins for the track can be configured.

Configure the colors and borders of the Scrollbar's track (as scalable vector graphic)

Starting with version 13, the Vertical Scrollbar enhances its visual element Track by a rectangle and border views. Those new views display the track using scalable vector graphic so that the Vertical Scrollbar is not restricted anymore to use bitmap resources only. As described in the section above the shape of the new track views can be configured for each widget state individually. With following properties you configure the colors to fill the background of the track and to stroke its borders:

Property

Description

TrackColorDefault

TrackColorActive

TrackColorDisabled

These properties determine the color to fill the background of the track when the scrollbar is in the corresponding state.

TrackBorderWidthDefault

TrackBorderWidthActive

TrackBorderWidthDisabled

These properties determine the thickness of the border surrounding the track when the scrollbar is in the corresponding state.

TrackBorderColorDefault

TrackBorderColorActive

TrackBorderColorDisabled

These properties determine the color to stroke the border surrounding the track when the scrollbar is in the corresponding state. To see the border ensure that the properties from the list above configure the border thickness greater than 0.

The following figure demonstrates the effect of diverse property combinations. The gray thin borders indicate the areas of the resulting Vertical Scrollbar. For demonstration purpose the track views are configured to appear with rounded corners:

Please note, if the track is configured to fill the background and stroke border around it, the border will always appear in front of the filled background area as demonstrated in the figure above.

Specify the offset and margins for the Scrollbars's track

Per default, the track fills the area between the top and bottom edges of the widget. If this is not desired, you can specify in the properties TrackMarginTop and TrackMarginBottom additional gaps in pixel between the track and the respective top or bottom edge of the scrollbar. The following figure demonstrates the effect of these properties (the gray borders indicate the areas of the respective scrollbar):

Unless it was explicitly configured, the tracks are centered horizontally within the Scrollbar's area. By using the properties TrackOffsetDefault, TrackOffsetActive and TrackOffsetDisabled an additional horizontal displacement for the track can be configured. The resulting track position can thus depend on the current state of the widget. For example, in the Active state the Track views may appear slightly shifted resulting in the visual effect as if the Scrollbar were pressed:

Specify bitmaps and colors for the scrollbar's thumb image

As explained in the section above the Thumb view occupies horizontally centered the area in the foreground of every Vertical Scrollbar. The vertical position and the height of the view depends on the scrollbar's position and the specified scroll range. With the following properties you specify the bitmap resources as well as other parameters to be used by this view depending on the scrollbar's actual state. In other words, you use them to configure the appearance of the Vertical Scrollbar's foreground:

Property

Description

ThumbBitmapDefault

ThumbBitmapActive

ThumbBitmapDisabled

With these properties you specify the bitmap resource the Vertical Scrollbar has to display in its foreground Thumb view. You have to specify the bitmaps individually for every possible scrollbar state. If you leave one property initialized with the value null, the thumb remains empty (transparent) as long as the scrollbar is in the corresponding state.

ThumbFrameDefault

ThumbFrameActive

ThumbFrameDisabled

These properties are relevant only if the bitmap resource specified in the corresponding above described property ThumbBitmapDefault, ThumbBitmapActive or ThumbBitmapDisabled contains more than one frame. In such case you use them to determine the desired frame number. Is one of the bitmaps additionally configured as containing an animated sequence you can initialize the corresponding ThumbFrame... property with the value -1 to instruct the Vertical Scrollbar to automatically play the animation as long as the scrollbar remains in this state.

ThumbTintDefault

ThumbTintActive

ThumbTintDisabled

The effect of these three properties depends on the type of the bitmap resource specified in the corresponding above described property ThumbBitmapDefault, ThumbBitmapActive or ThumbBitmapDisabled. In case of alpha-only bitmaps you use the properties to determine the colors to tint the bitmaps. In all other cases you can use the alpha value of the corresponding ThumbTint... property to simply modulate the opacity of the affected bitmap.

The specified bitmaps will fill horizontally centered the Vertical Scrollbar with a height being proportional to the ratio between the specified size of the view area and content area. This is achieved by so-called 9-slice image scaling technique where the intended destination area is filled with slices copied from the original bitmap. In case of the Vertical Scrollbar, however, the slices are copied vertically only. In the horizontal direction, the bitmaps retain their original width and they are just centered within the background area. Therefore, you have to ensure that the used Thumb bitmaps are composed of three equally sized slices arranged in a single column as shown in the following figure. You should consider this aspect when designing the bitmaps in a graphic editor:

Please note, the scrollbars can be configured to not automatically adapt the height of the thumb. In this mode, the thumb will always appear with its smallest possible, fixed height regardless of the actual ratio between the view area and content area. Only the vertical position of the thumb changes. You can imagine, such configured scrollbar displays the thumb composed of the top and bottom slices only (in the figure above the slices H1 and H3). The middle slice (H2) is omitted. Accordingly, the smallest possible height of the thumb is 2/3 of the height of the original bitmap.

If you leave all three properties ThumbBitmapDefault, ThumbBitmapActive and ThumbBitmapDisabled initialized with null, the Vertical Scrollbar will appear without any foreground.

Configure the shape and the layout of the Scrollbar's thumb (as scalable vector graphic)

Starting with version 13, the Vertical Scrollbar enhances its visual element Thumb by a rectangle, border and shadow views. Those new views display the thumb using scalable vector graphic so that the Vertical Scrollbar is not restricted anymore to use bitmap resources only. To configure the area and the shape of the new views, following properties are available:

Property

Description

ThumbThicknessDefault

ThumbThicknessActive

ThumbThicknessDisabled

These properties determine the width in pixel of a filled rectangle, border and shadow views belonging to the thumb when the scrollbar is in the corresponding state. That means, the properties control the width of the thumb.

ThumbCornerRadiusDefault

ThumbCornerRadiusActive

ThumbCornerRadiusDisabled

These properties control the rounding at corners of the thumb views when the scrollbar is in the corresponding state. Normally, the thumb views have the shape of a rectangle with sharp corners. Specifying a value greater than 0 in these properties rounds the corners. The larger the value, the bigger the rounding effect.

The following figure demonstrates the effect of diverse property combinations. The gray thin borders indicate the areas of the resulting Scrollbar. For demonstration purpose the thumb views are configured to appear with rounded corners:

Please note, per default the thumb is centered horizontally within the area of the Vertical Scrollbar. As explained in the section Specify the offset and margins for the Scrollbar's thumb this position as well as the top and bottom margins for the thumb can be configured. Furthermore, the height of the thumb corresponds per default to the actual ratio between the specified view and content areas as explained in section Configure the size behavior of the scrollbar's thumb. Finally, if the Scrollbar is configured so that parts of its thumb are lying outside the Scrollbar's area, these are not clipped and will remain visible outside the widget. These parts, however, are not sensitive to touch or mouse interactions.

Configure the colors and borders of the Scrollbar's thumb (as scalable vector graphic)

Starting with version 13, the Vertical Scrollbar enhances its visual element Thumb by a rectangle, border and shadow views. Those new views display the thumb using scalable vector graphic so that the Vertical Scrollbar is not restricted anymore to use bitmap resources only. As described in the section above the shape of the new thumb views can be configured for each widget state individually. With following properties you configure the colors to fill the background of the thumb and to stroke its borders:

Property

Description

ThumbColorDefault

ThumbColorActive

ThumbColorDisabled

These properties determine the color to fill the background of the thumb when the scrollbar is in the corresponding state.

ThumbBorderWidthDefault

ThumbBorderWidthActive

ThumbBorderWidthDisabled

These properties determine the thickness of the border surrounding the thumb when the scrollbar is in the corresponding state.

ThumbBorderColorDefault

ThumbBorderColorActive

ThumbBorderColorDisabled

These properties determine the color to stroke the border surrounding the thumb when the scrollbar is in the corresponding state. To see the border ensure that the properties from the list above configure the border thickness greater than 0.

The following figure demonstrates the effect of diverse property combinations. The gray thin borders indicate the areas of the resulting Vertical Scrollbar. For demonstration purpose the thumb views are configured to appear with rounded corners:

Please note, if the thumb is configured to fill the background and stroke border around it, the border will always appear in front of the filled background area as demonstrated in the figure above.

Configure the shadow of the Scrollbar's thumb (as scalable vector graphic)

Starting with version 13, the Vertical Scrollbar enhances its visual element Thumb by a rectangle, border and shadow views. Those new views display the thumb using scalable vector graphic so that the Vertical Scrollbar is not restricted anymore to use bitmap resources only. As described in the section above the shape of the new thumb views can be configured for each widget state individually. Using the following properties you configure the shadow parameters of the thumb:

Property

Description

ThumbShadowColorDefault

ThumbShadowColorActive

ThumbShadowColorDisabled

These properties determine the color of the shadow behind the thumb when the scrollbar is in the corresponding state.

ThumbShadowBlurRadiusDefault

ThumbShadowBlurRadiusActive

ThumbShadowBlurRadiusDisabled

These properties determine the blur radius of the shadow behind the thumb when the scrollbar is in the corresponding state. The greater the value the more blurred the resulting shadow.

ThumbShadowOffsetDefault

ThumbShadowOffsetActive

ThumbShadowOffsetDisabled

These properties determine optional displacement of the shadow behind the thumb when the scrollbar is in the corresponding state.

The following figure demonstrates the effect of diverse property combinations. The gray thin borders indicate the areas of the resulting Vertical Scrollbar. For demonstration purpose the thumb is configured to appear with rounded corners:

Please note, concerning the stacking order, the shadow always appears in the background of the thumb, just behind its filled rectangle view and/or the border view. Furthermore, if the thumb's background is transparent or semi-transparent, the shadow shines through the background.

Specify the offset and margins for the scrollbar's thumb

Per default, the thumb can be moved freely across the entire height of the Vertical Scrollbar. If this is not desired, you can specify in the properties ThumbMarginBottom and ThumbMarginTop additional gaps in pixel between the thumb and the respective bottom or top edge of the scrollbar. The following figure demonstrates the effect of these properties (the gray borders indicate the areas of the respective scrollbar):

Unless it was explicitly configured, the thumb appears horizontally centered within the Scrollbar and arranged vertically at position corresponding to the scroll position of the visible area (view area) within the entire scrollable content. By using the properties ThumbOffsetDefault, ThumbOffsetActive and ThumbOffsetDisabled an additional displacement for the thumb can be configured. The resulting thumb position can thus depend on the current state of the widget. For example, in the Active state the Thumb views may appear slightly shifted resulting in the visual effect as if the thumb were pressed:

Configure the size behavior of the scrollbar's thumb

Per default, the scrollbar automatically adapts the height of the thumb to correspond to the actual ratio between the specified view and content areas. In this manner, the user can estimate easily how large is the actually visible part of the content in relation to its entire size. If this behavior is not desired, you can initialize the property ThumbSizeFixed with the value true. Now, the height of the thumb does not change anymore. The thumb appears with the smallest possible, fixed size.

In case of the thumb being configured to display an image (using properties described above) the minimal thumb height corresponds to the 2/3 of the original height of the used bitmap - means the upper and lower edges of the bitmap without its interior area. In case of the thumb being composed of a filled rectangle, border and shadow views the minimal size is determined explicitly by the properties ThumbMinHeightDefault, ThumbMinHeightDisabled and ThumbMinHeightActive whereby this minimal size is additionally limited by the corner radius specified for the thumb. That means the thumb is at least twice as tall as the specified corner radius.

Configure how the scrollbar should react on touch events

Depending on the configuration of the Vertical Scrollbar, the scrollbar will handle touch events in different ways. Generally, the scrollbar reacts on touch events when the user touches inside the area of the thumb image. Thereupon, when the user drags the finger, the thumb will follow. If the user touches outside the thumb, the scrollbar simply ignores the events and nothing happens.

If the scrollbar is configured to hide itself automatically after a short delay, the handling of touch events changes. Now, the user can touch elsewhere within the entire area of the scrollbar. This causes the scrollbar to appear again permitting the user to simply touch and drag on the thumb. After finalizing the interaction, the scrollbar disappears again automatically and remains invisible until the user has touched it again.

The scrollbars are per default configured to handle touch events. By initializing the property Touchable with the value false you can suppress this behavior. Now the scrollbar acts as a pure passive widget intended to show to the user the actual scroll position. Interacting with such configured scrollbar is not possible. Even if the scrollbar is configured to automatically disappear after a short delay, the scrollbar will not appear again when the user tries to touch it.

Configure whether the scrollbar should automatically disappear

Per default, the Vertical Scrollbar widgets are visible whole the time. This is even the case if the affected scrollbar is actually not needed because of the associated content being empty or already entirely visible within the respective view area. If this behavior is not desired you can initialize the property HideIfNotNeeded with the value true. Thereupon the affected scrollbars will automatically disappear if the size of the specified content area is less than or equal to the size of the view area. As soon as the content area becomes larger than the view area, the scrollbar appears automatically again.

With the further property AutoHideDelay you can configure the scrollbar to automatically disappear after its state remained unchanged for a predetermined period expressed in milliseconds. For example, initializing the property AutoHideDelay with the value 500 will instruct the scrollbar to disappear 500 ms after its last state alternation. Every time the scrollbar's properties Position, ContentArea or ViewArea change, the scrollbar appears again and the user can notice the alternation. Similarly, the scrollbar reappears automatically when the user touches inside its area. If the user stops to interact with the scrollbar and the scrollbar's state remains unchanged for 500 ms, the scrollbar disappears again.

The hiding and showing of the scrollbar can additionally be configured by using the properties FadeOutDuration and FadeInDuration. As their names imply, the properties permit you to specify the duration in milliseconds for animation to hide (fade-out) and show (fade-in) the scrollbar. The animation affects the opacity of the scrollbar. For example, initializing the property FadeOutDuration with the value 150 will instruct the scrollbar to fade-out it smoothly within 150 ms instead of simply hiding it. If you don't want the fade-in/out animations, leave the properties FadeInDuration and FadeOutDuration initialized with 0.

Configure the Z-order of views belonging to the Vertical Scrollbar

Up to version 12 inclusive the Z-order of visual elements belonging to the Vertical Scrollbar (the order in which the views are displayed one above the other) was fixed predetermined. The Track visual element, for example, was displayed always in the background of the widget while the Thumb view in the foreground. Starting with the version 13, the Z-order can be modified. For this purpose you specify for each visual element its stacking priority value as integer number. As consequence, visual elements with higher stacking priority will overlap visual elements with lower stacking priority. To configure the stacking priority use following properties:

Property

Affected visual element

Default value

TrackStackingPriority

Views belonging to the Track visual element.

1

ThumbStackingPriority

Views belonging to the Thumb visual element.

2

Configure the scrollbar's snap animation effect

The Vertical Scrollbar can automatically snap at predetermined positions. Accordingly, after the user has touched, dragged and released again the scrollbar's thumb, the scrollbar calculates the next appropriate snap position and adjusts its Position property respectively. Per default, this adjustment is performed instantly - just after the user has released the thumb, the thumb jumps to the estimated snap position.

By using the property SnapDuration you can configure the scrollbars to perform this adjustment with an animation. In such case, the thumb slides smoothly with the FastIn_EasyOut timing to the snap position instead of jumping to it. The property SnapDuration has to be initialized with a value expressed in milliseconds how long the animation should take. If you don't want the animation effect, leave the property SnapDuration initialized with 0.

Configure the Vertical Scrollbar state transition animation

During its life time, the Vertical Scrollbar remains always in one of its three possible states. While the user interacts with the widget, touches it for example, the scrollbar switches between the states fourth and back. Those state transitions occur usually abruptly.

By using the property StateTransitionDuration you can configure the widget to perform all state transitions with an animation. During such animation all colors, size or position values related to the preceding and the current states are interpolated automatically. The property StateTransitionDuration determines the duration of this interpolation in milliseconds. The interpolation itself is performed linearly. If the animation is not desired, leave this property configured with the value 0 (zero).

IMPORTANT

Please note, the animations don't affect transitions between bitmaps used by the widget. When the state alternation occurs, the widget displays the bitmaps corresponding to the actual state immediately.

Configure the Vertical Scrollbar size constraints

With the both properties WidgetMinSize and WidgetMaxSize you can configure size constraints for all Vertical Scrollbars using your configuration object. For example, if your Vertical Scrollbars can not become smaller than 50x100 pixel, initialize the property WidgetMinSize with the value <50,100>. Similarly, by initializing the property WidgetMaxSize you determine the maximum size the scrollbars may assume at the runtime. Trying to resize the scrollbars beyond the specified size constraints will be automatically suppressed.

Per default, the properties are initialized with the values <0,0> which means, that no constraints have to be taken in account. If desired, you can also specify constraints only for the height or the width of the scrollbar. For example, if your scrollbars are flexibly resizable in the vertical direction but they should have fixed width of 100 pixel, you initialize the both properties with the value <100,0>.

Enhance the Vertical Scrollbar configuration by additional decoration views

The appearance of the Scrollbar is limited to the visual elements that compose it. To overcome this limitation you can enrich the Scrollbar by additional decoration views. The section Combine the Scrollbar with decoration views explains how to do this in context of a GUI component containing the Scrollbar. That means, the Scrollbar and the additional decoration views are siblings in context of the superior GUI component. The code necessary to update the appearance of the decoration views is implemented directly within the GUI component.

This approach is practicable when there are only few Scrollbars you want to combine with decoration views or the Scrollbars should have different appearance. If you require multiple Scrollbars to be enhanced by the same set of decoration views, the necessary implementation may become less convenient resulting in the same code being repeated for each Scrollbar instance.

To avoid the code repetition you can associate the necessary update implementation directly to the Scrollbar Config object. The update implementation will then affect all Scrollbars which are using this configuration object. The Scrollbar Config object provides for this purpose a property OnUpdate. When you assign a slot method to this property, the slot method will receive postsignals every time the state of any of the associated widgets has changed.

Similarly to how the section Combine the Scrollbar with decoration views explains, you implement within the slot method the code to update the position, size and appearance of the decoration views. The approach using the common implementation has however following peculiarities:

When the slot method is executed, its sender variable refers the instance of the Scrollbar which has triggered the state alternation. Therefore, use sender in the implementation of the slot method to access the affected Scrollbar instance.

Scrollbars can exist within multiple GUI components. For example, one widget may exist within an Alert dialog and other may exist within a Settings dialog. These dialogs are completely different GUI components containing a completely different set of views. The implementation of the slot method should therefore avoid accesses to members existing within the GUI component.

Ideally, the implementation of the slot method operates on the Scrollbar instance only. In particular, it can add to the instance new decoration views, manipulate the views and remove the decoration views again.

The implementation should avoid modifications on views belonging originally to the Scrollbar. It should limit to views it has created by itself. To identify the own decoration views we recommend the usage of the StackingPriority property. When you assign to a decoration view a stacking priority value, the view can be found later by using the method FindViewWithStackingPriority().

The following code demonstrates a typical implementation of the slot method associated to the OnUpdate property of the Vertical Scrollbar Config object. In this example, we enhance the Vertical Scrollbar by a simple Filled Rectangle view. This decoration view is visible during transitions to the ACTIVE state only:

// Using 'sender' variable get the Vertical Scrollbar instance, which has triggered the update var WidgetSet::VerticalScrollbar b = (WidgetSet::VerticalScrollbar)sender; // Within the instance search for our decoration view. Use the 'StackingPriority' value to // identify the view. Here we search for a view with priority == 100. var Core::View v = b.FindViewWithStackingPriority( null, 100, 100, Core::ViewState[]); // Try to type-cast the found view to the expected type (e.g. Rectangle). var Views::Rectangle r = (Views::Rectangle)v; // Show a new or update an already existing decoration view. In this example, the decoration // view should be visible during the transition to the 'ACTIVE' state only. if (( b.GetTransitionEndState() == WidgetSet::CommonState.Active ) && ( b.GetTransitionStartState() != b.GetTransitionEndState())) { var rect a = b.Bounds.orect; var rect q = rect( 0, 0, math_mix( a.w / 2, a.w, b.GetTransitionProgress()), a.h ); // The decoration view is not yet available. Create a new instance and add it to the Vertical // Scrollbar if ( !r ) b.Add( r = new Views::Rectangle, 0 ); // Update the position/size/appearance of the decoration view. r.Bounds = q + a.center - q.center; r.Radius = a.h / 2; r.Color = math_mix( #33333322, #33333300, b.GetTransitionProgress()); // In order to find this view during the next update, identify it with a 'StackingPriority' // value r.StackingPriority = 100; } // The decoration view is not needed anymore. Remove it from the Vertical Scrollbar. else if ( r ) b.Remove( r );

Modify provided default Vertical Scrollbar Config objects

The above sections explained how you create and configure your own Vertical Scrollbar Config objects practically from scratch. This is usual when you have your own GUI design. However, if you prefer to use the configurations provided per default with Embedded Wizard and you want only few settings to be changed, it is more convenient to create a copy of the existing configuration object and adapt the affected property only. Let's assume you want to use the WidgetSet::VerticalScrollbar_Lime_Large configuration but with different margins above and below the thumb. In such case do following:

As explained in the section Duplicate an existing autoobject locate the object WidgetSet::VerticalScrollbar_Lime_Large and copy it to one of your own project units.

Rename the just created copy to not confound it with the original object.

As long as the copied object is selected you can inspect and modify its properties conveniently in the Inspector window. Change its property ThumbMarginBottom and ThumbMarginTop now.

Once you have adapted all properties as expected, you can assign the copied configuration object to every affected Vertical Scrollbar.

CAUTION

Directly modifying the original configuration objects provided with Embedded Wizard is not recommended. The objects are part of the Mosaic framework and Embedded Wizard will prevent you from being able to save any modification made in this framework. Therefore always create and modify copies of the objects.