Recipe 8.13 Scrolling Text with the ScrollBar Component

8.13.1 Problem

You want to create a scrolling text field with a scrollbar.

8.13.2 Solution

Use the Flash UI Components ScrollBar component.

8.13.3 Discussion

Using the ScrollBar component, you can easily add both vertical and horizontal scrolling capabilities to a text field. If the text field is created during authoring, you can simply drag a scrollbar instance from the Components panel onto the text field itself. The ScrollBar component will automatically snap (if View Snap to Objects is enabled) to the side on which it is dropped (top, bottom, left, or right) and will automatically size itself to match the text field object. Additionally, the scrollbar instance will automatically set its scroll target to be the text field onto which it was dropped.

You can also add a scrollbar to a dynamically created text field, or add the scrollbar dynamically for other reasons (such as when a text field is resized or its contents change). To make the process fully dynamic, add the scrollbar using MovieClip.attachMovie( ) (see Recipe 7.19). To accomplish this, you must first make sure that the ScrollBar component is included in the movie's Library by dragging an instance of it from the Components panel to the Stage. This action will automatically link the ScrollBar component for export with the identifier FScrollBarSymbol. With the symbol in the Library, you can attach the component using ActionScript, as follows:

_root.attachMovie("FScrollBarSymbol", "myScrollBar_sb", 2);

To specify the text field to control, specify it as the target parameter for the ScrollBar component's setScrollTarget( ) method:

myScrollBar_sb.setScrollTarget(myTextField);

While this is all that is technically required for a scrollbar to control the scrolling of a text field, there are generally additional considerations. For example, you usually will want to position the scrollbar adjacent to the text field. Likewise, you typically will want the scrollbar's dimensions to match the width or height of the text field it controls (depending on whether it is a horizontal or vertical scrollbar).

To align a vertical scrollbar instance so that it is flush with the top of the text field it controls, set its _y property to match the text field's _y property. To align the same scrollbar instance so that it touches the right side of the text field, offset its _x property by the text field's width value. For example:

myScrollBar_sb._x = myTextField._x + myTextField._width;
myScrollBar_sb._y = myTextField._y;

To set the size of a scrollbar instance, use the setSize( ) method, which accepts the size (the height) of the instance in pixels. To match the scrollbar length to the text field, pass the text field's _height property to the setSize( ) method:

myScrollBar_sb.setSize(myTextField._height);

If you want the scrollbar to control the horizontal scrolling of a text field, use the setHorizontal( ) method, passing it the value true. (This also orients the scrollbar horizontally.)

myScrollBar_sb.setHorizontal(true);

When a scrollbar instance is horizontal, setSize( ) sets its width instead of its height.

8.13.4 See Also

Recipe 8.14