Recipe 9.11.
Scrolling Text Programmatically
Problem
You want
to scroll text in a text field via ActionScript.
Solution
Use the scrollV, maxScrollV, bottomScrollV, scrollH, and maxScrollH properties of the
text field. Use the mouseWheelEnabled property to enable
scrolling of text by way of the mouse wheel.
Discussion
You can control the scrolling of a text field
with ActionScript and without the aid of a scrollbar. For example,
you may want to scroll the contents of a text field automatically
to display a word or selection within the text. You can
programmatically control a text field's scrolling in both the
vertical and horizontal directions using some built-in properties.
You should use the scrollV, maxScrollV, and
bottomScrollV properties to control vertical scrolling,
and use the scrollH and maxScrollH properties to
control horizontal scrolling.
Every text field has a number of lines, whether
it is 1 or 100. Each of these lines is identified by a number
starting at 1. Some of these lines may be visible, and some may be
beyond the border of the text field. Therefore, to view the lines
that extend beyond the visible portion of the text field you must
scroll to them. Figure 9-1 illustrates
this point. It depicts a text field's display where the solid line
indicates the object's border (the visible area), and the dotted
line surrounds the rest of the text contained within the object but
lying outside the its visible area. To the left of the text field
are line numbers for each line of text. The three
labelsscrollV, bottomScrollV, and
maxScrollVindicate the meaning of the text field
properties of the same names.
The scrollV property is a read-write
property that indicates the top line of the text field's visible
area. In Figure 9-1, the
scrollV property's value is 1. To scroll the contents of a
text field, assign a newline number to the scrollV
property. Setting scrollV to 6, for example, scrolls the
contents of the text field up until line 6 is the top-most line
displayed. The value of scrollV should always be an
integer; Flash cannot scroll to non-integer values:
field.scrollV = 1; // Scroll to the top
field.scrollV += 1; // Scroll to the next line
field.scrollV = 6; // Scroll to line 6
You can scroll to the next page of a text
field's contents by using the bottomScrollV property,
which indicates the bottom-most visible line in the text field.
While you cannot set bottomScrollV, you can use it to
determine the new value to assign to scrollV. In Figure
9-1, bottomScrollV is 13. If scrollV is set
to 6, then bottomScrollV is automatically updated to
18:
// Scroll to the next page with the previous page's bottom line
// at the top
field.scrollV = field.bottomScrollV;
// Scroll to the next complete page without the bottom line from
// previous page
field.scrollV = field.bottomScrollV + 1;
You should use the maxScrollV property
to scroll to the last page of contents within a text field. The
maxScrollV property is also a read-only property. This
property contains the value of the maximum line number that can be
assigned to scrollV. Therefore, the maxScrollV
property changes only when the number of lines in the text field
changes (either through user input or ActionScript assignment). In
Figure 9-1,
maxScrollV is 14. This is because with 26 total lines in
the text field and 13 visible lines, when scrollV is set
to 14, the last visible line is 26 (the last line in the text
field).
Don't try to set scrollV to a value
less than 1 or greater than the value of maxScrollV.
Although this won't cause an error, it won't scroll the text beyond
the contents. Add blank lines to the beginning or end of the text
field's contents to artificially extend its scrolling range:
field.scrollV = field.maxScrollV; // Scroll to the bottom
The vertical scrolling properties are in units
of lines, but the horizontal scrolling properties (scrollH
and maxScrollH) are in units of pixels. Other than that,
scrollH and maxScrollH work more or less in the
same fashion as scrollV and maxScrollV (there is
no property for horizontal scrolling that corresponds to
bottomScrollV). The scrollH property is a
read-write property that allows you to control the value of the
leftmost visible pixel starting with 0. The maxScrollH
property is a read-only property that indicates the pixel value of
the maximum value that can be assigned to scrollH:
field.scrollH = 0; // Scroll to the far left
field.scrollH += 1; // Scroll to the right 1 pixel
field.scrollH = field.maxScrollH; // Scroll to the far right
Figure 9-2 depicts
maxScrollH for a dynamic text field (a field whose
type is set to DYNAMIC). Text shown in gray is
outside the visible area of the text field.
Figure 9-3 depicts
maxScrollH for an input text field (a field whose
type is set to input).
|
Flash automatically adds a buffer space to allow
room for user input. Again, text shown in gray is outside the
visible area of the text field.
|
|
Use the mouseWheelEnabled property to
enable text scrolling using a scrollwheel mouse. The property is
set to false by default; setting the property to
TRue enables mouse wheel scrolling, as shown here:
field.mouseWheelEnabled = true;
|