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