Button.onSetFocus( ) Event Handler

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

Button.onSetFocus( ) Event Handler

Flash 6

---

callback invoked when the button gains focus

theButton.onSetFocus(oldFocus)

Arguments

oldFocus

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

Description

The onSetFocus( ) event handler is executed when theButton gains focus. A button gains focus when:

• The user navigates to it with the Tab key.

• Selection.setFocus( ) assigns focus programmatically.

When a button's tabEnabled property is false, the button cannot be focused by the user but can be focused programmatically with Selection.setFocus( ). The following code registers a callback function that responds to onSetFocus( ):

// Assign the onSetFocus() callback using a function literal next_btn.onSetFocus = function (oldFocus) {   trace(this + " now has focus. Old focus was " + oldFocus); };

Notice that from the body of the callback, we can refer to next_btn using the this keyword. To stop a callback from handling the onSetFocus( ) event, use the delete operator, as in:

// Make sure to omit the () operator after the function name! delete next_btn.onSetFocus;

To detect attainment of focus via either the keyboard or mouse, use the onRollOver( ) handler, which executes both when the mouse is over theButton and when theButton gains keyboard focus. To capture all focus events centrally, rather than for a single instance, use Selection.onSetFocus( ).

To activate a keyboard-focused button, the user must press the Enter key or spacebar (which has the same effect as clicking the button and causes the button's onRelease( ) handler to execute).

See Also

Button.onKillFocus( ), Button.onRollOver( ), MovieClip.onSetFocus( ), Selection.onSetFocus( ), Selection.setFocus( ), TextField.onSetFocus( ); Chapter 10