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

1:
JClass Field Basics

Terminology * Overview of GUI Components and Field Data Types

JClass Field Components and Data Types * The Structure of a JClass Field Component

Validators * Events * Keystroke Actions

JClass Field Inheritance Hierarchy * An Example Program

Internationalization

The following topics cover basic information that anyone who intends to create JClass Field objects should be familiar with. After you can recognize the basic JClass Field processes and vocabulary, you can begin using JClass Field's objects and data validators to simplify the development of your data entry applications.


Terminology

There are five basic graphical user interface (GUI) styles of visual components in JClass Field: Text, Spin, Combo, Popup and Label. Each of these styles is represented by one of Field's standard Beans: JCTextField, JCSpinField, JCComboField, JCPopupField, and JCLabelField.

One or more of the data types supported by JClass Field are handled by each of these Beans. Regardless of what data type the Bean handles, the name of the field is the same.

In all, there are five standard field components and five data-bound components. The following BeanBox illustration shows the standard JClass Field Bean components:

 


Overview of GUI Components and Field Data Types


JClass Field's GUI components

Your choice of the type of visual object will be based in part on the type of validation you wish to perform on the data. The following image shows the five types of visual objects in JClass Field:

The upper and lower limits on the range can be determined by predefining min and max values. The intermediate values are controlled by the increment property.
A pick list offers all the possible values that the spin field can contain. This has precedence over the increment method.
Only one value at a time is shown in the spin field. Up and down-arrow buttons are used to change the value by "spinning." The spin field has access to the same validator functions as the text field.


Data Types Handled by JClass Field

The following table lists the data types handled by JClass Field:

JCField DataType Stored As

Byte

java.lang.Byte

Integer

java.lang.Integer

Short

java.lang.Short

Long

java.lang.Long

Float

java.lang.Float

Double

java.lang.Double

BigDecimal

java.math.BigDecimal

String

java.lang.String

Calendar

java.util.Calendar

Date

 

SqlDate

java.util.Date

or

java.sql.Date

SqlTime

java.sql.Time

SqlTimeStamp

java.sql.TimeStamp

JCIPAddress

com.klg.jclass.util.

JCIPAddress

Note that the Date data type is stored as two different representations. You can select either type at design time or you can set the type programmatically.

The Sql data types are usually used when databinding to a database.


GUI Component Support for Data Types

The following table shows the commonly used data types and GUI component combinations:

Data Type Text Field Spin Field Combo Field Popup Field Label Field

java.lang.Byte

 

 

 

 

 

java.lang.Short

 

 

 

 

 

java.lang.Integer

 

 

 

 

 

java.lang.Long

 

 

 

 

 

java.lang.Float

 

 

 

 

 

java.lang.Double

 

 

 

 

 

java.math.BigDecimal

 

 

 

 

 

java.lang.String

 

 

 

 

 

java.util.Calendar

 

 

 

 

 

java.util.Date

 

 

 

 

 

java.sql.Date

 

 

 

 

 

java.sql.Time

 

 

 

 

 

java.sql.Timestamp

 

 

 

 

 

com.klg.jclass.util.JCIPAddress

 

 

 

 

 

In actuality, you can use any data type with any GUI component; however, some combinations may not be as useful as others. For example, a popup field that uses the byte data type will not display a popup.


JClass Field Components and Data Types

This section provides a brief description of the standard JClass Field components combined with each appropriate data type, and the databound components.


JCTextField

Data Type(s) Description

java.lang.Byte
java.lang.Integer
java.lang.Short
java.lang.Long
java.lang.Double
java.lang.Float
java.math.BigDecimal

Numeric values in a JCTextField are displayed while in edit mode using an edit pattern, and displayed in a possibly different format after editing is complete. The field may be editable, in which case values may be typed in, or it may be set to simply display a value supplied by your program.

Example of an integer type in a text field:

java.lang.String

The String type in a text component permits entry of data that can be validated using a mask. For instance, the field may be for phone numbers, whose formats follow a fixed rule. Optionally, place-holder characters may be supplied to indicate the type of data that the field is programmed to accept. The user types over these characters using them as a guide when typing in valid data.

