borland Packages Class Hierarchy dx.text Package
java.lang.Object +----com.borland.dx.text.ItemFormatter +----com.borland.dx.text.ItemFormatStr
Constructors Properties Methods
ItemFormatStr extends the ItemFormatter class through the use of String patterns to control formatting and parsing. Though other implementations of Formatter are allowed, ItemFormatStr is the only one currently provided with JDataStore. Note that the current implementation supports only Variants and is only a wrapper for VariantFormatStr.
Four different kinds of pattern strings can be used. Each is distinct, and the fields from one cannot be used with another. The type used will be inferred from the Variant.Type passed into the constructor. The types are:
The numeric format mask actually consists of two semicolon separated masks. The first is required. The second, if provided, will determine how negative numbers are formatted. For example, "###.##;(###.##)"
will format negative numbers in parentheses.
The following table illustrates the characters allowed in numeric fields.
Symbol | Meaning |
---|---|
0 | A digit. |
# | A digit, zero shows as absent. |
. | Placeholder for decimal separator. |
, | Placeholder for grouping delimiter. Shows the interval to be used. |
; | Separates formats. There are two: positive and negative. |
% | Divide by 100 and show as percentage. |
X | Any other characters can be used in. |
- | Leading minus for negative numbers. |
() | Parenthesis to show the entire expression as negative (e.g. "($#,###.##)"). |
{} | Optional fields (e.g. "0000.{00}"). Will allow the decimal fraction to be omitted when editing. |
^ | Sets the initial cursor when editing. |
\nnnn{} | Single character literal (e.g. \002, \0x0A, \u2030). |
The following table illustrates the characters allowed in date or timestamp fields.
Symbol | Meaning | Presentation | Notes |
---|---|---|---|
G | Era designator | Text | AD/BC |
y | Year | Number | Y,YY = 97, YYYY = 1997 |
M | Month in year | Text and number | M,MM = numeric, MMM = month abbrev, MMMM = full month |
d | Day in year | Number | d,dd = 10, dddd = 0010 |
h | Hour in am/pm (1~12) | Number | h,hh = 12, hhhh = 0012 |
H | Hour in day (0~23) | Number | H,HH = 23, HHHH = 0023 |
m | Minute in hour (0~23) | Number | m,mm = 59, mmmm = 0059 |
s | Second in minute | Number | s,ss = 59, ssss = 0059 |
S | Millisecond | Number | S = 9, SS = 99, SSS = 999 |
E | Day in week | Text | E,EE,EEE = Sun, EEEE = Sunday |
D | Day in year | Number | D,DD = 364, DDDD = 0364 |
F | Day of week in month | Number | 2 (2nd Wed in July) |
w | Week in year | Number | 27 |
W | Week in month | Number | 2 |
a | AM/PM marker | Text | AM/PM |
k | Hour in day (1~24) | Number | 24 |
K | Hour in am/pm (0~11) | Number | 0 |
z | Time zone | Text | z,zz,zzz = PDT, zzzz = Pacific Standard Time |
' | Escape for text | ||
'' | Single quote | ||
\nnnn | Single character literal (e.g. \002, \0x0A, \u2030) | ||
() | Can be used to bracket optional fields (e.g. "0000.{00}" will allow the decimal fraction to be omitted when editing) | ||
^ | Sets the initial cursor position when editing |
The string editmask can actually consist of up to four distinct subfields, separated by the semicolons. The subfields are:
For example, the edit mask "(999)000-0000;0;_;"
would indicate:
"(___)___-____
"_"
(underscore)
(408)555-1234
would become 4085551234
(___)555-1234
would become 5551234
Not all three subfields are required. If subfield 3 is omitted, the "_"
(underscore) character will be the blank indicator. If subfield 2 is omitted, literals are not removed.
The following table illustrates the characters allowed in string fields.
Symbol | Meaning |
---|---|
0 | Digit (0 through 9, entry required; plus [+] and minus [-] signs not allowed). |
9 | Digit or space (entry not required; plus and minus signs not allowed). |
# | Digit or space (entry not required; blank positions converted to spaces, plus and minus signs allowed). |
L | Letter (A through Z, entry required). |
l | Letter (A through Z, entry optional). |
? | Letter (A through Z, entry optional). |
A | Letter or digit (entry required). |
a | Letter or digit (entry optional). |
C | Any character or a space (entry optional). |
c | Any character or a space (entry required). |
& | Any character or a space (entry required). |
< | Causes all characters that follow to be converted to lowercase. |
> | Causes all characters that follow to be converted to uppercase. |
! | Causes input mask to fill from right to left, rather than from left to right when characters on the left side of the input mask are optional. The exclamation point can be included anywhere in the input mask. |
\ | Causes the character that follows to be displayed as a literal character. |
\ | Causes the character that follows to be displayed as a literal character. Used to display any of the characters listed in this table as literal characters (for example, \A is displayed as just A). |
\nnnn | Single character literal (e.g. \002, \0x0A, \u2030). |
'' | Encloses a literal expression (for example, the pattern "990' units sold'" would display as "27 units sold"). |
** | Encloses a password encrypted string. For example, the pattern "*AAAAaaaa*" would accept a password of at least 4, and at most 8, alphanumeric characters. The characters would echo as '*' as they were typed. |
{} | Can be used to bracket optional fields. For example, "LLLL{LLL}" will allow a user to edit at least (but optionally up to 7) letters. |
^ | Sets the initial cursor position when editing. |
public ItemFormatStr(String pattern, int variantType)Constructs a string-based implementation of the Formatter interface.
public ItemFormatStr(String pattern, int variantType, Locale locale)Constructs a string-based implementation of the Formatter interface.
public Format getFormatObj()Returns the JDK Format subclass associated with this ItemFormatter.
getFormatObj() returns null if the constructor could not accept the initial pattern.
public Locale getLocale()Returns the Locale currently being used by this Formatter. Currently, there is no way to change this locale once the Formatter has been created. The returned value is never null.
public String getPattern()Returns the pattern currently being used by this Formatter for parsing and formatting.
public String format(Object value)Returns a String representing the given value stored in the supplied Variant. All reasonable attempts are made to "cast" the type found in the object into the appropriate type specified in the constructor of the implementing classes. A returned empty string indicates a null or empty input value. null means the formatting failed.
public Object getSpecialObject(int objType)Returns the value of the specified special object.
Some Formatter classes define special objects for their own use. You must know the internal details of the Format subclass being used to use getSpecialObject().
public Object parse(String stringValue)Analyzes the given String and produces as output an Object containing the appropriate value. A null return value results when stringValue is null or empty.
public String setPattern(String pattern)Sets the pattern used for parsing and formatting to a new pattern, returning the old pattern. The new pattern must be of the same basic type associated with this type of Formatter. For example, if you used a Date/Time pattern in the constructor, you can't switch to a numeric pattern as each basic pattern type has its own data-dependent format() and parse() methods.
If the new pattern is null (or empty), setPattern() chooses a default pattern for the current locale.
public Object setSpecialObject(int objType, Object obj)Sets the special object associated with a particular Formatter. This is a general purpose routine to set specific booleans, characters, flags, and so on inside a formatter, but it is completely dependent on the formatter being used. setSpecialObject() returns the prior special object, which can be useful for restoring the original value after a temporary alteration.