To display this property editor, choose the editMask property from the Inspector when any (StorageDataSet) Column component is selected in the Component Tree.
The editMask property stores the string specification used to control the entry of data in the column when the user starts editing data and to format the value entered. The displayMask handles the formatting. Edit and display masks are never substituted one for the other if one is supplied and the other not. However, if an edit mask is not specified, the display mask performs validation of user input. Edit masks affect the formatting of data by displaying spaces or special characters that ease data entry. Edit masks also restrict the type of data the user can enter, for example, by allowing digits only, or requiring entry in certain parts of a field, and so on. For String columns, these characters may optionally be stored with the data or not. For example, displaying parenthesis for a telephone number can ease data entry by clearly separating the area code from the telephone number.
User-defined edit masks are not altered if the column's locale changes.
When entering data into an edit mask and using the left shift feature where characters are entered from the right end of the pattern specification and shift left, if any character input cannot shift left, shifting stops. If you continue to type when you are positioned at the right of the pattern, the last character is overwritten with each key pressed.
If you find that the editMask does not handle your formatting needs, you can create your own class which implements the ItemEditMask interface and assign it into the Column component's editMasker property directly. In such cases, do not assign the editMask property as your editMasker will be overwritten.
For examples of patterns used with display masks, see Adding an Edit or Display Pattern to control data in the Database Application Developer's Guide.
See also: displayMask property, String-based patterns (masks)
If a pattern is syntactically invalid you will see are error message in the lower left corner of the editor. However, the property editor may indicate that a valid pattern is erroneous, for example if a pattern consists entirely of literals. The property editor cannot detect these types of errors, but can detect errors such as a missing closing quote.
Enter sample data in this field to test that it is compatible with the selected pattern in the mask field. When you click in the field, you will see a data-entry mask based on the pattern. Enter your sample data. If the mask will not accept the desired input, press Esc to cancel. Then correct the pattern, and try again. When you have entered your sample data, press Enter. If an error dialog appears, the pattern and the sample data are not compatible. A common error message is "Missing or invalid characters in field", indicating that input is not complete. For example, a pattern for a currency column may require two decimal digits.
If the pattern and the data are compatible, the parsed sample data is displayed in its default display format. For the US locale, the defaults for data types that are locale-specific are:
Data type | Default display format | Description |
Numeric | #,##0.###;-#,##0.### | grouped by thousands, one whole number required, up to three decimals, minus sign for negatives |
Currency | $#,##0.00;($#,##0.00) | grouped by thousands, one whole number and two decimals required, parentheses for negatives |
Date | M/d/yy | Month/day/year order, month as a number, two-digit year |
Time | h:mm:ss a | 12-hour time, includes "am" or "pm" |
Boolean | true;false |
In your application, you may want to use a displayMask as well as an editMask, to change the way values are formatted.