[Home]   [Contents]   [Index]   [Javadoc] JCLASS
  [Frames]    [No Frames]
[Previous]   [Next]

2:
JClass Field's Properties

Introduction * Field's Key Properties * Format Tables

Property Summaries * Exploring the Form Demo


Introduction

This chapter discusses how to use JClass Field's key properties, and provides a quick summary of the properties arranged by data type. See Appendix A, JClass Field Property Listings for a complete summary of JClass Field's properties, and the API for complete reference information.

Date, number, and format tables are included for reference purposes, since JClass Field components may be used for date and time information, for displaying and editing numbers and currencies, and for validating text entries. These formats follow standard Java conventions.


Field's Key Properties

The key properties of JClass Field components are contained in three objects, JCValueModel, JCValidator, and JCInvalidInfo. The properties, which you set to dictate the format and behavior of the JClass Field components, are not directly exposed by the Bean, but are accessed through the property customizer, DataProperties, or can be set programmatically.

JClass Field is designed to be used within an IDE, so almost all of its properties, including the property customizer, can be manipulated by using the property sheet in the IDE. Of course, you can set the properties programmatically as well.


The Value Model

value

value is the fundamental property of a field. A field's value changes dynamically as the end-user supplies data and has it validated. Because value is initially null, and allowNull is false by default, the field starts out in an invalid state.

The data member value is used to record both the initial value given to a field and its current value. It is initially set to null. If the allowNull property is true, the field may be left in this condition. However, the field is usually edited by the user and its null value changed to the value set by the user's input. After it has been inspected and approved by the field's validator, this change becomes the new value. Thus, in a typical application, value is updated through user interaction with the field. You see the current value displayed in the field and you can inspect value programmatically using the method getValue() to determine this central property of a field.


The Validator Property

By setting a data type with a JClass Field component, you associate a corresponding validator with that component. Here are some of the important properties contained in one or more of the JClass Field validators:

displayPattern, editPattern

You use these properties to control the appearance of values in number fields. When the field has focus, editPattern is in effect. When the field loses focus, displayPattern comes into effect. Both properties take their formats from one of the possible conventions for number formatting in the current locale, but you can choose a different format while in edit mode from that in display mode. Thus, you can allow the user to type a minus sign when entering a negative number, yet display it in the accounting fashion, using brackets instead of the minus sign.

It is possible to supply a type of feedback to users by appending a text string to the number that was entered, perhaps to remind users of the units that are expected in the field. For example, if the application is using a JCTextField with a property set for integer to collect a length measurement, and the required unit of measurement is feet, you could cause "ft." to display after the number by incorporating that string in the number format that you specify for displayPattern. The internal value of the field is unchanged; it remains a pure number, and no units are associated with it.

For JDK 1.2 and higher, numeric validators support scientific notation.

editFormats

This is a list of string formats that are used to match a user's input in fields that contain date and time values. The input is assumed to represent a partially completed field that the validator attempts to expand into a full date. There are a number of standard locale specific formats that can be used. The default edit formats are listed here:

h:mm:ss 'o"clock' a z EEEE, MMMM d, yyyy

h:mm:ss a z EEEE, MMMM d, yyyy

h:mm:ss a EEEE, MMMM d, yyyy

h:mm a EEEE, MMMM d, yyyy

h:mm:ss 'o"clock' a z dd-MMM-yy

h:mm:ss a dd-MMM-yy

h:mm a dd-mm-yy

h:mm:ss 'o"clock' a z M/d/yy

h:mm:ss a M/d/yy

MM d yy h:mm:ss or d MM yy or EE MM d

The symbols dd, mm, M, and so on, must follow the convention specified in the javadoc entry in the setFormat method of JCDateTimeValidator. You can construct a date format in any way you choose, so long as you assemble it from date format elements. This manual contains a copy of the date format conventions in the section on Date Formats later in this chapter, and under the entry format in Appendix A.

Note that the maskInput property potentially has an effect on editFormats. If you set maskInput to true, its format specification may override the one in editFormats.

mask, numMaskMatch

