PackageTop Level
Classpublic class Selection
InheritanceSelection Inheritance Object

Player version: Flash Player 5

The Selection class lets you set and control the text field in which the insertion point is located (that is, the field that has focus). Selection-span indexes are zero-based (for example, the first position is 0, the second position is 1, and so on).

There is no constructor function for the Selection class, because there can be only one currently focused field at a time.


Public Methods
 Method
  
addListener(listener:Object):Void
[static]Registers an object to receive keyboard focus change notifications.
  
getBeginIndex():Number
[static]Returns the index at the beginning of the selection span.
  
getCaretIndex():Number
[static]Returns the index of the blinking insertion point (caret) position.
  
getEndIndex():Number
[static]Returns the ending index of the currently focused selection span.
  
getFocus():String
[static]Returns a string specifying the target path of the object that has focus.
  
removeListener(listener:Object):Boolean
[static]Removes an object previously registered with Selection.addListener().
  
setFocus(newFocus:Object):Boolean
[static]Gives focus to the selectable (editable) text field, button, or movie clip, specified by the newFocus parameter.
  
setSelection(beginIndex:Number, endIndex:Number):Void
[static]Sets the selection span of the currently focused text field.
 Methods inherited from class Object
 addProperty, hasOwnProperty, isPropertyEnumerable, isPrototypeOf, registerClass, toString, unwatch, valueOf, watch
Events
 EventSummaryDefined by
  
onSetFocus = function([oldfocus:Object], [newfocus:Object]) {}
Notified when the input focus changes.Selection
Method detail
addListener()method
public static function addListener(listener:Object):Void

Player version: Flash Player 6

Registers an object to receive keyboard focus change notifications. When the focus changes (for example, whenever Selection.setFocus() is invoked), all listening objects registered with addListener() have their onSetFocus method invoked. Multiple objects may listen for focus change notifications. If the specified listener is already registered, no change occurs.

Parameters
listener:Object — A new object with an onSetFocus method.

See also

Selection.setFocus()

Example
In the following example, you create two input text fields at runtime, setting the borders for each text field to true. This code creates a new (generic) ActionScript object named focusListener. This object defines for itself an onSetFocus property, to which it assigns a function. The function takes two parameters: a reference to the text field that lost focus, and one to the text field that gained focus. The function sets the border property of the text field that lost focus to false, and sets the border property of the text field that gained focus to true: 
this.createTextField("one_txt", 99, 10, 10, 200, 20);
this.createTextField("two_txt", 100, 10, 50, 200, 20);
one_txt.border = true;
one_txt.type = "input";
two_txt.border = true;
two_txt.type = "input";

var focusListener:Object = new Object();
focusListener.onSetFocus = function(oldFocus_txt, newFocus_txt) {
    oldFocus_txt.border = false;
    newFocus_txt.border = true;
};
Selection.addListener(focusListener);

When you test the SWF file, try using Tab to move between the two text fields. Make sure that you select Control > Disable Keyboard Shortcuts so you can change focus between the two fields using Tab.

getBeginIndex()method 
public static function getBeginIndex():Number

Player version: Flash Player 5

Returns the index at the beginning of the selection span. If no index exists or no text field currently has focus, the method returns -1. Selection span indexes are zero-based (for example, the first position is 0, the second position is 1, and so on).

Returns
Number — An integer.

See also

Selection.getEndIndex()

Example
The following example creates a text field at runtime, and sets its properties. A context menu item is added that can be used to change the currently selected text to uppercase characters. 
this.createTextField("output_txt", this.getNextHighestDepth(), 0, 0, 300, 200);
output_txt.multiline = true;
output_txt.wordWrap = true;
output_txt.border = true;
output_txt.type = "input";
output_txt.text = "Enter your text here";
var my_cm:ContextMenu = new ContextMenu();
my_cm.customItems.push(new ContextMenuItem("Uppercase...", doUppercase));
function doUppercase():Void {
    var startIndex:Number = Selection.getBeginIndex();
    var endIndex:Number = Selection.getEndIndex();
    var stringToUppercase:String = output_txt.text.substring(startIndex, endIndex);
    output_txt.replaceText(startIndex, endIndex, stringToUppercase.toUpperCase());
}
output_txt.menu = my_cm;

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components' DepthManager class instead of the MovieClip.getNextHighestDepth() method.

