ca.odell.glazedlists.swing
Class AutoCompleteSupport<E>

java.lang.Object
  ca.odell.glazedlists.swing.AutoCompleteSupport<E>

public final class AutoCompleteSupport<E>
extends Object

This class install(javax.swing.JComboBox, ca.odell.glazedlists.EventList)s support for filtering and autocompletion into a standard JComboBox. It also acts as a factory class for creating autocompleting table cell editors.

All autocompletion behaviour provided is meant to mimic the functionality of the Firefox address field. To be explicit, the following is a list of expected behaviours which are installed:

Typing into the ComboBox Editor

1. typing any value into the editor when the popup is invisible causes the popup to appear and its contents to be filtered according to the editor's text. It also autocompletes to the first item that is prefixed with the editor's text and selects that item within the popup.
2. typing any value into the editor when the popup is visible causes the popup to be refiltered to contain values that start with the prefix and reselects an appropriate autocompletion item
3. typing the down or up arrow keys in the editor when the popup is invisible causes the popup to appear and its contents to be filtered according to the editor's text. It also autocompletes to the first item that is prefixed with the editor's text and selects that item within the popup.
4. typing the up arrow key when the popup is visible and the selected element is the first element causes the autocompletion to be cleared and the popup's selection to be removed
5. typing the up arrow key when no selection exists causes the last element of the popup to become selected and used for autocompletion
6. typing the down arrow key when the popup is visible and the selected element is the last element causes the autocompletion to be cleared and the popup's selection to be removed
7. typing the down arrow key when no selection exists causes the first element of the popup to become selected and used for autocompletion

Clicking on the Arrow Button

1. clicking the arrow button when the popup is invisible causes the popup to appear and its contents to be shown unfiltered
2. clicking the arrow button when the popup is visible causes the popup to disappear

Sizing the ComboBox Popup

1. the popup is always at least as wide as the autocompleting JComboBox, but may be wider to accomodate a prototype display value if a non-null value exists
2. as items are filtered in the ComboBoxModel, the popup height is adjusted to display between 0 and JComboBox.getMaximumRowCount() rows before scrolling the popup

JComboBox ActionEvents

A single ActionEvent is fired from the JComboBox in these situations:

1. the user hits the enter key
2. the selected item within the popup is changed (which can happen due to a mouse click, a change in the autocompletion term, or using the arrow keys)
3. the JComboBox loses focus and contains a value that does not appear in the ComboBoxModel

Null Values in the ComboBoxModel

null values located in the ComboBoxModel are considered identical to empty Strings ("") for the purposes of locating autocompletion terms.

ComboBoxEditor Focus

When the ComboBoxEditor gains focus it selects the text it contains if getSelectsTextOnFocusGain() returns true; otherwise it does nothing.

In order to achieve all of the autocompletion and filtering behaviour, the following occurs when install(javax.swing.JComboBox, ca.odell.glazedlists.EventList) is called:

• the JComboBox will be made editable
• the JComboBox will have a custom ComboBoxModel installed on it containing the given items
• the JTextField which is the editor component for the JComboBox will have a DocumentFilter installed on its backing Document

The strategy of this support class is to alter all of the objects which influence the behaviour of the JComboBox in one single context. With that achieved, it greatly reduces the cross-functional communication required to customize the behaviour of JComboBox for filtering and autocompletion.

Warning: This class must be mutated from the Swing Event Dispatch Thread. Failure to do so will result in an IllegalStateException thrown from any one of:

• install(JComboBox, EventList)
• install(JComboBox, EventList, TextFilterator)
• uninstall()
• setCorrectsCase(boolean)
• setStrict(boolean)

Author:

James Lemieux

Field Summary

protected JButton

arrowButton The arrow button that invokes the popup.

Method Summary

static <E> DefaultCellEditor	createTableCellEditor(TableFormat<E> tableFormat, EventList<E> tableData, int columnIndex) This factory method creates and returns a DefaultCellEditor which adapts an autocompleting JComboBox for use as a Table Cell Editor.
JComboBox	getComboBox() Returns the autocompleting JComboBox or null if AutoCompleteSupport has been uninstall()ed.
boolean	getCorrectsCase() Returns true if user specified strings are converted to the case of the autocompletion term they match; false otherwise.
EventList<E>	getItemList() Returns the filtered EventList of items which backs the ComboBoxModel of the autocompleting JComboBox.
boolean	getSelectsTextOnFocusGain() Returns true if the combo box editor text is selected when it gains focus; false otherwise.
static <E> AutoCompleteSupport	install(JComboBox comboBox, EventList<E> items) Installs support for autocompletion into the comboBox and returns the support object that is actually providing those facilities.
static <E> AutoCompleteSupport<E>	install(JComboBox comboBox, EventList<E> items, TextFilterator<E> filterator) Installs support for autocompletion into the comboBox and returns the support object that is actually providing those facilities.
boolean	isStrict() Returns true if the user is able to specify values which do not appear in the popup list of suggestions; false otherwise.
void	setCorrectsCase(boolean correctCase) If correctCase is true, user specified strings will be converted to the case of the element they match.
void	setSelectsTextOnFocusGain(boolean selectsTextOnFocusGain) If selectsTextOnFocusGain is true, all text in the editor is selected when the combo box editor gains focus.
void	setStrict(boolean strict) If strict is true, the user can specify values not appearing within the ComboBoxModel.
void	uninstall() This method removes autocompletion support from the JComboBox it was installed on.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

