Adding an Edit or Display Pattern for data formatting

All data stored internally as numbers, dates, etc., is entered and displayed as text strings. Formatting is the conversion from the internal representation to a string equivalent. Parsing is the conversion from string representation to internal representation. Both conversions are defined by rules specified by string-based patterns.

All formatting and parsing of data in the DataSet package is controlled by the VariantFormatter class, which is uniquely defined for every Column in a DataSet. To simplify the use of this class, there are corresponding string properties which, when set, construct a VariantFormatter for the Column using the basic "pattern" syntax defined in the JDK java.text.Format classes.

There are four distinct kinds of patterns based on the data type of the item you are controlling.

  1. Numeric patterns
  2. Date and time patterns
  3. String patterns
  4. Boolean patterns

See String-based patterns (masks) for more information on patterns.

The Column level properties that work with these string-based patterns are:

The default VariantFormatter implementations for each Column are simple implementations which were written to be fast. Those columns using punctuation characters, such as dates, use a default pattern derived from the column's locale. To override the default formatting (for example, commas for separating groups of thousands, or a decimal point), explicitly set the string-based pattern for the property you want to set (displayMask, editMask, or exportDisplayMask).

Setting a displayMask, editMask, or exportDisplayMask to an empty string or null has special meaning; it selects its pattern from the default Locale. This is the default behavior of JBuilder for columns of type Date, Time, Timestamp, Float, Double, and BigDecimal. By doing this, JBuilder assures that an application using the defaults will automatically select the proper display format when running under a different locale.

Note: When writing international applications that use locales other than en_US (U.S. English locale), you must use the U.S. style separators (for example, the comma for the thousands separator and the period as the decimal point) in your patterns. This allows you to write an application that uses the same set of patterns regardless of its target locale. When using a locale other than en_US, these characters are translated by the JDK to their localized equivalents and displayed appropriately. For an example of using patterns in an international application, see the IntlDemo.jpr file in the samples\borland\samples\intl directory of your JBuilder installation.

To override the default formats for numeric and date values that are stored in locale files, set the displayMask, editMask, or exportDisplayMask property (as appropriate) on the Column component of the DataSet.

The formatting capabilities provided by JBCL string-based patterns are typically sufficient for most formatting needs. If you have more specific formatting needs, the format mechanism includes general-purpose interfaces and classes that you can extend to create custom format classes.

Display masks

Display masks are string-based patterns that are used to format the data displayed in the Column, for example, in a GridControl. Display masks can add spaces or special characters within a data item for display purposes.

Display masks are also used to parse user input by converting the string input back into the correct data type for the Column. If you enter data which cannot be parsed using the specified display mask pattern, you will not be able to leave the field until data entered is correct.

Tip: User input that cannot be parsed with the specified pattern generates validation messages. These messages appear on the StatusBar control when the StatusBar and the UI control that displays the data for editing (for example, a GridControl) are set to the same DataSet.

Edit masks

Before editing starts, the display mask handles all formatting and parsing. Edit masks are optional string-based patterns that are used to control data editing in the Column and to parse the string data into the Column keystroke-by-keystroke.

In a Column with a specified edit mask, literals included in the pattern display may be optionally saved with the data. Positions in the pattern where characters are to be entered display as underscores (_) by default. As you type data into the Column with an edit mask, input is validated with each key pressed against characters that the pattern allows at that position in the mask.

Characters that are not allowed at a given location in the pattern are not accepted and the cursor moves to the next position only when the criteria for that location in the pattern is satisfied.

Using masks for importing and exporting data

When you import data into a JBCL component, JBuilder looks for a .SCHEMA file by the same name as the data file. If it finds one, the settings in the .SCHEMA file take precedence. If it doesn't find one, it looks at the column's exportDisplayMask property. Use the exportDisplayMask to format the data being imported. Often, data files contain currency formatting characters which cannot be read directly into a numeric column. You can use an exportDisplayMask pattern to read in the values without the currency formatting. Once in JBuilder, set display and/or edit masks to re-establish currency (or other formatting) as desired.

When exporting data, JBuilder uses the exportDisplayMask to format the data for export. At the same time, it creates a .SCHEMA file with these settings so that data can be easily imported back into a JBCL component.

Data type dependent patterns

The following sections describe and provide examples for string-based patterns for various types of data.

Patterns for numeric data

Patterns for numeric type data consist of two parts: the first part specifies the pattern for positive numbers (numbers greater than 0) and the second for negative numbers. The two parts are separated with a semi-colon (;). The pattern symbols for numeric data are described in Numeric data patterns.

Numeric Column components always have display and edit masks. If you do not set these properties explicitly, default patterns are obtained using the following search order:

  1. From the Column component's locale.
  2. If no locale is set for the Column, from the DataSet object's locale.
  3. If no locale is set for the DataSet, from the default system locale. Numeric data displays with three decimal places by default.

Numeric columns allow any number of digits to the left of the decimal point; however, masks restrict this to the number of digits specified to the left of the decimal point in the mask. To ensure that all valid values can be entered into a Column, specify sufficient digits to the left of the decimal point in your pattern specification.

In addition, every numeric mask has an extra character positioned at the left of the data item that holds the sign for the number.