For another example, see the Flash Samples page at www.adobe.com/go/learn_fl_samples. Download and decompress the Samples zip file and go to the ActionScript2.0\Strings folder to access the Strings.fla file.

getCaretIndex()method 
public static function getCaretIndex():Number

Player version: Flash Player 5

Returns the index of the blinking insertion point (caret) position. If there is no blinking insertion point displayed, the method returns -1. Selection span indexes are zero-based (for example, the first position is 0, the second position is 1, and so on).

Returns
Number — An integer.

Example
The following example creates and sets the properties of a text field at runtime. The getCaretIndex() method is used to return the index of the caret and display its value in another text field. 
this.createTextField("pos_txt", this.getNextHighestDepth(), 50, 20, 100, 22);
this.createTextField("content_txt", this.getNextHighestDepth(), 50, 50, 400, 300);
content_txt.border = true;
content_txt.type = "input";
content_txt.wordWrap = true;
content_txt.multiline = true;
content_txt.onChanged = getCaretPos;

var keyListener:Object = new Object();
keyListener.onKeyUp = getCaretPos;
Key.addListener(keyListener);

var mouseListener:Object = new Object();
mouseListener.onMouseUp = getCaretPos;
Mouse.addListener(mouseListener);

function getCaretPos() {
    pos_txt.text = Selection.getCaretIndex();
}

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components' DepthManager class instead of the MovieClip.getNextHighestDepth() method.

For another example, see the Flash Samples page at www.adobe.com/go/learn_fl_samples. Download and decompress the Samples zip file and go to the ActionScript2.0\Strings folder to access the Strings.fla file.

getEndIndex()method 
public static function getEndIndex():Number

Player version: Flash Player 5

Returns the ending index of the currently focused selection span. If no index exists, or if there is no currently focused selection span, the method returns -1. Selection span indexes are zero-based (for example, the first position is 0, the second position is 1, and so on).

Returns
Number — An integer.

See also

Selection.getBeginIndex()

Example
This example is excerpted from the Strings.fla file in the ActionScript samples folder. 
// define the function which converts the selected text in an instance,
// and convert the string to upper or lower case.
function convertCase(target, menuItem) {
    var beginIndex:Number = Selection.getBeginIndex();
    var endIndex:Number = Selection.getEndIndex();
    var tempString:String;
    // make sure that text is actually selected.
    if (beginIndex>-1 && endIndex>-1) {
    // set the temporary string to the text before the selected text.
    tempString = target.text.slice(0, beginIndex);
    switch (menuItem.caption) {
    case 'Uppercase...' :
        // if the user selects the "Uppercase..." context menu item,
        // convert the selected text to upper case.
        tempString += target.text.substring(beginIndex, endIndex).toUpperCase();
        break;
    case 'Lowercase...' :
        tempString += target.text.substring(beginIndex, endIndex).toLowerCase();
        break;
    }
    // append the text after the selected text to the temporary string.
    tempString += target.text.slice(endIndex);
    // set the text in the target text field to the contents of the temporary string.
    target.text = tempString;
    }
}

For the entire script, see the Flash Samples page at www.adobe.com/go/learn_fl_samples. Download and decompress the Samples zip file and go to the ActionScript2.0\Strings folder to access the Strings.fla file.

getFocus()method 
public static function getFocus():String

Player version: Flash Player 5 — Instance names for buttons and text fields work in Flash Player 6 and later.

Returns a string specifying the target path of the object that has focus.

Returns
String — A string or null.

See also

Selection.onSetFocus
Selection.setFocus()

Example
The following example displays the currently focused selection's target path in a TextArea component instance. Add several component instances or button, text field and movie clip instances to the Stage. Add several component instances or button, text field and movie clip instances to your SWF file. Then add the following ActionScript to your AS or FLA file. 
var focus_ta:mx.controls.TextArea;
my_mc.onRelease = function() {};
my_btn.onRelease = function() {};