arrowButton

protected JButton arrowButton

The arrow button that invokes the popup.

Method Detail

install

public static <E> AutoCompleteSupport install(JComboBox comboBox,
                                              EventList<E> items)

Installs support for autocompletion into the comboBox and returns the support object that is actually providing those facilities. The support object is returned so that the caller may invoke uninstall() at some later time to remove the autocompletion features.

This method assumes that the items can be converted into reasonable String representations via Object.toString().

Parameters:

comboBox - the JComboBox to decorate with autocompletion

items - the objects to display in the comboBox

Returns:

an instance of the support class that is providing autocomplete features

Throws:

IllegalStateException - if this method is called from any Thread other than the Swing Event Dispatch Thread

install

public static <E> AutoCompleteSupport<E> install(JComboBox comboBox,
                                                 EventList<E> items,
                                                 TextFilterator<E> filterator)

Installs support for autocompletion into the comboBox and returns the support object that is actually providing those facilities. The support object is returned so that the caller may invoke uninstall() at some later time to remove the autocompletion features.

The filterator will be used to extract searchable text strings from each of the items.

The following must be true in order to successfully install support for autocompletion on a JComboBox:

• The JComboBox must use a JTextField as its editor
• The JTextField must use an AbstractDocument as its model

Parameters:

comboBox - the JComboBox to decorate with autocompletion

items - the objects to display in the comboBox

filterator - extracts searchable text strings from each item

Returns:

an instance of the support class that is providing autocomplete features

Throws:

IllegalStateException - if this method is called from any Thread other than the Swing Event Dispatch Thread

getComboBox

public JComboBox getComboBox()

Returns the autocompleting JComboBox or null if AutoCompleteSupport has been uninstall()ed.

getItemList

public EventList<E> getItemList()

Returns the filtered EventList of items which backs the ComboBoxModel of the autocompleting JComboBox.

getCorrectsCase

public boolean getCorrectsCase()

Returns true if user specified strings are converted to the case of the autocompletion term they match; false otherwise.

setCorrectsCase

public void setCorrectsCase(boolean correctCase)

If correctCase is true, user specified strings will be converted to the case of the element they match. Otherwise they will be left unaltered.

Note: this flag only has meeting when strict mode is turned off. When strict mode is on, case is corrected regardless of this setting.

Throws:

IllegalStateException - if this method is called from any Thread other than the Swing Event Dispatch Thread

See Also:

setStrict(boolean)

isStrict

public boolean isStrict()

Returns true if the user is able to specify values which do not appear in the popup list of suggestions; false otherwise.

setStrict

public void setStrict(boolean strict)

If strict is true, the user can specify values not appearing within the ComboBoxModel. If it is false each keystroke must continue to match some value in the ComboBoxModel or it will be discarded.

Note: When strict mode is turned on then all user input is corrected to the case of the autocompletion term, regardless of the correctsCase setting.

Throws:

IllegalStateException - if this method is called from any Thread other than the Swing Event Dispatch Thread

See Also:

setCorrectsCase(boolean)

getSelectsTextOnFocusGain

public boolean getSelectsTextOnFocusGain()

Returns true if the combo box editor text is selected when it gains focus; false otherwise.

setSelectsTextOnFocusGain

public void setSelectsTextOnFocusGain(boolean selectsTextOnFocusGain)

If selectsTextOnFocusGain is true, all text in the editor is selected when the combo box editor gains focus. If it is false the selection state of the editor is not effected by focus changes.

Throws:

IllegalStateException - if this method is called from any Thread other than the Swing Event Dispatch Thread

uninstall

public void uninstall()

This method removes autocompletion support from the JComboBox it was installed on. This method is useful when the EventList of items that backs the combo box must outlive the combo box itself. Calling this method will return the combo box to its original state before autocompletion was installed, and it will be available for garbage collection independently of the EventList of items.

Throws:

IllegalStateException - if this method is called from any Thread other than the Swing Event Dispatch Thread

createTableCellEditor

public static <E> DefaultCellEditor createTableCellEditor(TableFormat<E> tableFormat,
                                                          EventList<E> tableData,
                                                          int columnIndex)

This factory method creates and returns a DefaultCellEditor which adapts an autocompleting JComboBox for use as a Table Cell Editor. The values within the table column are used as autocompletion terms within the ComboBoxModel.

If the appearance or function of the autocompleting JComboBox is to be customized, it can be retrieved using DefaultCellEditor.getComponent().

Parameters:

tableFormat - specifies how each row object within a table is broken apart into column values

tableData - the EventList backing the TableModel

columnIndex - the index of the column for which to return a Table Cell Editor

Returns:

a DefaultCellEditor which contains an autocompleting combobox whose contents remain consistent with the data in the table column at the given columnIndex