Appendix  D

Using JCField's Autocomplete Feature

Using Autocomplete in a JCComboField  Autocomplete Methods  Autocomplete Modes

Code Examples  Setting and Updating the List of Autocomplete Strings  Porting Guidelines

D.1 Using Autocomplete in a JCComboField

The autocomplete mechanism in JCField's JCComboField may be used to simplify selecting items in a combo box. In addition to providing a facility for narrowing the range of possible matches as each character is typed, and thus anticipating what choice the end user really wants, the prefix mechanism can be used to simplify typing Web addresses, directory paths, or other choices that begin with a common String.

Here is what you need to do to use the autocomplete facility. A code snippet is included in each step:

1. Create or reference a combo field.
        JCComboField combo = new JCComboField());
2. Create a String validator, or a validator derived from a String validator. These are the only validators that may be used with the autocompletion mechanism: JCStringValidator, JCDateValidator, JCDateTimeValidator, JCTimeValidator, JCIPAddressValidator:
        JCStringValidator sv = new JCStringValidator();
3. Create or update the list Strings that will populate the combo field's drop down.
        String[] string_list = {string1, string2, ...};
4. Create a list model with the items.
        JCListModel autoCompleteListModel = new JCListModel(string_list);
5. Set this list model on the validator.
        sv.setPickList(autoCompleteListModel);
6. Set the validator on the combo box.
        combo.setValidator(sv);
7. Once a validator containing the list model has been set on a chosen combo field, the method call for invoking auto completion is:

        JCComboField combo;
     boolean autoComplete = true;
     combo.setAutoComplete(autoComplete, autoAppend, autoSuggest,
          autoRefinement, prefix_list);

The first four parameters are Booleans, while the last is an array of Strings. The only way to set the modes and a prefix list is through a call to setAutoComplete(). The parameters for setAutoComplete() are:

• autoComplete - autocomplete is active. The combo box tries to autocomplete as the user types. If this parameter is false, auto completion is disabled.
• autoAppend - a candidate String appears in the text field itself. The drop down list does not appear unless autoSuggest is also true. What the end user has already typed appears as normal text and the rest of the autocompleted String appears in reverse video.
• autoSuggest - a drop down list appears as soon as the end user starts typing. All Strings in the list model appear in the list. The selected item is updated as the user types. The list updates itself if autoRefinement in on. If autoAppend is false there is no candidate completed String in the text field, only the characters the end user has typed so far.
• autoRefinement - to use refine, suggest mode must be on. It operates on the drop down list part of the combo box. If autoRefinement is true, the list updates itself as the end user continues to type, eliminating choices that are no longer relevant. Also, it adds what is currently in the text box to the list. If autoRefinement is false, the drop down list retains all items and the first possible match is highlighted. Autorefinement always reacts to adding or deleting a character anywhere in the String as the autocompletion mechanism matches possibilities with what has been typed.
• prefix_list - eliminates the need for the end user to type a common first part of the input, such as http://www. in a URL, or C:/JClass/com/klg/class in a directory path. Set a prefix list by calling setAutoComplete() with the array of prefix list Strings as the last parameter. If the typed-in String matches the letters immediately following one of the Strings in the prefix list, the item or items matched will appear in the combo box, along with items that begin with the typed-in String. If you are using a prefix list, set the Boolean properties autoSuggest and autoRefinement to true to avoid behavior that might be non-intuitive to the end user. With these two properties set, matching begins as soon as the end user begins typing. The drop down list shows the first matched list item highlighted along with any other possible match. The drop down list updates itself as the end user continues to type, showing only those items that are possible completions to what has already been typed.

  Example: The prefix list contains the Strings {"water", "snow"}, and the combo box list contains items "police," "polish," "waterpic," "waterpolo." The combo box has autoSuggest and autoRefinement set to true. The end user begins by typing a "p" in the text box. All the items mentioned above appear in the drop down list. The last item is the letter "p" that has just been typed in. The end user types an "o," so the text box contains "po." The drop down list updates itself to contain just the matched items "police," "polish," "waterpolo," and "po." By the time the end user has typed "polo," only two list items remain, "waterpolo," and "polo."

D.1.1 Cursor Behavior

Placing the cursor within the String sets the insertion point for the next typed character. The appearance of the cursor and its behavior depend on the mode autocomplete is in. The following table lists the state of autoSuggest (S), autoRefine (R), and autoAppend (A). The behaviors of the cursor, the text box, and the drop down list are described for each state. Assume in each case that autoComplete is true.