var keyListener:Object = new Object();
keyListener.onKeyDown = function() {
    if (Key.isDown(Key.SPACE)) {
    focus_ta.text = Selection.getFocus()+newline+focus_ta.text;
    }
};
Key.addListener(keyListener);

Test the SWF file, and use Tab to move between the instances on the Stage. Make sure you have Control > Disable Keyboard Shortcuts selected in the test environment.

removeListener()method 
public static function removeListener(listener:Object):Boolean

Player version: Flash Player 6

Removes an object previously registered with Selection.addListener().

Parameters
listener:Object — The object that will no longer receive focus notifications.

Returns
Boolean — If listener was successfully removed, the method returns a true value. If listener was not successfully removed--for example, if listener was not on the Selection object's listener list--the method returns a value of false.

See also

Selection.addListener()

Example
The following ActionScript dynamically creates several text field instances. When you select a text field, information displays in the Output panel. When you select a text field, information writes to the log file. When you click the remove_btn instance, the listener is removed and information no longer displays in the Output panel. When you click the remove_btn instance, the listener is removed and information no longer writes to the log file. 
this.createTextField("one_txt", 1, 0, 0, 100, 22);
this.createTextField("two_txt", 2, 0, 25, 100, 22);
this.createTextField("three_txt", 3, 0, 50, 100, 22);
this.createTextField("four_txt", 4, 0, 75, 100, 22);

for (var i in this) {
    if (this[i] instanceof TextField) {
    this[i].border = true;
    this[i].type = "input";
    }
}

var selectionListener:Object = new Object();
selectionListener.onSetFocus = function(oldFocus, newFocus) {
    trace("Focus shifted from "+oldFocus+" to "+newFocus);
};
Selection.addListener(selectionListener);

remove_btn.onRelease = function() {
    trace("removeListener invoked");
    Selection.removeListener(selectionListener);
};

setFocus()method 
public static function setFocus(newFocus:Object):Boolean

Player version: Flash Player 5 — Instance names for buttons and movie clips work only in Flash Player 6 and later.

Gives focus to the selectable (editable) text field, button, or movie clip, specified by the newFocus parameter. If null or undefined is passed, the current focus is removed.

Parameters
newFocus:Object — An object such as a button, movie clip or text field instance, or a string specifying the path to a button, movie clip, or text field instance. If you pass a string literal specifying a path, enclose the path in quotation marks (" "). You can use dot or slash notation to specify the path. If you are using ActionScript 2.0, you must use dot notation. You can use a relative or absolute path.

Returns
Boolean — A Boolean value; true if the focus attempt is successful, false if it fails.

See also

Selection.getFocus()

Example
In the following example, the text field focuses on the username_txt text field when it is running in a browser window. If the user does not fill in one of the required text fields (username_txt and password_txt), the cursor automatically focuses in the text field that's missing data. For example, if the user does not type anything into the username_txt text field and clicks the submit button, an error message appears and the cursor focuses in the username_txt text field. 
this.createTextField("status_txt", this.getNextHighestDepth(), 100, 70, 100, 22);
this.createTextField("username_txt", this.getNextHighestDepth(), 100, 100, 100, 22);
this.createTextField("password_txt", this.getNextHighestDepth(), 100, 130, 100, 22);
this.createEmptyMovieClip("submit_mc", this.getNextHighestDepth());
submit_mc.createTextField("submit_txt", this.getNextHighestDepth(), 100, 160, 100, 22);
submit_mc.submit_txt.autoSize = "center";
submit_mc.submit_txt.text = "Submit";
submit_mc.submit_txt.border = true;
submit_mc.onRelease = checkForm;
username_txt.border = true;
password_txt.border = true;
username_txt.type = "input";
password_txt.type = "input";
password_txt.password = true;
Selection.setFocus("username_txt");
//
function checkForm():Boolean {
    if (username_txt.text.length == 0) {
    status_txt.text = "fill in username";
    Selection.setFocus("username_txt");
    return false;
    }
    if (password_txt.text.length == 0) {
    status_txt.text = "fill in password";
    Selection.setFocus("password_txt");
    return false;
    }
    status_txt.text = "success!";
    Selection.setFocus(null);
    return true;
}

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components' DepthManager class instead of the MovieClip.getNextHighestDepth() method.

