TextField.restrict Property

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

limit text entry to a series of characters read/write
theField.restrict = restrictedChars;

Arguments

restrictedChars

Although not strictly an argument, restrictedChars is a string containing the allowable characters for the field.

Description

The string restrict property specifies the characters that the user can enter into theField. When restrict contains null (the default) or undefined, any character can be entered. When restrict contains a nonempty string of characters, only those characters are allowed as user input; attempts to enter other characters will simply be ignored. The following example limits text entry to the letters y and n. It also uses maxChars to limit text entry length to a single character:

this.createTextField("yesnoInput_txt", 1, 0, 0, 200, 20); yesnoInput_txt.type = "input"; yesnoInput_txt.border = true; yesnoInput_txt.restrict = "yn"; yesnoInput_txt.maxChars = 1;

Note that restrict operates according to character code points, not keyboard keys, so upper- and lowercase letters, such as Y and y, must be listed separately, as in:

yesnoInput_txt.restrict = "ynYN";

Interestingly, when only one case is specified, text entry is converted to that case. For example, to force the letters y and n to be converted to Y and N, use:

yesnoInput_txt.restrict = "YN";

Characters can be specified with string literals, as we have just seen, or with Unicode escape sequences in the form \uxxxx, where xxxx is the hexadecimal code point of the allowed character. Unicode notation normally is used with international characters. The following code assigns "ynYN" using escape sequences:

yesnoInput_txt.restrict = "\u0079\u006e\u0059\u004e";

Specifying many characters for inclusion in a text field can be tedious, so restrict also supports special sequences that represent character ranges and exclusions. These will be familiar to programmers accustomed to regular expressions. The "-" character marks a character range. For example:

// Limit ageInput_txt to the numbers: 0123456789 ageInput_txt.restrict = "0-9";

Multiple ranges are listed without spaces, as in:

// Limit passInput_txt to letters (upper- and lowercase) and numbers only passInput_txt.restrict = "a-zA-Z0-9";

Characters included in a range are those between the Unicode code points of the specified first and last characters, inclusive. For example, the following limits text entry to common punctuation symbols (hex code points 21 to 2F):

theField_txt.restrict = "\u0021-\u002F";

Normally, characters assigned to restrict are those included in the allowable set of input. The ^ character lets us specify characters to be excluded from allowable input. Any character following the ^ character cannot be entered into theField. For example:

// Include all characters except the numbers theField_txt.restrict = "^0-9"; // Include upper- and lowercase letters, but excluding x and X theField_txt.restrict = "a-zA-Z^xX";

To include the \, ^, or - characters, use \\\\, \\^, and \\-. For example, the following code restricts text entry to the letters a-z and the characters \, ^, and -:

theField_txt.restrict = "a-z\\^\\-\\\\";

The restrict property does not limit text changes made by a script; it applies to user input only. That is, the text and htmlText properties can be set to any value, regardless of restrict's limitations. Also, restrict does not dictate which characters are exported as font outlines with the movie; it merely limits text entry. Font outline export can be set via the authoring tool only, using the Character button in the text field Property inspector. See TextField.embedFonts for details on exporting fonts.

Bugs

Setting restrict to the empty string ("") should entirely disable text input; however, in Flash Player 6, it allows any character to be entered, exactly as if restrict were set to null. To disable input entirely, set the field's type property to "dynamic" and its selectable property to false.

See Also

TextField.embedFonts, TextField.maxChars, TextField.password, TextField.selectable, TextField.type; "Unicode-style escape sequences," in Chapter 4; Appendix B



    ActionScript for Flash MX. The Definitive Guide
    ActionScript for Flash MX: The Definitive Guide, Second Edition
    ISBN: 059600396X
    EAN: 2147483647
    Year: 2002
    Pages: 780
    Authors: Colin Moock

    flylib.com © 2008-2017.
    If you may any questions please contact us: flylib@qtcs.net