ActionScript: The Definitive Guide

Name

Selection.setFocus( ) Method — set keyboard focus for a specific text field

Availability

Flash 5

Synopsis

Selection.setFocus(variableName)

Arguments

variableName

A string representing the path (e.g., "_root.myTextField" or "userName") to the text field variable that is to receive focus.

Returns

A Boolean indicating whether the focus attempt succeeded (true) or failed (false). A focus attempt fails only if the variable specified by variableName is not found or if it is not a text field variable.

Description

The setFocus( ) method sets the keyboard focus for a text field. It places the cursor in that text field, normally in order to draw attention to the field or to allow the user to enter data. The setFocus( ) method can also provide a handy means of identifying erroneous input to a user. In an online form, for example, a user may mistype an email address. To alert the user to the error, we could set the focus to the email-address text field and ask her to fix the problem. We can also use setFocus( ) to create a custom Tab key order for the fields in a form, as shown in the example that follows.

Usage

Note that setting the focus of a text field automatically selects any content in that field. To set a field’s focus without selecting any characters, use the following code:

// First, focus myField Selection.setFocus("myField"); // Now place the insertion point at the start of myField Selection.setSelection(0, 0); // Or at the end of myField Selection.setSelection(myField.length, myField.length); ...