DisplayMask property editor

To display this property editor, choose the displayMask property from the Inspector when any (StorageDataSet) Column component is selected in the Component Tree.

The displayMask property stores the string specification used to format the data displayed in the Column. This can format a Date column to display as "MM/dd/yy" or "dd/MM/yy", for example. In numeric columns, this is how you show commas, decimal points, and currency symbols. In String columns, display masks can add spaces or special characters that are not contained in the data itself for display formatting purposes. For example, a telephone number stored as 4084311000 can be displayed as (408) 431-1000 using a display mask of "(999) 999-9999" (without quotes).

The display mask is also used to parse user input by converting the String input back into the correct data type for the Column. User input which cannot be parsed using the specified display mask causes JBuilder to keep the user in the edit field until the data is entered correctly. You can display these validation messages by adding a StatusBar control to your application, and connecting it to the same StorageDataSet as the data in your GridControl (or other data-aware control). When you want tighter character validation (for example, character by character validation), set the editMask property. The edit mask has the same syntax as the displayMask, but it is used only for parsing user input, not for display formatting.

Explicitly setting the displayMask property to null or an empty string causes JBuilder to choose a display mask specification. If the data type of the column has international (localization) implications, the locale file for the Column is accessed for default display settings, for example, date and currency symbols. Otherwise, the formatter is bypassed and a basic display mask is used.

Because default display masks are locale-sensitive and built as needed, they are automatically localized. User-defined display masks are not altered if the column's locale changes.

Display masks and edit masks are never substituted if one is supplied and the other not. However, the display mask does perform validatation of user input if no edit mask is specified.

The displayMask property is an easy way to generate an instance of a formatter object which manages how the data is displayed. If you find that the displayMask does not handle your formatting needs, you can create your own class which implements the ItemFormatStr interface and assign it into the Column component's formatter property directly. In such cases, do not assign the displayMask property as your formatter 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: editMask, exportDisplayMask, String-based patterns (masks)

Mask

Enter a valid pattern, or mask, or select one from the list of sample masks. See Sample Masks for references to resources that provide more sample masks.

Description

Provide a verbal description of the type of information that would use the pattern you just entered. This is not required, but if you add the pattern to the Sample Masks list, the description will make it easier to use in future applications.

Add to Samples button

Click this button to add the mask and description currently in the Mask and Description field to the list of Sample Masks.

Test Input

Enter sample data in this field to test that it is compatible with the selected pattern in the Mask field. Click in the field, enter sample data, and press Enter. JBuilder will try to parse the data using the selected pattern, just as it usually does when a column has a displayMask but no editMask. If an error dialog appears, the pattern and the sample data are not compatible. Often the message is "Missing or invalid characters in field". For example, you will see this message when a date format requires a three-letter abbreviation of a month name if you enter a number or an unknown month abbreviation.

If the pattern and the data are compatible, the sample data is formatted according to the pattern. Since this is the same format you used to enter it, you won’t see any change except that field is no longer in edit. In your application, you may want to use an editMask as well as a displayMask to guide data entry and editing.

Sample Masks

Provides some examples of masks available for the type of data selected. For more sample masks, see String-based patterns (masks) or Adding an Edit or Display Pattern for data formatting. Each of these topics discusses masks for numeric data patterns, date and time data patterns, text data patterns, and boolean data patterns.