setSelection()method 
public static function setSelection(beginIndex:Number, endIndex:Number):Void

Player version: Flash Player 5

Sets the selection span of the currently focused text field. The new selection span will begin at the index specified in the beginIndex parameter, and end at the index specified in the endIndex parameter. Selection span indexes are zero-based (for example, the first position is 0, the second position is 1, and so on). This method has no effect if there is no currently focused text field.

Parameters
beginIndex:Number — The beginning index of the selection span.
 
endIndex:Number — The ending index of the selection span.

Example
In the following ActionScript, you create a text field at runtime and add a string to it. Then you focus the text field and select a span of characters in the focused text field.
this.createTextField("myText_txt", 99, 10, 10, 200, 30);
myText_txt.text = "this is my text";
this.onEnterFrame = function () {
    Selection.setFocus("myText_txt");
    Selection.setSelection(0, 3);
    delete this.onEnterFrame;
}

The following example illustrates how the endIndex parameter is not inclusive. In order to select the first character, you must use an endIndex of 1, not 0. If you change the endIndex parameter to 0, nothing will be selected.

this.createTextField("myText_txt", 99, 10, 10, 200, 30);
myText_txt.text = "this is my text";
this.onEnterFrame = function () {
    Selection.setFocus("myText_txt");
    Selection.setSelection(0, 1);
    delete this.onEnterFrame;
}

Event detail
onSetFocusevent listener

public onSetFocus = function([oldfocus:Object], [newfocus:Object]) {}

Player version: Flash Player 6

Notified when the input focus changes. To use this listener, you must create a listener object. You can then define a function for this listener and use Selection.addListener() to register the listener with the Selection object, as in the following code: 

var someListener:Object = new Object();
someListener.onSetFocus = function () {
    // statements
}
Selection.addListener(someListener);

Listeners enable different pieces of code to cooperate because multiple listeners can receive notification about a single event.

Parameters
oldfocus:Object [optional] — The object losing focus.
 
newfocus:Object [optional] — The object receiving focus.

Example
The following example demonstrates how to determine when input focus changes in a SWF file between several dynamically created text fields. Enter the following ActionScript into a FLA or AS file and then test the document: 
this.createTextField("one_txt", 1, 0, 0, 100, 22);
this.createTextField("two_txt", 2, 0, 25, 100, 22);
this.createTextField("three_txt", 3, 0, 50, 100, 22);
this.createTextField("four_txt", 4, 0, 75, 100, 22);

for (var i in this) {
    if (this[i] instanceof TextField) {
    this[i].border = true;
    this[i].type = "input";
    }
}

this.createTextField("status_txt", this.getNextHighestDepth(), 200, 10, 300, 100);
status_txt.html = true;
status_txt.multiline = true;

var someListener:Object = new Object();
someListener.onSetFocus = function(oldFocus, newFocus) {
    status_txt.htmlText = "<b>setFocus triggered</b>";
    status_txt.htmlText += "<textformat tabStops='[20,80]'>";
    status_txt.htmlText += "&nbsp;\toldFocus:\t"+oldFocus;
    status_txt.htmlText += "&nbsp;\tnewFocus:\t"+newFocus;
    status_txt.htmlText += "&nbsp;\tgetFocus:\t"+Selection.getFocus();
    status_txt.htmlText += "</textformat>";
};
Selection.addListener(someListener);

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components' DepthManager class instead of the MovieClip.getNextHighestDepth() method.

See also

Selection.addListener()
Selection.setFocus()



© 2004-2010 Adobe Systems Incorporated. All rights reserved.
Wed Apr 7 2010, 4:41 PM GMT-07:00