S	R	A	Behavior
Off	Off	Off	Autocomplete is on, but there are no visual clues.
Off	Off	On	There is no automatic invocation of the drop down list. As the end user begins typing, the first matched item appears in full in the text box. Since append mode is on, the autocompleted portion of the item is highlighted. A blinking cursor is shown at the end of the highlighted text. If the end user types another character, it is placed between what has already been typed and the highlighted portion, not at the blinking cursor. The drop down list is updated if a new match is found. If instead the end user types the backspace key, the entire highlighted portion of the String is removed. Further backspaces remove individual characters. If the end user clicks on the String to change the insertion point, the autocompleted portion of the text remains and highlighting is turned off.
Off	On	Off	Autocomplete is on, but there are no visual clues. This combination should not be used.
Off	On	On	Same as (Off, Off, On). This combination should not be used.
On	Off	Off	Just the end user's typing (without autocompletion) appears in the text box. The drop down list appears as soon as the end user begins typing. The first matched item is highlighted. All other items are available in the drop down list's scroll pane. The cursor appears in the text box at the end of the typed-in String. If the end user changes the insertion point and begins typing there, the drop down list adjusts by highlighting the new match, if there is one. If there is no match, the list stays the same.
On	Off	On	Cursor behavior is similar to (Off, Off, On). The full item list appears in the drop down list with the first matched item highlighted.
On	On	Off	Since autoAppend is inactive, cursor behavior is the same as (On, Off, Off). Because autoRefine is on, the drop down list is restricted to potential matches. If the end user uses the left cursor key to move the insertion point and inserts a character that results in a new word that also is a partial match for some list items, the drop down list updates itself.
On	On	On	Cursor behavior is the same as (Off, Off, On). If a match occurs, an autocompleted item appears in the text box. The drop down list contains only potential matches.

Backspacing

To summarize, if autoAppend is false, backspacing deletes a character as usual. There is no autocompletion, so the cursor is at the end of the String. If autoAppend is true, there are effectively two cursors when a match is first found, one for inserting text and one for deleting text. Characters are inserted just before the highlighted text. Backspaces cause the highlighted text to be erased, after which previous typing is erased.

D.2 Autocomplete Methods

The methods listed here are of use with the autocomplete function:

Autocomplete Method	Description
setAutoComplete()	Controls whether the autocomplete function is on or off, and sets its modes of operation, which are described in the next section.
isAutoComplete()	Returns true if the field has autoComplete turned on.
isAutoSuggest()	Returns true if the field has autoSuggest turned on.
isAutoAppend()	Returns true if the field has autoAppend turned on.
isAutoRefinement()	Returns true if the field has autoRefinement turned on.
getPrefixList()	Returns a String array of prefixes that need not be typed to be matched, so long as the characters following the prefix do match an item in the combo box's list model.

D.3 Autocomplete Modes

The parameters in setAutoComplete() control the autocomplete modes:

Autocomplete Mode	Function
autoAppend	The text field shows a candidate String from its autocomplete list. Append the completion to the partial completed text shown in reverse video
autoComplete	Determines whether the auto complete mode is enabled. If this value is false, the values of the attributes are ignored.
autoRefinement	If autoSuggest is true, refine the popup list to include all possible matches as well as the currently typed text. Note that if AutoSuggest is false, this attribute will also be set to false.
autoSuggest	Pop up the combo box's popup as a suggestion list upon typing a character.
prefixList	Sets the prefixList. If non-null, the combo box will ignore the given prefixes when matching items. The longest matching prefix is always used. Note that although it is permitted to use a prefix list without autoSuggest being true, the resulting behavior maybe be quite non-intuitive to the end user.

The autocomplete mechanism for a JCComboField is turned on and off by a call to setAutoComplete(). The method's first parameter is the flag that controls whether autocomplete is enabled or not, and the other parameters set the autocomplete modes and the prefix list. If you do not want a prefix list, set the prefix list parameter to null. Thus, a typical call to setAutoComplete() looks like this:

combo.setAutoComplete(true, append, suggest, refine, prefix_list);

D.4 Code Examples

The following example shows a method that returns a JCComboField. Its parameters are string_list, the list of items for the combo box, prefix_list, a list of ignorable prefixes, and three Booleans for the autocomplete modes, suggest, refine, and append.

