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 8314311000 can be displayed as (831) 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 JdbStatusLabel
component to your application, and connecting it to the same StorageDataSet
as the data in your JdbTable
(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 Database Application Developer's Guide
.
See also
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.
Provide a 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.
Click this button to add the mask and description currently in the Mask and Description field to the list of Sample Masks.
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.
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.