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.

Figure 9-1. Understanding scrollV, bottomScrollV, and maxScrollV


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-2. The maxScrollH property for a dynamic 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.


Figure 9-3. The maxScrollH property for an input 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;




ActionScript 3. 0 Cookbook
ActionScript 3.0 Cookbook: Solutions for Flash Platform and Flex Application Developers
ISBN: 0596526954
EAN: 2147483647
Year: 2007
Pages: 351

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net