Pixel-Based Text Scrolling with Movie Clips

Flash Player 8 introduces a new property for the MovieClip class: scrollRect. This property controls the viewable area of a MovieClip instance on the Stage and can only be set with ActionScript (that is, you won't find a scrollRect setting in the Property inspector for Movie Clip symbols). You can think of the scrollRect property as a built-in mask that selectively shows content within the MovieClip object.

Tip 

You need to use the new Rectangle class in Flash Player 8 to create the rectangle shape that will be used by a MovieClip object's scrollRect property. You learn how to create a new Rectangle object in this section's example.

You can use the scrollRect property to show and hide any type of content within a MovieClip object. In this section, you learn how to use the scrollRect property to create a scrollable area with text content within a MovieClip object. You learn how to control the _y property of a TextField instance with the UIScrollBar component. Typically, the UIScrollBar component is used to update the scroll property of a TextField instance, not the TextField instance's _y property.

On the CD-ROM 

To get a sense of these two different types of scrolling, open the scroll_comparison.html document in the ch30/scroll folder of this book's CD-ROM. This page shows a Flash movie comparing text scrolling with the scroll property versus the _y property of a TextField instance.

In the following steps, you learn how to build a Flash movie that pixel scrolls a TextField instance with the UIScrollBar component.

1. Make a copy of the fp8_pixelscroll_starter.fla file from the ch30/scroll folder of this book's CD-ROM. Open the file in Flash 8, and resave it as fp8_pixelscroll_100.fla. This starter file has a TextField instance named tDisplay on the Stage. This field is set to embed the same range of Verdana font characters just like our previous examples in this chapter, and already contains the text from the Gettysburg Address.

2. Nest the tDisplay instance into a new Movie Clip symbol. Select the tDisplay instance on the Stage, and choose Modify ð Convert to Symbol. Name the symbol holderClip, and set the registration to the top-left corner, as shown in Figure 30-12. Click OK to finish creating the symbol.

3. Select the new holderClip symbol instance on the Main Timeline (that is, Scene 1) Stage. In the Property inspector, name this instance mcHolder. Also, rename the tDisplay layer to mcHolder.

   Now you're ready to create a Rectangle object to use as the scrollRect value for the mcHolder instance. As you can see, the tDisplay field nested within the mcHolder instance continues off stage. The scrollRect for the mcHolder will be 300 x 300 pixels.

4. Create a new layer named actions. Select frame 1 of the actions layer, and open the Actions panel (F9, or Option+F9). Add the code shown in Listing 30-6.

   Listing 30-6: Creating a Rectangle Object

    import flash.geom.Rectangle; var rWin:Rectangle; var mcHolder:MovieClip; var tDisplay:TextField; function init():Void {    var nWidth:Number = 300;    var nHeight:Number = 300;    rWin = new Rectangle(0, 0, nWidth+5, nHeight);    mcHolder.scrollRect = rWin;    tDisplay = mcHolder.tDisplay; } init(); 

   The first line imports the new Rectangle class, which is part of the flash.geom class. The next three lines of code create variables for the Rectangle, MovieClip, and TextField instances that will be used within the init() function.

   The init() function creates the Rectangle instance and uses the instance for the scrollRect property of the mcHolder instance. The nWidth and nHeight variables establish the width and height, respectively, of the viewable area of the MovieClip instance. The Rectangle constructor uses four arguments: the starting X position, the starting Y position, the width, and the height of the rectangle shape. Once the shape is created, it is set to be the value of the scrollRect property of the mcHolder instance. The tDisplay variable is also set to equal the tDisplay instance inside of the mcHolder instance, to create a shorter reference name for the TextField instance.

   After the init() function is defined, the function is invoked so that the Rectangle instance is bound to the mcHolder instance when the Flash movie starts.

   Note 

   Due to rendering oddities of the new FlashType engine, you buffer the width of the Rectangle instance (rWin) by 5 pixels. This buffer will make sure that any text bleeding outside of the TextField instance will still be viewable.

5. Save the document, and test it (Ctrl+Enter or z+Enter). You should see that the text is now masked by the new Rectangle instance, as shown in Figure 30-13.

6. Once the field is masked, you can add a scroll bar to enable the user to view the entirety of the text. Open the Components panel (Ctrl+F7 or z+F7), expand the User Interface grouping, and drag a copy of the UIScrollBar instance to the document's Stage. Once you've added the component to the Stage, select the instance and delete it. You simply need a copy of the UIScrollBar component in the movie's Library panel. In the next step, you attach the component to the movie's Stage via ActionScript.

7. Select frame 1 of the actions layer, and open the Actions panel. Add the bold code shown in Listing 30-7 to the existing script. Note that the

    import flash.geom.Rectangle; import mx.utils.Delegate; import mx.controls.UIScrollBar; var rWin:Rectangle; var csb:UIScrollBar; var mcHolder:MovieClip; var tDisplay:TextField; function init():Void {    var nWidth:Number = 300;    var nHeight:Number = 300;    rWin = new Rectangle(0, 0, nWidth+5, nHeight);    mcHolder.scrollRect = rWin;    tDisplay = mcHolder.tDisplay;    csb = createClassObject(UIScrollBar, "csb", 1, {_x: mcHolder._x +        mcHolder._width + 5, _y: mcHolder._y});    csb.setScrollProperties(nHeight, 0, tDisplay._height - nHeight);    csb.setSize(csb.width, nHeight);    csb.addEventListener("scroll", Delegate.create(this, this.onScroll)); } function onScroll(oEvent:Object):Void {    tDisplay._y = -csb.scrollPosition; } init(); 

   The init() function adds four new lines of code, which create a new instance of the UIScrollBar component. The new instance is named csb and is positioned to the right of the mcHolder instance. More importantly, the minimum and maximum values that the scroll bar should return for its scrollPosition property are defined. The height of the Rectangle object is subtracted from the total height of the tDisplay field, since you don't want to scroll the TextField instance off the Stage. The size of the UIScrollBar instance is also sized to the height of the Rectangle instance. The last line of code within the init() function adds the new handler, onScroll, as a listener to the "scroll" event broadcasted from the UIScrollBar component.

   The last block of code defines the onScroll() function, which is invoked whenever the user interacts with the UIScrollBar instance, csb. The scrollPosition property returned by the csb is used to set the _y position of the tDisplay field. Note that the value is inverted, so that the top of the TextField instance moves up. (You can come back to this code and remove the - sign to see what happens if it's not there.)

8. Save the document, and test it (Ctrl+Enter or z+Enter). You should now see an instance of the UIScrollBar component attached to the right of the mcHolder instance displaying the text, as shown in Figure 30-14. If you click and drag the scroll box, you can smoothly scroll the text.

   On the CD-ROM 

   You can find the completed file, fp8_pixelscroll_100.fla, in the ch30/scroll folder of this book's CD-ROM. You can see a more advanced example, fp8_pixel scroll_101.fla, in the same location. That version dynamically creates the MovieClip instance (mcHolder) and the tDisplay instance, and populates the field with text from the gettysburg.as file.

Figure 30-12: The Convert to Symbol dialog box

Figure 30-13: The scrollRect property masks the lower half of the TextField instance.

Figure 30-14: The scroll bar attached to the right of the text display