Example of a String type in a text field:

java.util.Calendar
java.util.Date
java.sql.Date
java.sql.Time
java.sql.Timestamp

The date and time data types in a JCTextField presents the date in a locale-specific format. The time text field may be programmed to accept any of a set of standard time formats, such as "h:mm:ss a", which stands for colon-delimited hours, minutes, and seconds entries followed by an "a" or a "p," standing for "AM" or "PM." A property (maskInput) can be set so that the component insists on a pre-defined format for input, and dates cannot be entered in any other format.

Example of a calendar type in a text field:

com.klg.jclass.util.
JCIPAddress

The IP address data type is created to allow validation of IP addresses in period-delimited subfields.

Example of a IP address data type in a text field:


JCSpinField

Data Type(s) Description

java.lang.Byte
java.lang.Integer
java.lang.Short

The spin field increments by integral values, between preset minimum and maximum values.

Example of an integer type in a spin field:

java.lang.Double
java.lang.Float
java.math.BigDecimal

Values may be selected by using the spin arrows or by typing in the field. After a value has been entered, it can be checked to ensure that it lies in the acceptable range. Typically, the arrow buttons are be disabled when the top or bottom of the list is reached, indicating that there are no more data items in that direction.

Example of a double type in a spin field:

java.lang.String

The String data type in a JCSpinField is useful for providing a list of names or other strings that can be accessed by spinning. By default the action of the spinners is set so that the data is accessible as if it were arranged in a continuous loop.

Example of a string type in a spin field:

java.util.Calendar
java.util.Date
java.sql.Date
java.sql.Time

This component permits the selection of other values by using the spin arrows in conjunction with the mouse. The sub-field is selected using the mouse pointer, then the arrow buttons are used to change the value of this sub-field.

Example of a calendar type in a spin field:

com.klg.jclass.util.
JCIPAddress

The IP address data type is created to allow validation of IP addresses in period-delimited subfields.

Example of a IP address data type in a spin field:


JCComboField

Data Type(s) Description

java.lang.Byte
java.lang.Integer
java.lang.Short
java.lang.Long
java.lang.Float
java.lang.Double
java.math.BigDecimal

This combo field component can show choices expressed in textual form as well as numeric. No matter how the items in the combo field appear, they are associated with numeric values. In the example shown below, the item "Mr." has a value of 0, and "Mrs." has a value of 1.

Example of an integer type in a combo field:

java.lang.String

The String type in a combo field behaves similarly to its integer relative except that the values that appear in the field are the actual values.

Example of a string type in a combo field:

com.klg.jclass.util.
JCIPAddress

The IP address data type is created to allow validation of IP addresses in period-delimited subfields.

Example of a IP address data type in a combo field:


JCPopupField

Data Type(s) Description

java.util.Calendar

The Calendar data type displays the time and date, along with an arrow button in the popup component. Clicking on the arrow button produces a pop-down calendar with spin fields for the year, month, hour, minute, second, and meridiem. When the year and month fields respond to mouse clicks by incrementing or decrementing their values each time an arrow button is pressed, the calendar display updates accordingly by showing the days of the month.

The default value for all calendar components is the current date and time.

Example of the calendar type in a popup field:

java.util.Date
java.sql.Date

This combination is similar to the calendar type and popup field, except that there are no time spinners in this component, and it contains no time information. Month and year values are changed using the two spin boxes at the top of the calendar, and the day of the month is selected by clicking on it in the calendar.

Example of the date type in a popup field:


JCLabelField

Data Type(s) Description

java.lang.Byte
java.lang.Integer
java.lang.Short
java.lang.Long
java.lang.Double
java.lang.Float
java.math.BigDecimal

Numeric values in a label field can be displayed in different formats.

Example of an integer type in a label field:

java.lang.String

String values can be used in label fields to simulate headings or to display a constant value.

Example of a string type in a label field:

