Recipe 8.7 Filtering Text Input

8.7.1 Problem

You want to restrict the characters that a user can type into an input field.

8.7.2 Solution

Set the restrict property of the text field.

8.7.3 Discussion

By default, a user can type any character into an input field. However, in many scenarios you might want to restrict the allowable characters. For example, you might restrict characters to numbers and dashes in the case of an input field for telephone numbers.

The TextField.restrict property lets you specify the allowed characters for user input in a field. Specify a string containing the allowable characters, such as:

myTextField.restrict = "abcdefg";

This example lets the user enter any of the following allowable characters: a, b, c, d, e, f, or g. Other characters are disallowed. If the user tries to enter "freedom", only "feed" will appear, since the letters r, o, and m are not in the allowable character set.

If the restrict string is set to the empty string, then all characters are allowed. To prevent input entirely, set the text field's type to "dynamic".

Also note that ActionScript distinguishes between upper- and lowercase characters. In other words, there is a difference between a and A. If the restrict property is set to "abcdefg", the uppercase variants of the allowable characters (such as A, B, C) will be entered as the lowercase (allowable) equivalents a, b, and c. The same is true in reverse: if a lowercase character is entered when only the uppercase counterpart is allowed, the character will be converted to uppercase.

The restrict property supports certain regular expressions, as described in Recipe 9.6. Therefore, you can also enter ranges by indicating the first character in the range and the last character in the range separated by a dash (-):

myTextField.restrict = "a-zA-Z";   // Allows only upper- and lowercase letters
myTextField.restrict = "a-zA-Z ";  // Allows only letters and spaces
myTextField.restrict = "0-9";      // Allows only numbers

In addition to specifying allowable characters, you can also disallow characters with a restrict string by using the caret character (^). All characters and ranges in a restrict string following the caret will be disallowed. For example:

myTextField.restrict = "^abcdefg"; // Allows all except lowercase a-g
myTextField.restrict = "^a-z";     // Disallows all lowercase letters (but allows all
                                   // other characters, including uppercase)
myTextField.restrict = "0-9^5";    // Allows numbers only, with the exception of 5

You can also specify allowable characters using Unicode escape sequences. For example, if you want to disallow users from entering the character (Ctrl-Z) into a field, you can specify its Unicode code point in the restrict property, as follows:

myTextField.restrict = "^\u001A";

To allow a literal character that has a special meaning when used in a restrict string (such as a dash or caret), you must escape the character in the restrict string by preceding it with two backslashes (not just one):

myTextField.restrict = "0-9\\-";      // Allows numbers and dashes
myTextField.restrict = "0-9\\^";      // Allows numbers and caret marks

If you want to escape the backslash character, you must precede it with three backslashes for a total of four backslashes:

myTextField.restrict = "0-9\\\\";     // Allows numbers and backslashes

8.7.4 See Also

Recipe 9.6. Also refer to Table A-1, which lists the Unicode code points for Latin 1 characters.