Manipulating Text with the Selection Class

The last text feature that we discuss in this chapter is the Selection class. The Selection class is similar to the Mouse class — you don't create instances of the Selection class as there can only be one active highlighted item at any given time.

Several object classes can use the Selection class, including TextField objects. The Selection class can use a string reference to the text field's variable (Var) name or its instance name to perform its methods. We discuss the methods of the Selection class in the following sections.

Note 

In Flash 4 movies, there is no way of checking which text field was active. You can turn off a focus rectangle for Flash Player 4 text fields and Button instances, but you can't control tab order or automatically set a text field to active.

getBeginIndex()

This method detects and returns the starting position of a highlighted selection in a text field. The method returns -1 if there is no active text field and/or there is no selection inside the text field. As with the Array object, selection indexes start position values at 0. You do not need to specify a target path for this method — only one text field can have a selection at any given point. Therefore, as a variable nIdx, the getBeginIndex() method would look like:

 this.onMouseMove = function():Void { var nIdx:Number = Selection.getBeginIndex(); trace("nIdx: " + nIdx); }; 

In the Output panel, the trace() action would reveal nIdx = -1 until you made a selection within a text field in the movie, as shown in Figure 30-15.

Figure 30-15: A text field with a starting selection index of 3

On the CD-ROM 

In the ch30/selection folder of this book's CD-ROM, review the getBeginIndex_trace.fla file to see how the getBeginIndex() method returns values for a text field. Each of the following sections also has a Flash document to demonstrate its respective method.

getEndIndex()

Similar to the getBeginIndex() method, this method returns a number indicating the index position at the end of a highlighted selection in a text field, as shown in Figure 30-16. If there is no active selection, then a value of -1 is returned.

Figure 30-16: A text field with a starting selection index of 5 and an ending index of 9

getCaretIndex()

This method of the Selection class returns the current cursor position (as an index value) within an active text field, as shown in Figure 30-17. As with the two previous methods, if you use the getCaretIndex() method when there is no active cursor in a text field, it returns a -1.

Figure 30-17: A text field with a caret index of 5

getFocus()

This method returns the current active text field's Var or instance name as an absolute path; that is, if you have selected or inserted the cursor position inside a text field instance named tOutput on the Main Timeline, then Selection.getFocus() returns _level0.tOutput. If there is no active text field, then this method returns null.

Note 

If a text field does not have an instance name but does have a Var name, the Var name and path will be returned. A text field's instance name, when available, will be returned by this method.

setFocus()

Perhaps the best enhancement to controlled text field activity is the setFocus() method. This method enables you to make a text field active automatically — the user doesn't need to click the mouse cursor inside the text field to start typing. To use this method, simply indicate the setFocus() method of the Selection class and the path to the text field as its argument:

 Selection.setFocus(tInput); 

This code sets the current focus to the tInput text field. If any text exists in the text field, it will be highlighted as a selection. You can only use string data types as the setFocus() argument for Flash Player 5 compatability, but you can use instance names for Flash Player 6 or higher.

setSelection()

Another method available for the Selection class is setSelection(). This method enables you to make a specific selection within an active text field. The method takes two arguments: a start index and an end index. Use the same index numbering as getBeginIndex() and getEndIndex(). Note that this method will not work unless a text field is already active. The following code creates a selection span from index 5 to 9 of the tInput text field:

 Selection.setFocus(tInput); Selection.setSelection(5,9); 

Caution 

You may find that the setSelection() method does not show any results in the Test Movie environment. Always test your Flash movies in a Web browser or the stand-alone player to analyze your results.

Web Resource 

We'd like to know what you think about this chapter. Visit www.flashsupport.com/feedback to send us your comments.