java.util.Calendar
java.util.Date
java.sql.Date
java.sql.Time

Calendar data types in a label field can display dates and times in locale-specific and standard formats. You can also set the format to your own specifications.

Example of a calendar type in a label field:

com.klg.jclass.util.
JCIPAddress

The IP address data type is created to allow validation of IP addresses in period-delimited subfields.

Example of a IP address data type in a label field:


Data Bound Components

JClass Field includes additional components that can be bound to a column in a JDBC or IDE-based database data source. These components are contained in separate JAR files for each development environment. See the Getting Started with JClass booklet for more information.

JCField Component Description

DSdbTextField (JClass DataSource)
JBdbTextField (Borland JBuilder)
VCdbTextField (VisualCafé)

DSdbSpinField (JClass DataSource)
JBdbSpinField (Borland JBuilder)
VCdbSpinField (VisualCafé)

DSdbComboField (JClass DataSource)
JBdbComboField (Borland JBuilder)
VCdbComboField (VisualCafé)

DSdbPopupField (JClass DataSource)
JBdbPopupField (Borland JBuilder)
VCdbPopupField (VisualCafé)

DSdbLabelField (JClass DataSource)
JBdbLabelField (Borland JBuilder)
VCdbLabelField (VisualCafé)

JClass Field data bound Beans have virtually the same interactive behavior and properties as JClass Field's standard Beans. They are designed to be bound to a column in a JClass DataSource, Borland JBuilder, or VisualCafé data source component. Once bound, the data type is read from the database query results.

 

Note: "DSdb" components only bind with data sources included with JClass DataSource; "JBdb" components only bind with Borland JBuilder 3 data sources; "VCdb" components only bind with VisualCafé 3.0d or later data sources.


The Structure of a JClass Field Component

JClass Field components are comprised of four elements:

A field starts with the visual component. Each of the three objects that define the field's properties is contained within this visual component. The first object, the value model, specifies the data type of the values the field will hold. Once you declare the value model, the appropriate validator to support the data type is automatically determined. You can then declare that validator. The InvalidInfo object is automatically created when the field is declared.

You can create a field in several ways. If you want a standard field with the minimum customization, you can use the constructor that requires the data type class, for example, JCComboField(java.util.Double.class c). This way, the selection of the data type automatically creates the correct value model and validator. To access the properties in the validator, you would use the getDataProperties() method. If you want slightly more control over the field, you can declare the value model and validator separately from the field. See Example Programs in chapter 4 for an example of this code.


Validators

JClass Field validators are used to ensure, as much as possible, the integrity of the information in the field. Initially they parse the text in the field and create an object to be examined by the validator. Once the validity of the object is established, the validator formats the object into appropriate text for the field. You can use validators to enforce a standard format for data fields, and you can prevent the typing of unwanted variants, such as "three" instead of "3." Refer to The Validation Process section below.

JClass Field validators are available for all of the data types. Therefore, you should assign the component a validator that is appropriate for the type of information that you want the data field to contain.

Note that the JCDateTimeValidator supports both the java.util.Calendar data type and the java.sql.Timestamp data type. The JCDateValidator supports both java.util.Date and java.sql.Date. All other validators correspond exactly to the names of the data types they support.


Validator Functions

The following list describes some of the functions supported by the validators. For a more detailed description of the supported functions see The Validator Property in chapter 3.

The way that numeric data is input and displayed can be modified to suit the circumstances. You can choose to display negative numbers by enclosing them in brackets, or you can add a fixed text string to the numeric field.
This allows you to display dates using any of the standard display formats, and you can choose an input format that differs from the display format if you wish.
You can set limits on the range of numeric data the field will accept.
There are times when you wish to restrict input to a short list of valid characters, and other times when there are only a few characters you wish to prohibit. Having both ways of setting character lists lets you choose the one that is shorter and more descriptive.
A field is given a default value when it is created. You might want to change this value, or you might not want a default to appear at all when the field is created. This property can also be used as a reference when a user types in invalid data.


The Validation Process