Note: When writing international applications that use locales other than en_US (U.S. English locale), you must use the U.S. style separators (for example, the comma for the thousands separator and the period as the decimal point) in your patterns. This allows you to write an application that uses the same set of patterns regardless of its target locale. When using a locale other than en_US, these characters are translated by the JDK to their localized equivalents and displayed appropriately. For an example of using patterns in an international application, see the IntlDemo.jpr file in the samples\borland\intl directory of your JBuilder installation.

The code that sets the display mask to the first pattern in the table below is:

     column1.setDisplayMask(new String("###%"));

The following table explains the pattern specifications for numeric data:

Pattern specification Data values Formatted value Meaning
###% 85 85% All digits are optional, leading zeros do not display, value is divided by 100 and shown as a percentage
#,##0.0#^ cc;-#,##0.0#^ cc 500.0
-500.5
004453.3211
-00453.3245
500.0 cc
-500.5 cc
4,453.32 cc
-453.32 cc
The "0" indicates a required digit, zeroes are not suppressed. Negative numbers are preceeded with a minus sign. The literal "cc" displays beside the value. The cursor is positioned at the point of the carat (^) with digits moving to the left as you type each digit.
$#,###.##;($#,###.##) 4321.1
-123.456
$4,321.1
($123.46)
All digits optional, includes a thousands separator, decimal separator, and currency symbol. Negative values enclosed in parenthesis. Typing in a minus sign (-) or left parenthesis (() causes JBuilder to supply parenthesis surrounding the value.

Patterns for date and time data

Columns that contain date, time, and timestamp data always have display and edit masks. If you do not set these properties explicitly, default patterns are obtained using the following search order:
  1. From the Column component's locale.
  2. If no locale is set for the Column, from the DataSet object's locale.
  3. If no locale is set for the DataSet, from the default system locale.
The pattern symbols you use for date, time, and timestamp data are described in Date, time, and timestamp patterns.

For example, the code that sets the edit mask to the first pattern listed below is:

     column1.setDisplayMask(new String("MMM dd, yyyyG"));

The following table explains the pattern specifications for date and time data:


Pattern specification Data values Formatted value Meaning
MMM dd, yyyyG
January 14, 1900
February 2, 1492
Jan 14, 1900AD
Feb 02, 1492AD
Returns the abbreviation of the month, space (literal), two digits for the day, 4 digits for year, plus era designator
MM/d/yy H:m July 4, 1776 3:30am
March 2, 1997 11:59pm
07/4/76 3:30
03/2/92 23:59
Returns the number of the month, one or two digits for the day (as applicable), two digits for the year, plus the hour and minute using a 24-hour clock

Patterns for string data

Patterns for formatting and editing text data are specific to JBCL classes. They consist of up to four parts, separated by semicolons, of which only the first is required. These parts are:
  1. The string pattern.
  2. Whether literals should be stored with the data or not. A value of 1 indicates the default behavior, to store literals with the data. To remove literals from the stored data, specify 0.
  3. The character to use as a "blank" indicator. This character indicates the spaces to be entered in the data. If this part is omitted, the underscore character is used.
  4. The character to use to replace blank positions on output. If this part is omitted, blank positions are stripped.
The pattern symbols you use for text data are described in Text patterns.

For example, the code that sets the display and edit masks to the first pattern listed below is:

     column1.setDisplayMask(new String("00000{-9999}"));
     column1.setEditMask(new String("00000{-9999}"));

The following table explains some pattern specifications:

Pattern specification Data values Formatted value Meaning
00000{-9999} 950677394
00043
1540001
95067-7394
00043
00154-0001
Display leading zeros for the left 5 digits (required), optional remaining characters include a dash literal and 4 digits. Use this pattern for U.S. postal codes.
L0L 0L0 H2A2R9
M1M3W4
H2A 2R9
M1M 3W4
The L specifies any letter A-Z, entry required. The 0 (zero) specifies any digit 0-9, entry required, plus (+) and minus (-) signs not permitted. Use this pattern for Canadian postal codes.
{(999)} 000-0000^!;0 4084311000 (408) 431-1000 A pattern for a phone number with optional area code enclosed in parenthesis. The carat (^) positions the cursor at the right side of the field and data shifts to the left as it is entered. To ensure data is stored correctly from right to left, use the ! symbol. (Numeric values do this automatically.) The zero (0) indicates that literals are not stored with the data.

Patterns for boolean data

The BooleanFormat component uses a string-based pattern that is helpful when working with values that can have two values, stored as true or false. Data that falls into each category is formatted using string values you specify. This formatter also has the capability to format null or unassigned values.

For example, you can store gender information in a column of type boolean but can have JBuilder format the field to display and accept input values of "Male" and "Female" as shown in the following code:

     column1.setEditMask("Male;Female;");
     column1.displayMask("Male;Female;");

The following table illustrates valid boolean patterns and their formatting effects:

Pattern specification

Format for true values Format for false values Format for null values
male;female male female (empty string)
T,F,T T F T
Yes,No,Don't know Yes No Don't know
smoker;; smoker (empty string) (empty string)
smoker;nonsmoker; smoker nonsmoker (empty string)