The Selection class, among its other functionalities, allows you to manage input focus among text fields, movie clips and buttons.
The Scaleform extends the focus functionality of the Selection class. In ActionScript 1.0 it is possible to refer to Selection extension functions directly, as in Selection.captureFocus(). ActionScript 2.0 is less tolerant and it will “complain” about such calls. To quiet the ActionScript 2.0 compiler you should use the alternative access syntax as follows: Selection"captureFocus".
alwaysEnableArrowKeys static property
alwaysEnableArrowKeys : Boolean
Scaleform version: 1.2.34
This static property allows arrow keys to change focus even when the _focusrect property is set to false (applied when the focus is captured). By default, Flash does not allow you to use arrow keys to change focus if the yellow focus rectangle is disabled via _focusrect = false;. To change this behavior, set the alwaysEnableArrowKeys property to true.
Example:
Selection["alwaysEnableArrowKeys"] = true;
alwaysEnableKeyboardPress static property
alwaysEnableKeyboardPress : Boolean
Scaleform version: 3.0.63
This static property allows to fire onPress / onRelease events by pressing SPACE or ENTER keys, even when the _focusrect property is set to false (applied when the focus is captured). By default, Flash does not allow you to press buttons by keyboard if the yellow focus rectangle is disabled via _focusrect = false;. To change this behavior, set the alwaysEnableKeyboardPress property to true.
Example:
Selection["alwaysEnableKeyboardPress"] = true;
captureFocus() static method
public function captureFocus([doCapture:Boolean, controllerIdx:Number]) : void
Scaleform version: 1.2.34
This static method is used to capture or release keyboard focus programmatically.
The captureFocus with the doCapture parameter set to true (or without a parameter at all) captures keyboard focus ,and allows the arrow keys to change focus, which is similar to the first time the Tab key is pressed.
The captureFocus with the doCapture parameter set to false releases keyboard focus, and acts like a mouse move when the focus rectangle is on.
Parameters
doCapture:Boolean – Optional, indicates whether keyboard focus should be captured or released. If this parameter is omitted then captureFocus behaves like this parameter is set to true.
controllerIdx:Number – Optional, indicates which keyboard/controller is used for the capture operation. By default controller 0 is used.
Example:
Selection["captureFocus"](); // same as passing "true" Selection["captureFocus"](false);
disableFocusAutoRelease static property
disableFocusAutoRelease : Boolean
Scaleform version: 1.2.34
This static property is used to control whether a mouse movement releases keyboard focus (the standard behavior in Flash) or not. By default, if focus is captured and the yellow rectangle is displayed (allowing arrow keys to change the focus), the mouse move releases the focus. To prevent this behavior, set this static property to true.
Example:
Selection["disableFocusAutoRelease"] = true;
disableFocusKeys static property
disableFocusKeys : Boolean
Scaleform version: 2.2.58
This static property disables handling of all focus keys (TAB, Shift-TAB and arrow keys), thus, users may implement their own focus keys management.
Example:
Selection["disableFocusKeys"] = true;
See also: moveFocus()
disableFocusRolloverEvent static property
disableFocusRolloverEvent : Boolean
Scaleform version: 2.0.37
This static property is used to disable rollover/out event firing if focus is changed by keys. By default, if focus is changed by pressing arrow keys rollover/rollout events are fired. To prevent this behavior, set this static property to true.
Example:
Selection["disableFocusRolloverEvent "] = true;
modalClip static property
modalClip : MovieClip
Scaleform version: 2.2.58
This static property sets the specified movie clip as a “modal” clip from focus management point of view. This means that focus keys (TAB, Shift-TAB and arrow keys) will move focus rectangle only inside the specified movie clip, i.e., only across “tabable” children of the movie clip.
Example:
Selection["modalClip"] = _root.mc; ... Selection["modalClip"] = undefined;
See also:
disableFocusKeys
moveFocus()
moveFocus() static method
public function moveFocus(keyToSimmulate : String [, startFromMovie:Object, includeFocusEnabledChars : Boolean = false, controllerIdx :Number]) : Object
Scaleform version: 2.2.58
This static method is used to move a focus rectangle by simulating key pressing of one of focus keys: TAB, Shift-TAB or arrow keys. This method with cooperation of disableFocusKeys and modalClip properties may be used for implementing custom focus management.
Parameters
keyToSimulate:String – Name of key to simulate: “up”, “down”, “left”, “right”, “tab”, “shifttab”.
startFromMovie:Object – Optional parameter that specifies a character; moveFocus will use it instead of the currently focused one as a start point. This property might be null or undefined, which means that currently focused character is used as a starting point; this might be useful to specify the third optional parameter.
includeFocusEnabledChars:Boolean – Optional flag that allows moveFocus onto characters with only the focusEnabled property set as well as onto characters with the tabEnabled / tabIndex properties set. If the flag is not specified or set to false then only characters with the tabEnabled / tabIndex properties set will participate in focus movement.
controllerIdx:Number – Index of the controller used for the operation. If not specified, then the default controller (controller 0) is used.
Example:
Selection["moveFocus"]("up");
Selection["moveFocus"]("tab", _root.mc);
Selection["moveFocus"]("tab", _root.mc, true);
Selection["moveFocus"]("tab", null, true);
Returns
Returns newly focused character or undefined if the character cannot be found.
See also:
disableFocusKeys
modalClip
findFocus() static method
public function findFocus(keyToSimmulate : String [, parentMovie:Object, loop : Boolean, startFromMovie:Object, includeFocusEnabledChars : Boolean, controllerIndex : Number]) : Object
Scaleform version: 3.3.84
This static method is used to find the next focus item by simulating key pressing of one of the following keys: TAB, Shift-TAB or arrow keys. This method with conjunction with the disableFocusKeys and setModalClip/getModalClip extensions may be used to implement custom focus management.
Parameters
keyToSimulate:String – Name of key to simulate: “up”, “down”, “left”, “right”, “tab”, “shifttab”.
parentMovie - The movie clip that is used as a modal clip. The focus item search is performed only within this clip’s children. May be null.
loop - Boolean flag to loop focus. For example, if the currently focused item is at the bottom and the key is “down”, then findFocus either returns “null” (if this flag is “false”) or the topmost focusable item (if the flag is “true”).
startFromMovie:Object – Optional parameter that specifies a character that findFocus will use instead of the currently focused one as a start point. This property might be null or undefined, which means that the currently focused character is used as a starting point.
includeFocusEnabledChars:Boolean – Optional flag that allows moveFocus onto characters with only the focusEnabled property set as well as onto characters with the tabEnabled/tabIndex properties set. If the flag is not specified or set to false then only characters with the tabEnabled/tabIndex properties set will participate in focus movement.
controllerIndex - A zero base index of the controller that is manipulating focus. This in conjunction with focus groups can be used to provide multi controller focus support.
Example:
var a = Selection["findFocus"]("up");
Returns
Returns next character to be focused or null if the character cannot be found.
See also:
disableFocusKeys setModalClip getModalClip
setModalClip() static method
public function setModalClip(modalClip : Object, controllerIndex : Number)
Scaleform version: 3.3.84
This static method sets the specified movie clip as a “modal” clip for focus management. This means TAB, Shift-TAB and arrow keys will move focus only inside the specified movie clip across all “tabable” children.
Parameters
modalClip – A modal clip. controllerIndex - A zero base index of the controller.
getModalClip() static method
public function getModalClip(controllerIndex : Number) : Object
Scaleform version: 3.3.84
This static method returns the modal clip for the specified controller.
Parameters
controllerIndex - Zero base index of the controller.
Returns A modal clip or undefined if not found.
setControllerFocusGroup () static method
public function setControllerFocusGroup (controllerIndex : Number, focusGroupIdx : Number) : Boolean
Scaleform version: 3.3.84
This static method associates the controller denoted by controllerIndex with a focus group. By default, all controllers are associated with focus group 0, which means that they are using the same focus. However, it is possible to make each controller work with their own focus. For example, if two controllers should have separate focus (in a split-screen use case) then setControllerFocusGroup(1,1) will create a separate focus group for the controller 1. Calling setControllerFocusGroup(1,0) will make controller 0 and 1 to share the same focus again.
Parameters
controllerIndex – Zero-base index of the controller. focusGroupIdx – Zero-base index of the focus group.
Example:
Selection["setControllerFocusGroup"](0,0); Selection["setControllerFocusGroup"](1,1); Selection["setControllerFocusGroup"](2,1);
Returns
Returns true if successful.
getControllerFocusGroup () static method
public function getControllerFocusGroup (controllerIndex : Number) : Number
Scaleform version: 3.3.84
This static method returns the focus group index associated with the specified controller.
Parameters
controllerIndex – Zero-base index of the physical controller.
Returns
Zero-based index of focus group.
getFocusArray() static method
public function getFocusArray(mc : Object) : Array
Scaleform version: 3.3.84
This static method returns an array of controller indices that currently has focus on the specified movieclip/button/text field.
Parameters
mc - A movie clip, button or text field.
Returns Array of zero-based indices (Numbers).
getFocusBitmask() static method
public function getFocusBitmask(mc : Object) : Number
Scaleform version: 3.3.84
This static method returns a bitmask where each bit represents a controller that currently has focus on the specified movieclip/button/textfield.
Parameters
mc - A movie clip, button or text field.
Returns A bitmask of controllers.
getControllerMaskByFocusGroup () static method
public function getControllerMaskByFocusGroup (focusGroupIdx : Number) : Number
Scaleform version: 3.3.84
This static method returns a bitmask where each bit represents a controller that is associated with the specified focus group. Returns the state set by the setControllerFocusGroup function.
Parameters
focusGroupIdx - An index of focus group.
Returns A bitmask of controllers.
numFocusGroups property
numFocusGroups : Number
Scaleform version: 3.3.84
Returns the number of focus groups, set up by call to setControllerFocusGroupfunction. If focus groups 0 and 3 are active, numFocusGroups will return 2.