  
|
1
JClass Field Basics
Terminology
Overview of GUI Components and Field Data Types
JClass Field Components and Data Types
Events
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.
1.1 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, andJCLabelField, respectively.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:
1.2 Overview of GUI Components and Field Data Types
1.2.1 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:
- A text field is a visual component which displays a single piece of alphanumeric data entered by the user. The contents of the field and the position of the cursor within the field are under program control. You can validate all types of data in this field.
- A spin field allows the user to spin through a range of values. The range of values shown in the spin field is determined by one of two mechanisms.
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.
- A combo field contains a text field and a drop-down list in combination. If the number of items available for selection is small enough, the drop-down list can show all possible pre-assigned values at once. Otherwise, a vertical scrollbar is used to position the items in the drop-down list window. You can also allow users to enter data not contained in the list.
- A popup field is used to display a monthly calendar in rectangular format where the user can select the month and year using spin fields, and the day of the month from the resulting calendar. If you are using a time or date/time validator, the user can set the hour, minute, second, and meridiem using spin fields.
- A label field is similar to a text field in that it is used to display a single piece of alphanumeric data; however, it functions as a heading or label because its value cannot be changed by the user and it is displayed as a label. It can be bound to a database and present dynamic data.
1.2.2 Data Types Handled by JClass Field
The following table lists the data types handled by JClass Field:
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 binding to a database.
1.2.3 GUI Component Support for Data Types
The following table shows the commonly used data types and GUI component combinations:
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.
1.3 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.
1.3.1 JCTextField
1.3.2 JCSpinField
1.3.3 JCComboField
Autocomplete Feature
Description
JClass Field's combo box autocomplete feature has three modes:
suggest - a drop-down list appears as soon as the end user begins typing refine - the drop-down list updates itself to just those items that match what has already been typed append - the first candidate that matches what has been typed appears in the text field. The completed part is highlighted
See Appendix D, Using JCField's Autocomplete Feature, for a complete description of the combo box's autocomplete facility.
As an end user begins typing in a combo field with autocomplete on, those list items that match what has already been typed are presented. Pressing ENTER selects the choice currently in the text field. Another choice from the drop-down list may be selected by clicking it.
1.3.4 JCPopupField
1.3.5 JCLabelField
1.3.6 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. Please see the JClass DesktopViews Installation Guide for more information.
Note: "DSdb" components only bind with data sources included with JClass DataSource; "JBdb" components only bind with Borland JBuilder 3 data sources.
1.4 The Structure of a JClass Field Component
JClass Field components are comprised of four elements:
- a visual component: either
JCTextField,JCComboField,JCSpinField,JCPopupField, orJCLabelField.- the value model, which determines the data type of the component and contains the initial and current values of the field.
- the validator which supports the data type and contains properties specific to that data type.
- the InvalidInfo object, which contains additional properties that can be used by all data types and validators to direct the behavior of the field when it encounters an invalid value.
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 thegetDataProperties()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.
1.5 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." For more information, refer to Section 1.5.2, The Validation Process.
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
JCDateTimeValidatorsupports both thejava.util.Calendardata type and thejava.sql.Timestampdata type. TheJCDateValidatorsupports bothjava.util.Dateandjava.sql.Date. All other validators correspond exactly to the names of the data types they support.
1.5.1 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 2.
- display pattern, edit pattern (numbers only)
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.
- mask (Strings only)
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.
- min and max (numbers only)
You can set limits on the range of numeric data the field will accept.
- a valid character list: validChars, an invalid character list: invalidChars
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.
- defaultValue
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.
1.5.2 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.
Figure 1 : The validation and parsing process.
1.5.3 The useFormatting flag
A
useFormattingflag is available forJCBigDecimalValidator,JCFloatValidator, andJCDoubleValidator. It is used to dictate whether or not formatting is enforced. By default, the value for this flag istrueforJCFloatValidatorandJCDoubleValidator.This flag is set to
falseby default for theJCBigDecimalValidator, as formatting may result in a loss of precision forBigDecimaldata types. This risk is not applicable to the other two properties.
1.5.4 Validators and Value Models
Each validator can be used with specific value models; the following table indicates the value model to use with the different validators.
1.6 JClass Field Inheritance Hierarchy
JClass Field's visual components are subclassed entirely from Swing. In previous versions of Field, some components were subclassed from JClass BWT. Using Swing and JClass Field, you can do everything without BWT.
The following two diagrams show the inheritance hierarchy for the JClass Field Bean components. The first diagram shows the inheritance of the basic classes in JClass Field.
Figure 2 : JClass Field's Component Classes - the basic classes.
Here is the hierarchy of classes within JClass Field:
Figure 3 : 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.Figure 4 : JClass Field's validator Classes.
1.7 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
JCFooEventis fired (where "Foo" is the place holder for the actual event name). TheJCFooListener(which has been registered by callingaddFooListener()on the component) receives the instance and enacts the action to be taken. The developer uses theJCFooListenerto define what action or actions should take place when it receives theJCFooEvent.JClass Field Events
The event listener that receives the events generated by the four editable Fields is called
JCValueListener. Its methods arevalueChanging()andvalueChanged(). Changes to any one of the Fields are handled by invokingaddValueListener(). You supply the code to implement theJCValueListenerinterface. To register the method, please see addValueListener, removeValueListener, in Chapter 2.The methods of the JClass Field event listener are described below:
1.8 Keystroke Actions
Most key actions are intuitive, however there are some circumstances that may need explanation.
- The Escape key cancels any changes made in a field as long as the data has not been committed by pressing the Return key. However, if no valid data has previously been committed to the field and the default value is zero or null, then the Escape key will not cancel the changes.
- Arrow keys perform dual functions in calendar popups. If the calendar popup is visible, the arrow keys may be used to move to adjacent days. If the popup is hidden, the right and left arrow keys move the cursor through the date field, and the down arrow opens the popup.
- In combo fields, the down arrow key may be used to spin through the entries in the combo field's list. To actually pop down the list, use CTRL+Down Arrow.
1.9 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, both with an IDE or programmatically, see Building a Field, in Chapter 3.
The class
Examplescontains amainmethod and aninitmethod and, therefore, it is both an applet and a program. The file is located in the examples directory. When run using the commandjava examples.field.Examples, the program produces the output shown in the figure below.
Figure 5 : JClass Field examples.
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();
}
}
1.9.1 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 thetext1object, 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
text2specifies two letters followed by five digits. In this example, thesetPlaceHolderChars()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 thesetCurrency()method set totrue. The field also uses thesetInvalidPolicy()method, which is contained in theInvalidInfoobject, to clear the field if the user enters an amount that is out of range. The range of valid values is determined by thesetRange()method.The field,
combo1, uses the methodssetPickList()andsetDisplayList()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.
1.9.2 The Property Sheet
It is possible to examine and experiment with the component properties of the JClass Field objects using the Bean Development Kit (BDK) or any IDE. You can use the Property sheet to change the properties of the JClass Field component under consideration.
Instructions on loading and running the BeanBox can be found online at http://java.sun.com/beans/bdk_download.html.
Figure 6 : 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.
1.9.3 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.
1.9.4 Editing JClass Field Properties
The following lists the steps required to edit the properties for a JClass Field Bean:
- In the design window, select the JClass Field component that you want to edit.
All the editable Bean properties (and some read-only properties as well) appear in the Properties window.
- Double click on the
DataPropertiesproperty to invoke a property customizer that contains thevalue,validator, andinvalidinfoobject properties.- 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.
- When you make changes in the DataProperties editor, you must click Apply and then Done before the changes will be displayed.
Figure 7 : The property customizer of a JClass Field component.
- Some properties, such as
about, are read-only. They are included in the property sheet as information only. For example, double clicking on theaboutproperty will display the JClass help information. There is another read-only property, calledstate, 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.
1.10 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/j2se/1.4.2/docs/guide/intl/index.html.
|
|