The following diagram shows the steps of parsing and validation that occur when a user enters text in a field. When the text is committed or the field loses focus, this process will be performed.

You can intercept the new value between the parse and validation processes. You might want to change the value a user has entered using the JCValueModel.SetNewValue() method, or simply monitor the user's data.

 

The validation and parsing process


JClass Field Inheritance Hierarchy

JClass Field 4.5's visual components are subclassed entirely from Swing. In previous versions of Field, some components were subclassed from JClass BWT. Using Swing and Field 4.5, you can do everything without BWT.

The following two diagrams show the inheritance hierarchy for the JClass Field 4.5 Bean components. The first diagram shows the inheritance of the basic classes in JClass Field.

JClass Field's Component Classes - the basic classes

The second diagram shows the hierarchy of classes within JClass Field.

JClass Field's Component Classes - classes inside JClass Field

The following diagram shows the inheritance properties for JClass Field's Validators. The object at the top signifies java.lang.Object, from which all JCField's validators are subclassed.

JClass Field's Validator Classes


Events

Events are a mechanism used to propagate state change notifications between a source object and one or more target listener objects. Events are typically used within windowing toolkits for delivering notifications of such things as mouse or keyboard actions, or other programmatically-defined actions.

Bean-compliant JClass products (like JClass Field) provide the means for an application to be notified when an event occurs through event listeners. It works as follows: if a component is acted upon by the user or from within the program, a JCFooEvent is fired (where "Foo" is the place holder for the actual event name). The JCFooListener (which has been registered by calling addFooListener() on the component) receives the instance and enacts the action to be taken. The developer uses the JCFooListener to define what action or actions should take place when it receives the JCFooEvent.

JClass Field Events

The event listener that receives the events generated by the four editable Fields is called JCValueListener. Its methods are valueChanging() and valueChanged(). 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 3.

The methods of the JClass Field event listener are described below:

Event Methods Description

JCValueListener.

valueChanging()

The field has been edited, as signalled by the end-user pressing the Return key or leaving the field or the setValue() method has been called programmatically, and the new value is about to replace the old value. valueChanging() is invoked whenever the value is about to change. Catching this event allows a change of the new value at this point if desired.

JCValueListener.

valueChanged()

The value has been changed.


Keystroke Actions

Most key actions are intuitive, however there are some circumstances that may need explanation.


An Example Program

Now that you have seen an overview of JClass Field's objects and validators, here is a sample program that illustrates several features of some JClass Field components.

You can create fields for your applications programmatically, or in an IDE. Either way, you are using the same Bean. The following sections describe building a field using an IDE. For more detailed information about the process of creating fields, with an IDE or programmatically, see Building a Field in chapter 4.

The class Examples contains a main method and an init method and, therefore, it is both an applet and a program. The file is located in the examples directory. If your browser does not support Java 1.1, you can still run Examples. When run using the command java examples.field.Examples, the program produces the output shown in the figure below.

 

JClass Field examples

Here is the program code:

package examples.field:
     
import com.klg.jclass.field.JCTextField;
import com.klg.jclass.field.JCComboField;
import com.klg.jclass.field.JCSpinField;
import com.klg.jclass.field.validate.*;
import com.klg.jclass.util.swing.JCExitFrame;
import com.klg.jclass.util.value.*;
import com.klg.jclass.field.JCInvalidInfo;
import com.klg.jclass.util.swing.JCListModel;
     
import javax.swing.*;
import javax.swing.border.TitledBorder;
     
import java.awt.GridLayout;
import java.awt.BorderLayout;
import java.awt.Color;
import java.util.Calendar;
     
