Table of Contents

Selection.methodName()

Methods

addListener( )

Register an object to receive onSetFocus( ) event notices.

getBeginIndex( )

Retrieve the index of the first selected character in the text field with keyboard focus.

getCaretIndex( )

Retrieve the index of the insertion point in a text field.

getEndIndex( )

Retrieve the index of the character following the selection in a text field.

getFocus( )

Identify the text field, button, or movie clip that is currently focused.

removeListener( )

Cancel event notices for the specified listener.

setFocus( )

Assign input focus to a text field, button, or movie clip object.

setSelection( )

Select characters in the currently focused text field.

Listener Events

onSetFocus( )

Occurs when input focus changes.

Description

We use the Selection object to control user interaction with text fields, to capture portions of text fields, and to detect input focus for buttons, movie clips, and text fields. Selection is a predefined object, not a class, so its methods are accessed directly, as in:

Selection.setFocus(input_txt);  // Focuses the input_txt text field

Character-manipulation methods of the Selection object always refer implicitly to the text field with keyboard focus, so we need only one Selection object. This is why, for example, Selection.getBeginIndex( ) is accessed through the Selection object directly, not through an instance of the TextField class.

The methods of a Selection object can position the insertion point in the focused text field and select or retrieve a text field's content. These abilities add subtle but important behavior to user-input systems. For example, in a user-login screen, we can prompt a user to enter his name by placing the text insertion point in a name-entry text field. Or, we can highlight an error in a form by selecting the problematic text. Such control is also central to word processing-style applications.

Positions of the characters in a text field are referred to with zero-relative indexes, in which the first character is index 0, the second is index 1, and so on. Character indexing is described in detail under Section 4.6.4, in Chapter 4.

In Flash 6 the TextField.replaceSel( ) method can be used to simulate cut, copy, and paste operations for a text field. Furthermore, the cut, copy, and paste shortcut keys (Ctrl-X, Ctrl-C, and Ctrl-V on Windows, or Cmd-X, Cmd-C, and Cmd-V on the Macintosh) are operational in Flash Player 6. The secondary mouse button (right-click on Windows, Ctrl-click on Macintosh) provides access to the cut, copy, and paste commands in Flash Player 5.

The Selection object can also control and report on keyboard focus (a.k.a. input focus) in a movie. When an object has keyboard focus, it accepts all keystrokes from the keyboard. For example, when a text field contains the text insertion point, it has keyboard focus, and keys pressed display as characters in the field. When a button has keyboard focus, it can be activated by pressing either the Enter key or spacebar. When a movie clip has keyboard focus, it can respond to keystrokes via its onKeyDown( )/onKeyUp( ) event handlers. Buttons and movie clips are given keyboard focus either by the user via the Tab key (not by a mouseclick!) or programmatically via Selection.setFocus( ). By default, a focused button or movie clip is surrounded by a yellow rectangle (see the global _focusrect property). Changes in focus can be captured globally by the Selection.onSetFocus( ) event or individually by the onSetFocus( )/onKillFocus( ) event handlers for Button, MovieClip, and TextField. The currently focused item can always be determined with Selection.getFocus( ).

Usage

Clicking a form's Submit button automatically removes focus from any previously focused text field. To capture a text selection before focus is lost, use the rollover handler attached to the Submit button, because rollover events occur before the button is pressed. For example:

submit_btn.onRollOver = function () {
  // Note which field is focused before the button is pressed.
  focusedField = Selection.getFocus();
   
  // Note which characters are selected.
  beginIdx = focusedField.getBeginIndex();
  endIdx =   focusedField.getEndIndex();
}

By storing the focused field in a variable, we can then operate on the selected characters in that field or return focus to the field after, say, checking the user's input for errors.

See Also

The Button class, _focusrect, the MovieClip class, the TextField class

Table of Contents