Recipe 9.5. Filtering Text Input

Problem

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

Solution

Set the restrict property of the text field.

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 into a field. Specify a string containing the allowable characters, such as:

field.restrict = "abcdefg";

This example lets the user enter any of the allowable characters: a, b, c, d, e, f, or g. Other characters are disallowed. If the user tries to enter grabs, only gab appears, since the letters r and s 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 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, c). The same is true in reverse, such that if a lowercase character is entered when only the uppercase counterpart is allowed, the character is converted to uppercase.

The restrict property supports certain regular expression-like patterns. 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 (-):

field.restrict = "a-zA-Z";   // Allow only upper- and lowercase letters
field.restrict = "a-zA-Z ";  // Allow only letters and spaces
field.restrict = "0-9";      // Allow 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 are disallowed; for example:

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

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

field.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), as shown here:

field.restrict = "0-9\\-";      // Allow numbers and dashes
field.restrict = "0-9\\^";      // Allow 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:

field.restrict = "0-9\\\\";     // Allow numbers and backslashes

The restrict property only affects the characters that the user can input. It does not have any affect on which characters can be displayed programmatically.