Selection.onSetFocus( ) Listener Event

	ActionScript for Flash MX: The Definitive Guide, 2nd Edition By Colin Moock
	Chapter 18.  ActionScript Language Reference

Selection.onSetFocus( ) Listener Event

Flash 6

---

invoked when a movie's input focus changes

Selection.onSetFocus(oldFocus, newFocus)

Arguments

oldFocus

The Button, MovieClip, or TextField object that previously had focus, or null if no object was previously focused.

newFocus

The Button, MovieClip, or TextField object that now has focus, or null if no object is currently focused.

Description

The onSetFocus( ) event is triggered whenever input focus in a movie changes for example, when the user presses the Tab key to navigate from a form field to the form's Submit button. We can use onSetFocus( ) to manage input focus from a central location. To handle focus for individual objects, we can alternatively use the Button, MovieClip, or TextField class's onSetFocus( ) and onKillFocus( ) handlers, which are triggered only when focus is given to or removed from a particular instance.

To respond to an onSetFocus( ) event, we must first assign a callback function to the onSetFocus property of some object and then register that object as a listener. The onSetFocus( ) callback should accept the oldFocus and newFocus parameters, as follows:

// Create a generic object selListener = new Object();     // Assign a callback function to the object's onSetFocus property selListener.onSetFocus = function (oldFocus, newFocus) {   trace("Focus changed from " + oldFocus + " to " + newFocus); }     // Register the listener with the Selection object Selection.addListener(selListener);

Any number of listener objects of any class can respond to the onSetFocus( ) event. To stop a listener from handling the onSetFocus( ) event, use removeListener( ), as in:

Selection.removeListener(selListener);

Any TextField, MovieClip, or Button object can receive and lose focus when:

• The user navigates to or from it with the Tab key.

• The Selection.setFocus( ) assigns focus to or from it programmatically.

In addition, a text field object can gain or lose focus when the user clicks in or out of it with the mouse. However, the tabEnabled property of Button, MovieClip, and TextField and the selectable property of TextField all affect input focus. For a detailed description of how and when buttons, movie clips, and text fields can be focused, see each class's onSetFocus( ) entry.

Usage

The Tab key does not work reliably in Test Movie mode unless Control Disable Keyboard Shortcuts is enabled. Be sure to test keyboard behavior in the Standalone Player, if applicable, and in the Flash Player for all targeted web browsers.

See Also

Button.enabled, Button.onSetFocus( ), Button.tabEnabled, MovieClip.onSetFocus( ), MovieClip.selectable, MovieClip.tabEnabled, Selection.addListener( ), Selection.removeListener( ), Selection.setFocus( ), TextField.onSetFocus( ), TextField.tabEnabled