[Home] [Contents] [Index] [Javadoc] | ![]() [Frames] [No Frames] |
[Previous] [Next] |
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
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.
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:
![]() |
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.
The following table lists the data types handled by JClass Field:
JCField DataType | Stored As |
---|---|
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.
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 | ||||
---|---|---|---|---|---|---|---|---|---|
|
|
|
|
||||||
|
|
|
|
||||||
|
|
|
|
||||||
|
|
|
|
||||||
|
|
|
|
||||||
|
|
|
|
||||||
|
|
|
|
||||||
|
|
|
|
||||||
|
|
|
|
||||||
|
|
|
|
||||||
|
|
|
|
||||||
|
|
|
|||||||
|
|
|
|||||||
|
|
|
|
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.
This section provides a brief description of the standard JClass Field components combined with each appropriate data type, and the databound components.
Data Type(s) | Description | |
---|---|---|
The spin field increments by integral values, between preset minimum and maximum values. Example of an integer type in a spin field:
|
||
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:
|
||
The String data type in a Example of a string type in a spin field:
|
||
|
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:
|
|
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:
|
Data Type(s) | Description | |
---|---|---|
|
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:
|
|
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:
|
||
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:
|
Data Type(s) | Description | |
---|---|---|
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:
|
||
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:
|
Data Type(s) | Description | |
---|---|---|
|
Numeric values in a label field can be displayed in different formats. Example of an integer type in a label field:
|
|
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:
|
||
|
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:
|
|
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:
|
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 |
---|---|
|
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.
JClass Field components are comprised of four elements:
JCTextField
, JCComboField
, JCSpinField
, JCPopupField
, or JCLabelField
.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.
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.
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 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.
![]() |
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.
![]() |
The second diagram shows the hierarchy of classes within 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.
![]() |
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
.
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 |
The field has been edited, as signalled by the end-user pressing the Return key or leaving the field or the |
|
Most key actions are intuitive, however there are some circumstances that may need explanation.
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.
![]() |
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(); } }
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.
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.
![]() |
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.
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.
The following lists the steps required to edit the properties for a JClass Field Bean:
All the editable Bean properties (and some read-only properties as well) appear in the Properties window.
DataProperties
property to invoke a property customizer that contains the value, validator and invalidinfo object properties.
![]() |
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 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] |