mask is a property of JCStringValidator and JCDateTimeValidator. You use it to specify the type of character that is admissible at each position. For example, in an instance of a JCTextField with a String validator, the line

TextFieldInstance.setMask("\\Licence \\#: UUU @@@");

results in the following being displayed:

The cursor is placed at the first editable position, where an alphabetic character is expected. The effect of a U in the mask is to convert lower case input to upper case. After three letters are typed, which match the three Us in the mask, the cursor skips over the space, and then is ready to accept three numeric characters, represented by the three "at" signs (@) in the mask. Note that the prompt string, Licence #, contains both a letter L and a number sign. These are mask characters which have special meaning. To use them as character literals, you need to preface them with double backslashes. For a list of the special mask characters and their meaning, see Mask Characters later in this chapter.

numMaskMatch is a property of JCStringValidator. With it, you set the number of characters to match against the mask, going from left to right. This number does not include any literals that you may have embedded between mask characters. If the value is negative, the entire mask will be matched. An example of the use of this property is in a field that is designed to collect an office telephone number and extension. The mask might be

TextFieldInstance.setMask("Phone \\#: (@@@) @@@-@@@@ Ext. @@@@");

If the value of numMaskMatch is set as follows,

TextFieldInstance.setNumMaskMatch(10);

then only the first ten digits are needed for the input to be considered valid, although fourteen digits will be accepted. Note that in the absence of a placeHolderChars string, the field will be blank; the pattern used in setMask() will not appear in the field.

placeHolderChars

You can use the property placeHolderChars to override the appearance of a field when a mask has been used. Notice that in our mask, numMaskMatch example above, the part of the field where the licence plate number is to be typed is blank. You can give the end-user a better idea of what the contents of the field should be by extending the prompt string to appear as follows.

Using a JCTextField with type String as an example, the command

TextFieldInstance.setPlaceHolderChars("Licence #: FLX 999");

results in the following being displayed:

The field now contains characters in the editable part of the field that give the user a good idea of what is expected.

If you use placeHolderChars, it is a good idea to match the mask string character by character. This means that you supply the same number of characters in the placeHolderChars string as there are in the mask string. If the mask string and placeHolderChars string have differing lengths or character placement, the field will use the character spacing of the mask and the display of the placeHolderChars string, which will likely confuse the user.

maskInput

The maskInput property exists for the date and time validators. If this Boolean property is true, the user's input must exactly match the date format that has been specified for the field. If it is false, the validator will attempt to complete a partial date as long as the input matches one of the currently set date formats.

When you use placeHolderChars with Calendar objects, maskInput must be true. The format is then transformed into a non-ambiguous form, and it is possible to use a placeHolderChars string as long as you are aware of the possible pitfall presented by ambiguous date formats. For example, if you use the ambiguous date format h:mm:ss, it is internally converted to hh:mm:ss. Thus, an acceptable placeHolderChars string is shown in the following code fragment:

CalendarComponent.setMaskInput(true);
CalendarComponent.setPlaceHolderChars("HH:MM:SS");

The best approach is to use only non-ambiguous date format strings.

pickList, matchPickList, displayList

pickList is a property which provides a list of values for combo and spin fields with numeric and String data types. You can restrict the choices to just those given in the pick list by setting the Boolean property matchPickList to true. The property displayList provides further control over the way that the field displays its values. By defining a display list, values in the pick list are associated with the corresponding items in the display list. This additional capability is useful if you want to display strings, yet couple them with integer values, in effect forming an associative array. The user sees the array element, and the field reports the index corresponding to that element as the value of the field. The following code snippet shows how:

// create validator
JCIntegerValidator IntVal= new JCIntegerValidator();

// set validator properties

Integer picklist[] = {new Integer(-10), new Integer(-5), 
	new Integer(-1),new Integer(0), new Integer(1), 
	new Integer(5), new Integer(10)};
String[] displaylist = {"minus ten", "minus five", "minus one", "zero",
	"one", "five", "ten"};
IntVal.setPickList(new JCListModel(picklist));
IntVal.setMatchPickList(true);
IntVal.setDisplayList(displaylist);

