Recipe 8.6. Setting Allowable Characters for Input

Problem

You want to restrict allowable characters for an input text field or text input component instance.

Solution

Use the Character Options to embed only those characters you want to allow the user to input.

Use the text field's restrict property to assign a list or range of characters to include or not include.

Discussion

If you are using an input text field, there are two ways you can restrict the allowable characters. One way is to embed the font and to use the Character Options to specify which characters to embed. Because only that subset of characters gets embedded, the user can enter only those characters. For example, if you want to make sure that a user can only enter a number into an input field, you can embed only the number characters.

The downside of relying on embedding a font to restrict allowable characters is that embedded fonts increase the file size of the Flash movie. You can use ActionScript to restrict the allowable characters even with device fonts. The restrict property for a text field determines what characters can be entered by the user. You can assign a string value to the restrict property that contains all the characters you want to allow. The following example restricts the allowable characters for tInputField to the lowercase letters from a to g and the uppercase letters X, Y, and Z:

	tInputField.restrict = "abcdefgXYZ";

The restrict property affects what characters an input text field can display. If the user presses a key, there are several possible results. If the user presses a key that is in the restrict property value, the character appears in the text field. If the user presses a key that isn't directly in the restrict property value but can be shifted to a character in the restrict property value (adding or removing a Shift key), the shifted value appears in the text field. For example, if the user presses the z key yet only the Z character is allowed, the Z character will appear in the text field. If the user presses a key for which there is no shifted or unshifted value in the restrict property, no character is added to the text field.

You can also specify ranges of characters by using the dash between the starting and ending (inclusive) letters or numbers. The following example restricts the allowable characters to the ranges of the upper- and lowercase letters, as well as the numbers. Therefore, the disallowed characters include all punctuation and other non-alpha-numeric characters.

	tInputField.restrict = "a-zA-Z0-9";

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:

	tInputField.restrict = "^abcdefg"; // Allows all except lowercase a through g
	tInputField.restrict = "^a-z";     // Disallows all lowercase letters (but
	                                   // allows all other characters including
	                                   // uppercase)
	tInputField.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 into a field, you can specify its Unicode code point in the restrict property as follows:

	tInputField.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):

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

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

The text input component has a restrict parameter that corresponds to the restrict property of text fields. You can assign a value to the parameter using the Component Inspector panel. The only difference between values assigned to the restrict property of a text field using ActionScript and the restrict parameter of a text input component using the Component Inspector panel is that when you want to specify a backslash character in the string for the parameter, you need to use only two consecutive backslashes rather than four.