HScrollBar and VScrollBar controls

The HScrollBar and VScrollBar controls are part of both the MX and Spark component sets. While you can use the MX controls in your application, Adobe recommends that you use the Spark controls instead.

The VScrollBar (vertical ScrollBar) control and HScrollBar (horizontal ScrollBar) controls let the user control the portion of data that is displayed when there is too much data to fit in the display area.

Although you can use the VScrollBar control and HScrollBar control as stand-alone controls, they are usually combined with other components as part of a custom component to provide scrolling functionality.

Scrollbar controls consists of four parts: two arrow buttons, a track, and a thumb. The position of the thumb and display of the buttons depends on the current state of the control. The width of the control is equal to the largest width of its subcomponents (arrow buttons, track, and thumb). Every subcomponent is centered in the scroll bar.

The ScrollBarBase control uses four parameters to calculate its display state:

  • Minimum range value

  • Maximum range value

  • Current position value; must be within the minimum and maximum range values

  • Viewport size; represents the number of items in the range that can be displayed at once and must be equal to or less than the range

For more information on using these controls with Spark containers, see Scrolling Spark containers.

Creating a scrollbar control

Define a scrollbar control in MXML by using the <s:VScrollBar> tag for a vertical scrollbar or the <s:HScrollBar> tag for a horizontal scrollbar, as the following example shows. Specify an id value if you intend to refer to a component elsewhere in your MXML, either in another tag or in an ActionScript block.

<?xml version="1.0"?>
<!-- controls\bar\SBarSimple.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx">

     <fx:Script>
        <![CDATA[
    
            import mx.events.ScrollEvent;
    
            // Event handler function to display the scroll location.
            private function myScroll():void {
                showPosition.text = "VScrollBar properties summary:" + '\n' +
                    "------------------------------------" + '\n' +
                    "Current scroll position: " + 
                    bar.value  + '\n' +
                    "The maximum scroll position: " + 
                    bar.maximum + '\n' +
                    "The minimum scroll position: " + 
                    bar.minimum;
            }
        ]]>
    </fx:Script> 
    <s:VGroup>
        <s:Label 
            width="100%" 
            text="Click on the ScrollBar control to view its properties."/>
        
    <s:VScrollBar id="bar" 
                   height="100%" 
                   minimum="0" 
                   maximum="{this.width - 20}"
                   stepSize="50" 
                   pageSize="100"  
                   repeatDelay="1000" 
                   repeatInterval="500" 
                   change="myScroll();"/>
        
    <s:TextArea id="showPosition" 
                 height="100%" 
                 width="100%" />
    </s:VGroup>
</s:Application>

The executing SWF file for the previous example is shown below:

Sizing a scrollbar control

The scrollbar control does not display correctly if it is sized smaller than the height of the Up arrow and Down arrow buttons. There is no error checking for this condition. Adobe recommends that you hide the scrollbar control in such a condition. If there is not enough room for the thumb, the thumb is made invisible.

User interaction

Use the mouse to click the various portions of the scrollbar control, which dispatches events to listeners. The object listening to the scrollbar control is responsible for updating the portion of data displayed. The scrollbar control updates itself to represent the new state after the action has taken place.