The code creates a JCIntegerValidator and declares a pick list of seven integer values. Since matchPickList is true, these values would be the only ones capable of being displayed in the field, except that a display list is also declared and set. Thus, instead of seeing the sequence of values from the pick list, -10, -5, -1, 0, 1, 10, in the combo box, the user sees the display list values, "minus ten", "minus five", "minus one", "zero", "one", "five", "ten". The value of the field is the associated integer, not the string that is displayed.

defaultValue

All fields are given a default value when they are created. You may decide to change this value as part of your own initialization of the field, but one way or the other, a field has an initial default value as well as a value. Typically, the default value for numeric fields is zero, for String fields, it is null, and for calendar fields, it is the current date and time. The data member defaultValue is used to hold a representative value for the field that does not get changed by user input or by the validation process. Note that the default value only displays in the field when the JCInvalidInfo.RESTORE_DEFAULT policy is in effect and the user has entered an invalid value. If you use the set the default value in a spin field without setting a value for the field, the field will be blank until the users clicks one of the arrows. The field will then spin from the default value to the next value.

You may wish to replace an invalid input with the default value as a way of providing the user with a reasonable starting place for further data entry. See invalidPolicy below for a description of how the invalidPolicy property is useful in this regard.

isCurrency

The isCurrency property allows you to specify whether a numeric type should be treated as currency. If the property is set to true, the value is displayed in the currency format appropriate to the set locale. The default value for this property is false. Note that if you set the property to true in a integer, short, byte, or long validator, the value will display with zero sub-units and the field will not allow the to user enter any fraction of the currency unit.


InvalidInfo Properties

invalidBackground, invalidForeground, beepOnInvalid

You use these three properties to provide visual and auditory warnings that an attempt has been made to enter invalid data in a field. By default, colors are inherited and beepOnInvalid is true. Examples are:

invalidInfoInstance.setInvalidBackground(Color.red);
invalidInfoInstance.setInvalidForeground(Color.white);
invalidInfoInstance.setBeepOnInvalid(false);

invalidPolicy

This property gives you four choices for the behavior of the field when invalid data is entered.

JCInvalidInfo.SHOW_INVALID is the default value. It leaves the data in the field even after the field loses focus. To highlight the fact that the data is invalid, you can show it in different colors using properties invalidBackground and invalidForeground.

JCInvalidInfo.RESTORE_DEFAULT displays the default value. If the field loses focus, still containing an invalid value, setting invalidPolicy to this parameter causes the field to replace the invalid entry with the default.

JCInvalidInfo.RESTORE_PREVIOUS replaces an invalid entry by the last valid value that was committed in the field.

JCInvalidInfo.CLEAR_FIELD clears a field containing invalid data upon loss of focus. In this case, the field is blank and the value of the field is undefined.


Other Properties

state

state is one of the few read-only properties in JClass Field. Using getState(), you can determine if the value of the field is valid, invalid or indeterminate. An indeterminate value arises when the field is currently being edited, so the validator must defer its decision until editing is complete. A field becomes "under edit" when the user types a key, and remains so until the field loses focus, the user presses the Enter key, or the field is resolved programmatically by the commit() method.

editable

This boolean property lets you decide whether or not a field can be edited via the keyboard. If you are concerned that it will be all too easy for the user to make a mistake if keyboard entry is allowed, you can set this property to false and restrict the user to employing the mouse. The items that you have placed in spin, combo and popup fields contain (presumably) valid choices, so your users are constrained to one of these valid choices. You would set editable to true when the user must supply more generalized and unpredictable information, such as names and addresses.

You can make spin and combo fields extensible by allowing users to type new values into the field, but you are responsible for adding the programming code that adds these new values to the pick list. See Event Programming at the end of chapter 4 for an example of this code. See pickList, matchPickList, displayList for a description of pick lists.

max and min

These properties set the minimum and maximum values of numeric fields. A convenience method, setRange(), allows you to set both properties in a single command. There are examples of its use in the code snippets in Chapter 4. In an IDE only the min and max properties are available.


addValueListener, removeValueListener

Changes to JClass Field are handled by invoking addValueListener(). Just as with any other listener, you supply the code to implement the JCValueListener interface, and add the event handler to the Field, for example:

