Recipe 8.10. Creating Scrolling Text

Problem

You want to create scrolling text.

Solution

Use a text area component.

Alternatively, create a multiline text field and button or movie clips for scrolling up and down. Then add some ActionScript to update the text field's scroll property when the button or movie clips are pressed.

Discussion

In the event that you want to use a standard scrollbar to scroll text horizontally and/or vertically, you can use the text area component with its built-in scrollbars. You can add a text area to the stage simply by dragging an instance from the Components panel to the stage. If you are planning to use the text area with ActionScript at all, make sure to give it an instance name (exp 3pod.com) using the Property inspector. If you want to add text to the text area you can follow the instructions provided in Recipe 8.9.

With a text area, the scrollbars (vertical and horizontal) appear only when necessary. However, with some simple ActionScript you can specify whether and when the scrollbars should appear. Each text area component instance has a property named vScrollPolicy and a property named hScrollPolicy. The vScrollPolicy property determines the behavior of the vertical scrollbar, and the hScrollPolicy property determines the behavior of the horizontal scrollbar. The properties can accept values of on, off,or auto. The default value is auto, which means that the scrollbar appears only when necessary. A value of on means that the scrollbar is visible even when unnecessary; a value of off means that the scrollbar does not appear, even when necessary. The following code example sets the vertical scrollbar to be on and the horizontal scrollbar to be off for a text area instance named ctaOutput:

	ctaOutput.vScrollPolicy = "on";
	ctaOutput.hScrollPolicy = "off";

There are times when you don't want to use a text area component. For example, due to file size issues, you may not have the option of including the 40KB text area component in your project. Another reason you may opt not to use the component is that you might want to create a custom scrolling mechanism. Whatever your reasoning, you can add a small amount of ActionScript code in order to scroll a text field.

Dynamic and input text fields have an ActionScript property named scroll. Each text field line is assigned an index by Flash, and the scroll property contains the index of the top visible line in a given text field. For example, if the text field is scrolled all the way to the top, the scroll property has a value of 1, because the first line is the top visible line. Not only does the scroll property report the index of the top visible line, but it also allows you to set that value. For example, regardless of how a text field has been scrolled, you can scroll it to the top by assigning a value of 1 to the scroll property of that instance.

	tField.scroll = 1; // Scroll a text field named tField to the top.

If you want to scroll a text field down one line, use the increment operator (++) with the instance's scroll property. You can scroll a text field up one line by using the decrement operator (--) with the instance's scroll property. Typically, you'll want to scroll a text field up and/or down using a movie clip or button instance in conjunction with an onPress( ) or onRelease( ) event handler method (see Chapter 9 for more details on handling button events with event handler methods). The following example scrolls a text field named tField to the next line when the user clicks on a movie clip with an instance name (exp 3pod.com) of mScrollDown, and scrolls the text up one line when the user clicks on a movie clip with an instance name (exp 3pod.com) of mScrollUp:

	mScrollDown.onPress = function():Void {
	  tField.scroll++;
	};
	mScrollUp.onPress = function():Void {
	  tField.scroll--;
	};

The preceding code allows the user to scroll the text up and down one line at a time. Each time the user wants to scroll one more line, he has to click the appropriate movie clip or button again. That can require a lot of clicks to scroll any substantial amount. If you want to add continuous scrolling functionality, you can do so by using the setInterval( ) command to tell Flash to repeatedly call a function that scrolls the text field. Call setInterval( ) within an onPress( ) event handler method, and then clear the interval within an onRelease( ) event handler method. The following code is an example:

	// Define a custom function that Flash can call on an interval. The function accepts
two
	// parameters  the text field to scroll and the amount by which to scroll the text
field.
	// A positive number for the nScrollAmount parameter will cause the text field to
scroll
	// downward, while a negative number will cause the text field to scroll upward.
function scrollField(tField:TextField, nScrollAmount:Number):Void {
	   // Add the scroll amount to the text field's scroll property.
tField.scroll += nScrollAmount;
	   // Refresh the stage so that the animation is as smooth as possible.
updateAfterEvent( );
	}
	// Declare a variable into which you'll store the interval ID. That way you can clear
the
	// interval later on, so as to stop the  
scrolling.
var nInterval:Number;
	// Assign an onPress( ) event handler method to the button or movie clip that the
user can click
	// to scroll the text upward. In this example the movie clip instance name (exp 3pod.com) is
mScrollUp.
	mScrollUp.onPress = function( ):Void {
	  // Clear the interval just to make sure that you don't accidentally get multiple
intervals
	  // calling the same function running simultaneously.
clearInterval(nInterval);
	  // Set an interval so that Flash will call the scrollField( ) function every 50
milliseconds.
	  // If you want the scrolling to occur faster, decrease the second parameter. If you
want a
	  // slower scroll, increase the value. Also, pass along the reference to the text
field you
	  // want to scroll. In this example the text field is named tField. And you should
also
	  // specify a value of -1 for the fourth parameter so that the text field scrolls
upward.
	  nInterval = setInterval(scrollField, 50, tField, -1);
	};

	// Assign an onRelease( ) event handler method to the same button or movie clip. In
this example
	// that movie clip is mScrollUp. When the user releases the click on the button
simply clear the
	// interval. That causes Flash to stop calling the scrollField( ) function.
mScrollUp.onRelease = function( ):Void {
	  clearInterval(nInterval);
	};
	// Make sure that the interval is stopped if the user releases the mouse while no
longer over
	// the movie clip.
	mScrollUp.onReleaseOutside = mScrollUp.onRelease;
	// Then assign onPress( ) and onRelease( ) event handler methods to the movie clip or
button that
	// should cause the text to scroll downward. In this example the movie clip instance
is named
	// mScrollDown. The code for the onPress( ) and onRelease( ) event handler methods on
the
	// downward scroll movie clip or button is almost the same as the code for the upward
scroll movie
	// clip or button. The only difference is that the fourth parameter passed to
setInterval( )
	// should be 1 instead of -1 since you want the text to scroll downward.
mScrollDown.onPress = function( ):Void {
	  clearInterval(nInterval);
	  nInterval = setInterval(scrollField, 50, tField, 1);
	};
	mScrollDown.onRelease = function( ):Void {
	  clearInterval(nInterval);
	};
	mScrollDown.onReleaseOutside = mScrollDown.onRelease;
	// The following code populate the text field with text so that you can test the
 
scrolling
	// functionality.
	for(var i:Number = 0; i < 100; i++) {
	  tField.text += i + newline;
	}

The scroll property handles scrolling in the vertical direction. You can also scroll in the horizontal direction using the hscroll property if the text field has word wrapping turned off. The scroll property value is given in line numbers; the hscroll property is given in pixels. The minimum value for hscroll is 0, and that value indicates that the text is scrolled all the way to the right. If the text extends beyond the right boundary of the text field, you can increment the hscroll property to move the text within the field to the left.