public class Examples extends JApplet {
     
protected JCTextField text1, text2, text3, text4;
protected JCComboField combo1; 
protected JCSpinField spin1; 
     
public void init() {
     
     // set the layout
          getContentPane().setLayout(new BorderLayout());	
     
     // place all the text fields in a panel
     JPanel p = new JPanel();
     getContentPane().add(p, BorderLayout.CENTER);
     p.setLayout(new GridLayout(5,2));
     p.setBorder(new TitledBorder("JClass Field Examples"));
     
     //
     // Example of a JCTextField using JCStringValidator
     //     with a mask set
     //
     p.add(new JLabel("String JCTextField: "));
     p.add(text1 = new JCTextField());
     
     // create the validator
     JCStringValidator sv1 = new JCStringValidator();
     
     // set the validator properties
     sv1.setMask("\\Licence \\#: UUU @@@");	
     sv1.setPlaceHolderChars("Licence #: FLX 999");
     sv1.setAllowNull(false);
     
     // set the value model and validator
     text1.setValueModel(new StringValueModel());
     text1.setValidator(sv1);
     
     // 
     // Example of a JCTextField using JCStringValidator
     //
     p.add(new JLabel("String JCTextField: "));
     p.add(text2 = new JCTextField());
     
     // create validator
     JCStringValidator sv2 = new JCStringValidator();
     
     // set validator properties
     sv2.setMask("AA @@@@@");
     sv2.setPlaceHolderChars("CA 90210");
     sv2.setAllowNull(true);
     
     // set the value model and validator
     text2.setValueModel(new StringValueModel());
     text2.setValidator(sv2);	
     
     //
     // Example of a JCTextField using JCDoubleValidator
     //     with currency property
     //
     p.add(new JLabel("Double JCTextField (currency): "));
     p.add(text3 = new JCTextField());
     
     // create validator
     JCDoubleValidator cv = new JCDoubleValidator();
     
     // set validator properties
     cv.setAllowNull(true);
     cv.setCurrency(true);
     cv.setDefaultValue("0");
     
     // set the invalidinfo properties
     JCInvalidInfo ii1 = text3.getInvalidInfo();
     ii1.setInvalidPolicy(JCInvalidInfo.CLEAR_FIELD);
     
     // set the value model, invalidinfo and validator
     text3.setValueModel(new DoubleValueModel(new Double(100.00)));
     text3.setInvalidInfo(ii1);
     text3.setValidator(cv);
     
     // 
     // Example of a JCComboField using JCIntegerValidator
     //
     p.add(new JLabel("Integer JCComboField:"));
     p.add(combo1 = new JCComboField());
     combo1.setEditable(false);
     
     // create validator
     JCIntegerValidator iv = new JCIntegerValidator();
     
     // set validator properties
     Integer[] int_values = {new Integer(1), new Integer(2), 
          new Integer(3), new Integer(4)};
     String[] display = {"0 - 25", "26 - 50", "51 - 75", "75 - 100"};
     iv.setAllowNull(true);
     iv.setPickList(new JCListModel(int_values));
     iv.setDisplayList(display);
     
     // set the value model and validator
     combo1.setValueModel(new IntegerValueModel());
     combo1.setValidator(iv);	
     combo1.setSelectedIndex(0);
     
     // 
     // Example of a JCSpinField using JCTimeValidator
     //
     p.add(new JLabel("Time JCSpinField: "));
     p.add(spin1 = new JCSpinField());
     
     // create validator
     JCTimeValidator tv = new JCTimeValidator();
     
     // set validator properties
     tv.setMaskInput(true);
     tv.setAllowNull(true);
     
     // set value model and validator
     spin1.setValueModel(new CalendarValueModel(
          Calendar.getInstance()));
     spin1.setValidator(tv); 
     
}
public static void main(String[] args) {
     JCExitFrame frame = new JCExitFrame("JCField Examples");
     Examples t = new Examples();
     t.init();
     frame.getContentPane().add(t);
     frame.pack();
     frame.show();
}
}


Programming the Example

The five objects reside in a container and are introduced on the left by explanatory text labels. Neither the container itself nor the explanatory text is part of JClass Field, but they illustrate how JClass Field components and other JClass components are used with standard Java objects to achieve a desired result.

The setMask() method specifies the general format for any changes to the field. In the case of the text1 object, the mask specifies that entered data will be validated against a pattern matching a North American license plate number. The @ symbol specifies that only digits are allowed in each of these positions and the U symbol specifies that only alphabetic characters are allowed in these positions. Any lowercase letters entered will be converted to uppercase.