myField.addValueListener(new MyJCValueListener);

The removeValueListener() method removes the named listener object.


Format Tables

The format strings for date and time validators, the mask characters for the String validator, and number format characters for fields using numeric validators are listed in the next three sections.


Date Formats

Symbol(s)

Meaning

y

Year within the current century (1 or 2 digits)

yy

Year within the current century (2 digits)

yyyy

Year including century (4 digits)

M

Numeric month of year (1 or 2 digits)

MM

Numeric month of year (2 digits)

MMM

Abbreviated month name

MMMM

Full month name

EEEE

Day of the Week (full name)

EE

Day of the Week (abbreviated)

d

Numeric day of month (1 or 2 digits)

dd

Numeric day of month (2 digits)

h

Hour of day (1-12) (1 or 2 digits)

hh

Hour of day (1-12) (2 digits)

H

Hour of day (0-23) (1 or 2 digits)

HH

Hour of day (0-23) (2 digits)

m

Minutes (1 or 2 digits)

mm

Minutes (2 digits)

s

Seconds (1 or 2 digits)

ss

Seconds (2 digits)

a

AM/PM representation

p

AM/PM representation

z

Time zone abbreviation

zz

Time zone abbreviation

zzzz

Time zone (full name)

D

Day in year (1, 2, or 3 digits)

DDD

Day in year (3 digits)


Mask Characters

Symbol

Meaning

#

Any digit, minus sign, comma, decimal point, or plus sign

@

Any digit.

H

Any hexadecimal digit.

U

Any alphabetic character. Lower case characters will be converted to upper case.

L

Any alphabetic character. Upper case characters will be converted to lower case.

A

Any alphabetic character. No case conversion.

*

Any character.

^

An alphanumeric character -- one of the set {0-9a-zA-Z}

\\

The next character that follows is to be treated as a literal, even if it is one of the above characters.


Number Format Characters

Symbol

Meaning

0

Any digit, zeros show as zero.

#

A digit, zero shows as absent.

.

Placeholder for decimal separator.

,

Placeholder for grouping separator.

E

Separates mantissa and exponent for exponential formats. JDK 1.2 or greater.

;

Separates formats.

-

Locale-specific negative prefix.

X

Any other characters can be used in the prefix or suffix.

'

Used to quote special characters in a prefix or suffix.

other

Appears literally in the output.

Notes:

If there is no explicit negative sub-pattern, - is prefixed to the positive form. That is, "0.00" alone is equivalent to "0.00;-0.00".

Illegal formats, such as "#.#.#" or mixing '-' and '*' in the same format, will cause a ParseException to be thrown. From that ParseException, you can find the place in the string where the error occurred.

The grouping separator is commonly used for thousands, but in some countries for ten-thousands. The interval is a constant number of digits between the grouping characters, such as 100,000,000 or 1,0000,0000.

If you supply a pattern with multiple grouping characters, the interval between the last one and the end of the integer is the one that is used. So, the grouping interval for each of "#,##,###,####", "######,####'', and "##,####,####" is four.


Property Summaries

The first property list shown below details the properties common to all fields. The following lists are organized according to properties contained in the three main validators of the JClass Field components and the InvalidInfo and ValueModel objects. You can use these lists for quick reference to the properties that a particular object possesses; however, the best reference is the API for a particular component.

These lists differ from the single list given in Appendix A, JClass Field Property Listings, where the property is listed and the JClass Field types which can be customized by it are listed in the second column.

A small number of properties are read-only variables, and therefore only have a get method. These properties are marked with a "(G)" following their property name.


Properties for JClass Field Components

Property Type Default

about

String

com.klg.jclass.field 4.5.0

background

Color

inherited

doubleBuffered

boolean

false

editable

boolean

true

enabled

boolean

true

font

Font

inherited

foreground

Color

inherited

maximumSize

Dimension

dynamic

minimumSize

Dimension

dynamic

name

String

null

preferredSize

Dimension

dynamic

required

boolean

true

selectOnEnter

boolean

false

state (G)

int

N/A

