Appendix  C

Porting JClass 3.6.x Applications

Key Concept Differences  Code Differences  Property Changes

Porting Guidelines  Event Handling Changes

There have been significant structural changes to JClass Field beginning in its 4.x version. These modifications allow more flexibility and control over the composition of fields. Although the changes are noteworthy, you can easily convert any code created with 3.6.x versions to version 4.x and higher. The following sections will describe how to upgrade your code to JClass Field 4.5 and higher.

C.1 Key Concept Differences

In earlier versions of JClass Field, each field consisted of a visual component and a validator together. The validator portion determined what type of data the field expected. The names of the fields indicated their visual aspect and supported data type. For example, a text field that contained integers and a text field that held String values were named JCIntTextField and JCStringTextField respectively.

Now the five basic styles of visual components, which are represented by one of JClass Field's standard Beans: JCTextField, JCSpinField, JCComboField, JCPopupField, and JCLabelField, are separated from the validators and the supported data types. To use a field, you must associate it with a validator and declare an appropriate value model. The following table lists the a few examples of the combination of components, validators, and value models in JClass Field 4.x that are equivalent to fields in earlier versions:

Field in JClass Field 3.6.3 and earlier	Equivalent Field in JClass Field 4.x
JCIntTextField	JCTextField + JCIntegerValidator + IntegerValueModel
JCTimeSpinField	JCSpinField + JCTimeValidator + TimeValueModel
JCStringComboField	JCComboField + JCStringValidator + StringValueModel
JCCalendarPopup	JCPopupField + JCDateTimeValidator + CalendarValueModel
JCCurrencySpinField	JCSpinField + JCDoubleValidator + DoubleValueModel + isCurrency property set to true

You can duplicate all the fields contained in earlier versions by selecting the corresponding field, validator, and value model. In fact, you can create even more fields since JClass Field 4.x and higher expands the list of supported validators to include java.lang.byte, java.lang.short, java.lang.long, java.lang.float, java.math.BigDecimal, java.sql.date, and java.sql.timestamp, and introduces a new GUI component, JCLabelField. This new field can be used to simulate a heading or to display uneditable data.

C.2 Code Differences

The following table shows the differences in code between JClass Field 4.x and higher, and previous versions for a text field containing a String value.

JClass Field 3.6.3 and earlier	JClass Field 4.0 and higher
JCStringTextField	JCTextField + JCStringValidator + StringValueModel
1 JCStringTextField text1 = new JCStringTextField(); 2   3 text1.setMask("(@@@) @@@-@@@@"); 4 text1.setPlaceHolder     Chars("(___) ___-____"); 5 text1.setValue("4165941026");	1 JCTextField text1 = new JCTextField();   2 JCStringValidator sv = new JCStringValidator(); 3 sv.setMask("(@@@)@@@-@@@@");   4 sv.setPlaceHolderChars("(___)___-____"); 5 text1.setValueModel(new StringValueModel("4165941026")); 6 text1.setValidator(sv);

C.2.1 Converting Your Code

This section breaks down the above code listings and gives a line-by-line description of the differences.

Line 1	Similar for both versions; it simply creates the field, text1.
Line 2	Declares the validator, in version 4.x and higher.
Line 3	Sets the mask property for the field in earlier versions and for the validator for version 4.x and higher.
Line 4	Sets the placeHolderChars property for the field in earlier versions and for the validator for version 4.x and higher.
Line 5	Sets the initial value of the field, using the value property in earlier versions and using the value model declaration in version 4.x and higher. Although you do not have to set the value using the value model, the value model declaration and association with the field is necessary.
Line 6	Associates the validator with the field in version 4.x and higher.

C.3 Property Changes

Since the introduction of the validator and invalidInfo objects, the properties have been divided between these two objects and the field component, which in earlier versions contained all the properties. The following table shows how the JClass Field 4.x and higher properties are allocated.

Validator Properties	Invalid Properties	Field Component Properties (same as earlier versions)
allowNull   casePolicy   continuousScroll   currency   currencyLocale   currencySymbol (G)   defaultDetail   defaultEditFormats (G)   defaultFormat (G)   defaultValue   displayList   displayPattern   editFormats   editPattern   firstValidCursorPosition (G)   format   increment   invalidChars   iPValidators   locale   mask   maskChars   maskInput   matchPickList   max   milleniumThreshold   min   numMaskMatch   parsedMask (G)   pickList   pickListIndex (G)   placeHolderChars   range (S)   spinPolicy   timeZone   useIntlCurrencySymbol   validChars	invalidPolicy   invalidBackground   invalidForeground   beepOnInvalid	about   background   doubleBuffered   editable   enabled   font   foreground   maximumSize   minimumSize   name   preferredSize   required   selectOnEnter   state (G)   toolTipText

C.4 Porting Guidelines

The following list gives a general outline of the steps you should follow to port your code to JClass Field 4.x and higher from earlier versions.

• Determine the field, value model, and validator that correspond to your existing field. Create each of these objects and associate the value model and validator with the field.
• Separate any JClass Field properties you use into field component, validator and invalid properties.
• If you have any invalid properties, declare the field's invalidInfo object and set the properties using the new invalidInfo.
• Set any other properties using the field component or validator objects.

C.5 Event Handling Changes

JClass Field events have also undergone significant change in version 4.x and higher.

The event listener that receives the events generated by the four editable Fields is now called JCValueListener instead of JCFieldListener. Its methods are valueChanging() and valueChanged() instead of valueChangedBegin(), valueChangedEnd(), and stateIsInvalid.

Changes to any one of the Fields are handled by invoking addValueListener(). You supply the code to implement the JCValueListener interface. To register the method see addValueListener, removeValueListener, in Chapter 2.

The methods of the JClass Field event listeners are compared below:

JCFieldListener: Event Methods (earlier versions)	JCValueListener: Event Methods (JClass Field 4.x and higher)
JCFieldListener.valueChangedBegin	JCValueListener.valueChanging()
JCFieldListener.valueChangedEnd	JCValueListener.valueChanged().
JCFieldListener.stateIsInvalid	no equivalent (see below)

Although the stateIsInvalid() method is not available in JCValueListener, you can use a Field component's addPropertyChangeListener() method to determine changes to the state of a field.