The mask for text2 specifies two letters followed by five digits. In this example, the setPlaceHolderChars() method displays a zip code in the field. This is not a default, but a prompt for the appropriate type entry.

The third object shows a default value of $100.00. This shows the use of a text field with type double and the setCurrency() method set to true. The field also uses the setInvalidPolicy() method, which is contained in the InvalidInfo object, to clear the field if the user enters an amount that is out of range. The range of valid values is determined by the setRange() method.

The field, combo1, uses the methods setPickList() and setDisplayList() to provide the user with meaningful choices while still using the type integer for the field value's data type.

The last object is a spin field that allows the user to change the time value. As for all objects with date or time types, the default, if none is set explicitly, is the current date and time.


The Property Sheet

It is possible to examine and experiment with the component properties of the JClass Field objects using the Bean Development Kit1 (BDK) or any IDE. You can use the Property sheet to change the properties of the JClass Field component under consideration.

 

A JClass TextField component's properties as seen in the Property sheet

The association between the property sheet and the design is dynamic, so any changes you make are automatically applied to the component in the BeanBox. Because the changes are immediately displayed as you edit properties, you can see how a change affects the JClass Field component without leaving the property sheet. You can continue to make changes and observe the results.


Using the Property Sheet

The following sections illustrate some steps for using the property sheet to customize the properties of a JClass Field Bean. You may wish to launch an appropriate program and execute the steps as they are described.

In the design window, click the JClass Field component you wish to customize. The property sheet's contents change to correspond to the component selected, as shown in the previous illustration.


Editing JClass Field Properties

The following lists the steps required to edit the properties for a JClass Field Bean:

  1. In the design window, select the JClass Field component that you want to edit.
  2. All the editable Bean properties (and some read-only properties as well) appear in the Properties window.
  3. Double click on the DataProperties property to invoke a property customizer that contains the value, validator and invalidinfo object properties.
  4. Before you can set the desired properties, you must select a data type from the list on the left of the DataProperties editor. Then you can customize the field using the properties in the Value, Validator and Invalid tabs of the DataProperties editor.
  5. When you make changes in the DataProperties editor, you must click Apply and then Done before the changes will be displayed.
  6. The property customizer of a JClass Field component
  7. Some properties, such as about, are read-only. They are included in the property sheet as information only. For example, double clicking on the about property will display the JClass help information. There is another read-only property, called state, that is used to describe whether the current contents of the field are valid, invalid, or in the process of being changed. Properties listed in Appendix A with a "(G)" after the property name have only a get method.

By now you should have a good idea of what JClass Field has to offer. The next chapter will explain in more detail the properties of the JClass Field components.


Internationalization

Internationalization is the process of making software that is ready for adaptation to various languages and regions without engineering changes. JClass products have been internationalized.

Localization is the process of making internationalized software run appropriately in a particular environment. All Strings used by JClass that need to be localized (that is, Strings that will be seen by a typical user) have been internationalized and are ready for localization. Thus, while localization stubs are in place for JClass, this step must be implemented by the developer of the localized software. These Strings are in resource bundles in every package that requires them. Therefore, the developer of the localized software who has purchased source code should augment all .java files within the /resource/ directory with the .java file specific for the relevant region; for example, for France, LocaleInfo.java becomes LocaleInfo_fr.java, and needs to contain the translated French versions of the Strings in the source LocaleInfo.java file. (Usually the file is called LocaleInfo.java, but can also have another name, such as LocaleBeanInfo.java or BeanLocaleInfo.java.)

Essentially, developers of the localized software create their own resource bundles for their own locale. Developers should check every package for a /resources/ directory; if one is found, then the .java files in it will need to be localized.

For more information on internationalization, go to: http://java.sun.com/products/jdk/1.2/docs/guide/internat/index.html.

 


1. Instructions on loading and running the BeanBox can be found online at http://java.sun.com/beans/bdk_download.html.


[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.