borland Packages  Class Hierarchy  dx.text Package 

ItemFormatStr class

java.lang.Object
   +----com.borland.dx.text.ItemFormatter
           +----com.borland.dx.text.ItemFormatStr

About the ItemFormatStr class

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:

Numeric fields

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.

Valid characters - 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).

Date and timestamp fields

The following table illustrates the characters allowed in date or timestamp fields.

Valid characters - date and 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    

String fields

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:

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.

Valid characters - 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.


ItemFormatStr constructors

ItemFormatStr properties

*Read-only properties **Write-only properties

Properties implemented in this class

Properties implemented in java.lang.Object

ItemFormatStr methods

Methods implemented in this class

Methods implemented in java.lang.Object


ItemFormatStr constructors

ItemFormatStr(java.lang.String, int)

  public ItemFormatStr(String pattern, int variantType)
Constructs a string-based implementation of the Formatter interface.

Parameters:

pattern
The string of special characters used to format values when using the format() method. If this value is null (or empty), the best "default" pattern will be selected based on the locale.
variantType
The type of pattern being used. This can be any one of the following 4 types: A value of zero will default to ItemFormatter.TEXT.

ItemFormatStr(java.lang.String, int, java.util.Locale)

  public ItemFormatStr(String pattern, int variantType, Locale locale)
Constructs a string-based implementation of the Formatter interface.

Parameters:

pattern
The string of special characters used to format values when using the format() method. If this value is null (or empty), the best "default" pattern will be selected based on the locale.
variantType
The type of pattern being used. This can be any one of the following 4 types: A value of zero will default to ItemFormatter.TEXT.
locale
The locale to control this pattern. This will determine things like the decimal point sign, the currency sign, etc. If this value is null, the current default locale will be used.

ItemFormatStr properties

formatObj

 public Format getFormatObj()
Returns the JDK Format subclass associated with this ItemFormatter.

getFormatObj() returns null if the constructor could not accept the initial pattern.

locale

 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.

pattern

 public String getPattern()
Returns the pattern currently being used by this Formatter for parsing and formatting.

ItemFormatStr methods

format(java.lang.Object)

  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.

Parameters:

value
The value to be formatted to a String.

Overrides: com.borland.dx.text.ItemFormatter.format(java.lang.Object)

getSpecialObject(int)

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

Parameters:

objType
Contains an identifier telling which object in which Formatter to retrieve. May be either ItemFormatter.FILLCHARACTER or ItemFormatter.REPLACECHARACTER. Fill characters are used to fill empty slots in the string. Replace characters replace fill characters on output.

Overrides: com.borland.dx.text.ItemFormatter.getSpecialObject(int)

parse(java.lang.String)

  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.

Parameters:

stringValue
The string to be parsed.

Overrides: com.borland.dx.text.ItemFormatter.parse(java.lang.String)

setPattern(java.lang.String)

  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.

Parameters:

pattern
The new pattern to be used for formatting and parsing.

Overrides: com.borland.dx.text.ItemFormatter.setPattern(java.lang.String)

setSpecialObject(int, java.lang.Object)

  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.

Parameters:

objType
Identifies which object in which formatter to retrieve. It can be ItemFormatter.FILLCHARACTER or ItemFormatter.REPLACECHARACTER. Fill characters are used to fill empty slots in the string. Replace characters replace fill characters on output.
obj
Contains the object to be set. The type of the Object must match the expected type for the given objType; do not pass a null object.