1	public JCComboField createComboField(String [] string_list,   String []     prefix_list,   boolean       suggest,   boolean       refine,   boolean      append)   // Example of a JCComboField using a JCStringValidator
2	JCComboField combo = new JCComboField();
3	JCStringValidator sv = new JCStringValidator();   sv.setMatchPickList(false);   sv.setAllowNull(true);
4	JCListModel dm = new JCListModel(string_list);
5	sv.setPickList(dm);   // set the value model and validator   combo.setValueModel(new StringValueModel());
6	combo.setValidator(sv);   // No need to call this if all autocomplete mode flags are false   if (suggest || refine || append) {
7	combo.setAutoComplete(true,     append,     suggest,     refine,     prefix_list);   }   return combo; }

D.4.1 Explaining the Code

This section further explains the code in the previous section. The line number keys specify which line is being described.

Line 1	The method call.
Line 2	Instantiates a new JCComboField. There is no constructor for enabling the autocomplete mechanism, so it must be configured by calling setAutoComplete().
Line 3	Creates a JCStringValidator, through which the list items are set on the combo field.
Line 4	Creates the data model that holds the list items.
Line 5	In a JCComboField's design, a pick list may be derived from a data model. The pick list is set on one of JClass Field's validators, and the validator is associated with the combo box.
Line 6	Associates the validator with the combo box.
Line 7	Call setAutoComplete(), specifying the modes and the prefix list.

D.5 Setting and Updating the List of Autocomplete Strings

The autocomplete candidates are the Strings that populate the combo box's drop down list. Among the ways of setting the list of Strings on the swing data model, these three deserve notice.

Setting the list items:

• from predefined Strings set in the application itself
• as the result of a database query
• read from a file containing the appropriate items

Once initialized, you may wish to update the list:

• as the end user types new information
• as information changes as the result of a database query
• because the context of the application has changed

Updating from user input

One way of updating the data model is by adding a JCValueListener to the combo field. When the end user commits a choice by typing the Enter key, the listener's valueChanging() and valueChanged() methods are invoked. In the valueChanged() method, get the result of the user's input with

JCComboField combo;
...
String newValue = (String) combo.getValue();

You will have to check that the entry is different from ones already in the list. If it is, the new entry may be added to the data model at the position you deem appropriate, thereby updating the list. Please see Event Programming, in Chapter 4 for an example of modifying the combo box's pick list from user input as well as the example that follows in this section.

Updating from a database

You can connect a data-aware JCComboField component, such as DSdbComboField, to a data source and populate the data model form an SQL query. Please see the Data Binding, in Chapter 3, for information on data binding.

When the database is updated, the data source should fire an event to inform the combo box so that the change may be reflected in its item list.

Populating the list from a file

The tokens representing the list elements you want may be delimited in various ways in your source file. When reading the file, you will form the array of Strings that you pass to a JCListModel, and you may want to use JCStringTokenizer in JClass Elements to simplify the task.

JClass Elements is available as part of the JClass DesktopViews product bundle. Visit http://www.quest.com for more information and downloads.

Adding an Item from End User Input

If you wish to allow end users to add to the list items, you can have the combo field respond to a value change event. Here is a suggestion.

In the class that is registered as a listener for JCValue events, implement the two required methods, valueChanging() and valueChanged().

  public void valueChanging(JCValueEvent e) {// May be empty }

  public void valueChanged(JCValueEvent e) {
    String newValue = ((String) combo.getValue()).trim();
    boolean found = false;
    int position = 0;
    if(newValue != null && newValue.length() > 0){
      for (int i = 0; i < dm.getSize(); i++){
        if (newValue.compareTo((String)dm.getElementAt(i)) == 0) {
          found = true;
        } else {
            if (newValue.compareToIgnoreCase(
                (String)dm.getElementAt(i)) > 0) {
              //place the new item in its sorted place
              position = i + 1; }
        }
      }
    }
    if (!found && newValue != null && newValue.length() > 0) {
      dm.add(position, (String) newValue);
      combo.setPickList(dm);
      combo.setSelectedIndex(position);
    }
  }

The event handler looks for an existing list item that is essentially the same as the one the end user typed. If one is found, no addition is made. If the user's input is different from each item in the existing list, the new item is added to the data model and to the combo field's pick list.

Note: If autoRefinement is true, the ValueChanged event is not passed on to your class simply by pressing the Enter key. If you wish to allow end users to update the list of combo box items using actionPerformed() while autoRefinement is in effect, they will have to click on the newly-typed item. Since it does not match any previous item, it will be the only one remaining in the drop down list. This generates a ValueChanged event that is passed to your ValueListener.

D.6 Porting Guidelines

There should be no porting issues for your applications that employ a JClass JCComboField, version 4.5.1 or earlier, when you update to a current release. Your code should continue to function, and you may add autocompletion if you wish.