| TextField.replaceSel( ) Method | Flash 6 |
| replace selected text (without disturbing formatting) |
The string of new characters that will replace the current selection.
The replaceSel( ) method deletes the selected characters in theField and replaces them with newText. If no characters are selected in theField, replaceSel( ) simply inserts newText at theField's insertion point, or before the first character if theField is not focused. The new amalgamated value is reflected by theField.text.
While replaceSel( )'s use may seem limited, it is actually one of the most important TextField methods because it provides the only means of inserting new text into a text field without disturbing existing character formatting. To update a text field's value using replaceSel( ), we must first focus the field, then position the insertion point, and then insert the text, as follows:
// Focus the field
Selection.setFocus("theField_txt");
// Position insertion point after the fourth character
Selection.setSelection(4, 4);
// Insert new text
theField_txt.replaceSel("text to insert");
Obviously, this process is tedious. See Example 18-6 for a custom method that takes care of the selection work.
To apply a new format to text inserted by replaceSel( ), we must invoke setNewTextFormat( ) after the insertion point is set with Selection.setSelection( ). See the Usage heading under TextField.setNewTextFormat( ) for details.
In some cases, we want to replace a selection made by the user when a button is clicked (for example, when inserting text in a word processing-style application). This proves to be trickier than expected because the selection is lost when focus changes to the button during the click. To prevent the selection from being lost, we record it in the button's rollover event handler, as follows:
replace_btn.onRollover = function () {
// Record which field was focused
oldFocus = Selection.getFocus();
// Record the selection span
oldBegin = Selection.getBeginIndex();
oldEnd = Selection.getEndIndex();
}
replace_btn.onRelease = function () {
// If a text field was the last object focused...
if (eval(oldFocus) instanceof TextField) {
// ...focus it
Selection.setFocus(oldFocus);
// Then set the selection and insert the new text
Selection.setSelection(oldBegin, oldEnd);
eval(oldFocus).replaceSel("text to insert");
}
}
Example 18-6 adds an appendText( ) method to all TextField objects. The method inserts new text at the end of the field, using replaceSel( ).
/*
* Method: TextField.appendText
* Desc: A convenient method for appending text to a
* text field without disturbing its formatting.
* Params: theText The text to append.
*/
TextField.prototype.appendText = function (theText) {
// Remember the original scroll because replaceSel( ) can change scroll.
var origScroll = this.scroll;
// Focus the field.
Selection.setFocus(this);
// Position insertion point after the last character.
Selection.setSelection(this.length, this.length);
// Append the text to the field.
this.replaceSel(theText);
// Reset the scroll to where it was before we added any text.
this.scroll = origScroll;
}
Reader Exercise: Adapt the appendText( ) handler from Example 18-6, or use the example from this entry's Description, to create a custom replaceText( ) function that accepts starting and ending character indexes to specify the character span to be replaced.
Selection.setFocus( ), Selection.setSelection( ), TextField.setNewTextFormat( ), TextField.text