toolTipText

String

null


Properties for Numeric and IPAddress Validators

Property Type Default

allowNull

boolean

false

casePolicy

int

JCValidator.AS_IS

continuousScroll

boolean

false

currency

boolean

false

currencyLocale

Locale

locale dependent

currencySymbol (G)

String

locale dependent

defaultValue

Object

0

displayList1

String

null

displayPattern

String

locale dependent

editPattern

String

Byte, Short, Integer, Long: 0

Float, Double, BigDecimal: 0.###

firstValidCursorPosition
(G)

int

usually 0, but dependent on mask set

increment

Number

1

invalidChars

String

null

locale

Locale

Locale.getDefault

matchPickList

boolean

true

max

int

type dependent

min

int

type dependent

pickList

ListModel

null

pickListIndex(G)

Object

N/A

range (S)

int

type dependent

spinPolicy

int

JCValidator.SPIN_FIELD

useIntlCurrencySymbol

boolean

false

validChars

String

null


Properties for JCStringValidator

Property Type Default

allowNull

boolean

false

casePolicy

int

JCValidator.AS_IS

continuousScroll

boolean

false

defaultValue

Object

null

firstValidCursorPosition
(G)

int

0

invalidChars

String

null

locale

Locale

Locale.getDefault

mask

String

null

maskChars

String

#@HULA*^\

matchPickList

boolean

true

numMaskMatch

int

-1

pickList

ListModel

null

pickListIndex(G)

Object

N/A

placeHolderChars

String

null

spinPolicy

int

JCValidator.SPIN_WRAP

validChars

String

null


Properties for Date/Time Validators

Property Type Default

allowNull

boolean

false

casePolicy

int

JCValidator.AS_IS

continuousScroll

boolean

false

defaultDetail

int

medium

defaultEditFormats(G)

String

N/A

defaultFormat(G)

String

N/A

defaultValue

Object

null

editFormats

String

locale dependent

firstValidCursorPosition
(G)

int

0

format

String

locale dependent

increment

int

1

invalidChars

String

null

locale

Locale

Locale.getDefault

mask

String

null

maskChars

String

#@HULA*^\\

maskInput

boolean

true for JCSpinField with any date type; false otherwise

matchPickList

boolean

true

milleniumThreshold

int

69

numMaskMatch

int

-1

parsedMask(G)

String

N/A

pickList

ListModel

null

pickListIndex(G)

Object

N/A

placeHolderChars

String

null

spinPolicy

int

JCValidator.SPIN_SUBFIELD

timeZone

java.util.

TimeZone

locale dependent

validChars

String

null


InvalidInfo Properties

Property Type Default

beepOnInvalid

boolean

true

invalidBackground

Color

null

invalidForeground

Color

null

invalidPolicy

int

JCInvalidInfo.SHOW_INVALID


ValueModel Properties

Property Type Default

value

Object

null

valueClass(G)

java.lang.Class

N/A


Exploring the Form Demo

JClass Field includes more extended sample programs. For example, the Form demo implements a complete data-entry form containing all of the elements needed by such an application. The code is located in the demos\field\form directory. To run it, enter "java demos.field.form.Form" at a command prompt.

 

This program uses two additional classes of JClass Field. The following sections describe them.


JCPromptHelper

JCPromptHelper extends the function of the toolTipText property. This class allows you to set a label in the specified container that takes the value of the tool tip text associated with the field in focus.

For example, in the illustration above, the text above the console output area is the tool tip text for the field containing the cursor, Last Name.


JCFormUtil

The class JCFormUtil provides several useful methods for collecting different sets of information based on the JClass Field components in a container.

The form program demonstrates all of these functions. You can view the return values in your command window. In addition, demos.field.form.Form has a scrollable text window where you can view the values directly. It also displays messages that inform the user of invalid input and incomplete entries.


1. Only byte, short, integer and long types possess these properties.


[Home]   [Contents]   [Index]   [Javadoc] Comments on the documentation?
Please send them to jclass_docs@klgroup.com
[Previous]   [Next]
[Frames]    [No Frames]

Copyright © 1999-2000 KL Group Inc.