|
Flash 8 ActionScript 2.0 Language Reference
|
|
Top LevelClass Selection
Object
public class Selection
extends 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.
static | addListener(listener:Object) : Void
Registers an object to receive keyboard focus change notifications. |
static | getBeginIndex() : Number
Returns the index at the beginning of the selection span. |
static | getCaretIndex() : Number
Returns the index of the blinking insertion point (caret) position. |
static | getEndIndex() : Number
Returns the ending index of the currently focused selection span. |
static | getFocus() : String
Returns a string specifying the target path of the object that has focus. |
static | removeListener(listener:Object) : Boolean
Removes an object previously registered with Selection.addListener() . |
static | setFocus(newFocus:Object) : Boolean
Gives focus to the selectable (editable) text field, button, or movie clip, specified by the newFocus parameter. |
static | setSelection(beginIndex:Number, endIndex:Number) : Void
Sets the selection span of the currently focused text field. |
onSetFocus Event 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 += " \toldFocus:\t"+oldFocus;
status_txt.htmlText += " \tnewFocus:\t"+newFocus;
status_txt.htmlText += " \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
addListener Method
public static 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. |
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.
See also
getBeginIndex Method
public static 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
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.
An example can also be found in the Strings.fla file in the ActionScript samples Folder. Typical paths to this folder are:
- Windows: boot drive\Program Files\Macromedia\Flash 8\Samples and Tutorials\Samples\ActionScript
- Macintosh: Macintosh HD/Applications/Macromedia Flash 8/Samples and Tutorials/Samples/ActionScript
See also
getCaretIndex Method
public static 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
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.
An example can also be found in the Strings.fla file in the ActionScript samples Folder. Typical paths to this folder are:
- Windows: boot drive\Program Files\Macromedia\Flash 8\Samples and Tutorials\Samples\ActionScript
- Macintosh: Macintosh HD/Applications/Macromedia Flash 8/Samples and Tutorials/Samples/ActionScript
getEndIndex Method
public static 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
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;
}
}
See the Strings.fla file for the entire script. Typical paths to the ActionScript samples folder are:
- Windows: boot drive\Program Files\Macromedia\Flash 8\Samples and Tutorials\Samples\ActionScript
- Macintosh: Macintosh HD/Applications/Macromedia Flash 8/Samples and Tutorials/Samples/ActionScript
See also
getFocus Method
public static 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. - If a TextField object has focus, and the object has an instance name, this method returns the target path of the TextField object. Otherwise, it returns the TextField's variable name.
- If a Button object or button movie clip has focus, this method returns the target path of the Button object or button movie clip.
- If neither a TextField object, Button object, Component instance, nor button movie clip has focus, this method returns
null
.
Returns
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.
See also
removeListener Method
public static 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 .
|
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);
};
See also
setFocus Method
public static 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.
|
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.
See also
setSelection Method
public static 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;
}
Copyright © 2005 Macromedia Inc. All rights reserved.
Tue Sep 13 2005, 16:15 PDT