| Selection.setFocus( ) Method | Flash 5; enhanced in Flash 6 to support buttons and movie clips |
| set input focus to a specific button, movie clip, or text field |
A string indicating the path to the button, movie clip, or text field instance to focus. Because instance references are converted to paths when used in a string context, instanceName can also be an object reference, as in "_level0.listBox_mc" versus _level0.listBox_mc.
A Boolean indicating whether the focus attempt succeeded (true) or failed (false). A focus attempt fails if the instanceName is not found or if it is not a button, text field, or movie clip instance. The setFocus( ) method also returns false if focus is disabled for instanceName, as explained in the following Description.
The setFocus( ) method sets the input focus to the button, movie clip, or text field specified by instanceName.
If instanceName is a button, when focused, its Over frame is displayed, and it is surrounded by a yellow rectangle (unless _focusrect is false). While focused, the button can be activated by pressing the Enter key or spacebar.
If instanceName is a movie clip, when focused, the frame labeled _over is displayed, if such a label exists, and the clip is surrounded by a yellow rectangle (unless _focusrect is false). While focused, the clip receives onKeyDown( ), onKeyUp( ), onMouseDown( ), and onMouseUp( ) event notices.
Take special note:
In Flash 6, moving the mouse over the Stage removes button and movie clip focus, but not text field focus.
Main movie timelines (e.g., _root and _level1) cannot receive keyboard focus.
A movie clip cannot be focused via Selection.setFocus( ) unless its focusEnabled property is true.
A movie clip without button events cannot be focused via the keyboard unless its tabEnabled property is true.
If instanceName is an input text field, the cursor appears in the field when it is focused, allowing characters to be entered into the field. Dynamic and static text fields cannot be focused. However, a user-input text field with its selectable and tabEnabled properties set to false can still be focused with setFocus( ).
Normally, an input text field is focused in order to draw attention to it or to allow the user to enter data. The setFocus( ) method can also provide a handy means of drawing a user's attention to erroneous input. In an online form, for example, a user may mistype an email address. To alert the user to the error, we can set the focus to the email-address text field and ask her to fix the problem. In Flash 5, we can also use setFocus( ) to create a custom Tab key order for the fields in a form, as shown in the following Example. In Flash 6, tab order should be assigned directly via the TextField.tabIndex property.
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 theField
Selection.setFocus("theField_txt");
// Now place the insertion point at the start of theField
Selection.setSelection(0, 0);
// Or at the end of theField
Selection.setSelection(theField.length, theField.length);
|
This example shows how to assign a custom tab order to the fields in a fill-in form. While relevant only in Flash 5, the example shows the powerful control Selection provides over user input. The corresponding sample .fla file can be downloaded from the online Code Depot. For more information on trapping the Tab key, see TextField.tabIndex.
// Custom tab order
// CODE ON THE MOVIE CLIP CONTAINING THE FORM FIELDS
onClipEvent (load) {
// Store the path to this clip in a string. We'll use it
// later when invoking Selection.setFocus( ) .
path = targetPath(this);
// Create an array with the names of our text fields, supplied in the
// desired tab order. The first field listed is the default. In Flash 6,
// these must be instance names, not Flash 5-style variable names.
tabOrder = ["field1", "field3", "field2", "field4"];
}
onClipEvent (keyUp) {
// If the Tab key was pressed...
if (Key.getCode() = = Key.TAB) {
// ...If no field has focus...
if (Selection.getFocus() = = null) {
// ...then set focus to the first field in the array of fields.
Selection.setFocus(path + "." + tabOrder[0]);
} else {
// Otherwise, locate the currently focused field in the array of fields.
i = 0;
focused = Selection.getFocus();
while (i < tabOrder.length) {
// Extract the name of the field variable from the full path
// that's returned by Selection.getFocus( ) .
fieldName = focused.substring(focused.lastIndexOf(".") + 1);
// Check each element of tabOrder for the focused field.
if (tabOrder[i] = = fieldName) {
// Stop when we find a match.
currentFocus = i;
break;
}
i++;
}
// Now that we know where the focused field lies in the tabOrder array,
// set the new focus to either the next field or the previous field,
// depending on whether the Shift key is down.
if (Key.isDown(Key.SHIFT)) {
// Shift key is down, so go to the previous field, unless we're
// already at the beginning, in which case go to the last field.
nextFocus = currentFocus-1 = = -1 ? tabOrder.length-1 : currentFocus-1;
} else {
// Shift key is not down, so go to the next field, unless we're
// already at the end, in which case go to the first field.
nextFocus = currentFocus+1 = = tabOrder.length ? 0 : currentFocus+1;
}
// Finally, assign the new focus.
Selection.setFocus(path + "." + tabOrder[nextFocus]);
}
}
}
// CODE ON BUTTON ON MAIN TIMELINE
on (keyPress "<Tab>") {
// This placeholder code just traps the Tab key in Internet Explorer
var tabCatcher = 0;
}
MovieClip.focusEnabled, Selection.getFocus( ), Selection.setSelection( ), TextField.selectable, TextField.tabEnabled