Prev Class | Next Class | Frames | No Frames |
Summary: Nested | Field | Method | Constr | Detail: Nested | Field | Method | Constr |
java.lang.Object
ca.odell.glazedlists.swing.AutoCompleteSupport<E>
public final class AutoCompleteSupport<E>
extends java.lang.Object
AutoCompleteSupport
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
JComboBox
, but may be wider to accomodate a
prototype display value
if a non-null prototype display value exists
JComboBox.getMaximumRowCount()
rows before scrolling the popup
ActionEvent
is fired from the JComboBox in these situations:
null
values located in the ComboBoxModel are considered
identical to empty Strings ("") for the purposes of locating autocompletion
terms.getSelectsTextOnFocusGain()
returns true
getHidesPopupOnFocusLost()
returns true
Object.toString()
to map elements to their String equivalents. Sometimes, however, toString()
is not a reliable or desirable mechanism to use. To deal with this problem,
AutoCompleteSupport provides an install method that takes a Format
object which is used to do all converting back and forth between Strings and
ComboBoxModel objects.
In order to achieve all of the autocompletion and filtering behaviour,
the following occurs when AutoCompleteSupport
is called:
IllegalStateException
thrown from any one of:
install(JComboBox, EventList)
install(JComboBox, EventList, TextFilterator)
install(JComboBox, EventList, TextFilterator, Format)
isInstalled()
uninstall()
setCorrectsCase(boolean)
setStrict(boolean)
setBeepOnStrictViolation(boolean)
setSelectsTextOnFocusGain(boolean)
setHidesPopupOnFocusLost(boolean)
setFilterMode(int)
setFirstItem(Object)
removeFirstItem()
Nested Class Summary | |
static class |
|
Method Summary | |
static |
|
static |
|
static |
|
static |
|
static |
|
static |
|
boolean |
|
JComboBox |
|
boolean |
|
int |
|
E |
|
boolean |
|
EventList |
|
boolean |
|
Object |
|
boolean |
|
boolean |
|
E |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
TextFilterator |
|
void |
|
public staticAutoCompleteCellEditor createTableCellEditor(Comparator uniqueComparator, TableFormat tableFormat, EventList tableData, int columnIndex)
This factory method creates and returns aAutoCompleteSupport.AutoCompleteCellEditor
which adapts an autocompletingJComboBox
for use as a Table Cell Editor. The values within the table column are used as autocompletion terms within theComboBoxModel
. This version ofcreateTableCellEditor
makes no assumption about the values stored in the TableModel at the givencolumnIndex
. Instead, it uses the givenuniqueComparator
to determine which values are duplicates (and thus can safely be removed) and which are unique (and thus must remain in theComboBoxModel
). Note that this factory method is only appropriate for use when the values in theComboBoxModel
should be the unique set of values in a table column. If some other list of values will be used thencreateTableCellEditor(EventList)
is the appropriate factory method to use. If the appearance or function of the autocompletingJComboBox
is to be customized, it can be retrieved usingAutoCompleteCellEditor.getComponent()
.
- Parameters:
uniqueComparator
- theComparator
that strips away duplicate elements from theComboBoxModel
tableFormat
- specifies how each row object within a table is broken apart into column valuestableData
- theEventList
backing the TableModelcolumnIndex
- the index of the column for which to return aAutoCompleteSupport.AutoCompleteCellEditor
- Returns:
- a
AutoCompleteSupport.AutoCompleteCellEditor
which contains an autocompleting combobox whose contents remain consistent with the data in the table column at the givencolumnIndex
public staticAutoCompleteCellEditor createTableCellEditor(EventList source)
This factory method creates and returns aAutoCompleteSupport.AutoCompleteCellEditor
which adapts an autocompletingJComboBox
for use as a Table Cell Editor. The values within thesource
are used as autocompletion terms within theComboBoxModel
. If the appearance or function of the autocompletingJComboBox
is to be customized, it can be retrieved usingAutoCompleteCellEditor.getComponent()
.
- Parameters:
source
- the source of data for the JComboBox within the table cell editor
- Returns:
- a
AutoCompleteSupport.AutoCompleteCellEditor
which contains an autocompleting combobox whose model contents are determined by the givensource
public staticAutoCompleteCellEditor createTableCellEditor(TableFormat tableFormat, EventList tableData, int columnIndex)
This factory method creates and returns aAutoCompleteSupport.AutoCompleteCellEditor
which adapts an autocompletingJComboBox
for use as a Table Cell Editor. The values within the table column are used as autocompletion terms within theComboBoxModel
. This version ofcreateTableCellEditor
assumes that the values stored in the TableModel at the givencolumnIndex
are allComparable
, and that the natural ordering defined by thoseComparable
values also determines which are duplicates (and thus can safely be removed) and which are unique (and thus must remain in theComboBoxModel
). Note that this factory method is only appropriate for use when the values in theComboBoxModel
should be the unique set of values in a table column. If some other list of values will be used thencreateTableCellEditor(EventList)
is the appropriate factory method to use. If the appearance or function of the autocompletingJComboBox
is to be customized, it can be retrieved usingAutoCompleteCellEditor.getComponent()
.
- Parameters:
tableFormat
- specifies how each row object within a table is broken apart into column valuestableData
- theEventList
backing the TableModelcolumnIndex
- the index of the column for which to return aAutoCompleteSupport.AutoCompleteCellEditor
- Returns:
- a
AutoCompleteSupport.AutoCompleteCellEditor
which contains an autocompleting combobox whose contents remain consistent with the data in the table column at the givencolumnIndex
public staticAutoCompleteSupport install(JComboBox comboBox, EventList items)
Installs support for autocompletion into thecomboBox
and returns the support object that is actually providing those facilities. The support object is returned so that the caller may invokeuninstall()
at some later time to remove the autocompletion features. This method assumes that theitems
can be converted into reasonable String representations viaObject.toString()
. The following must be true in order to successfully install support for autocompletion on aJComboBox
:
- The JComboBox must use a
JTextField
as its editor component- The JTextField must use an
AbstractDocument
as its model
- Parameters:
comboBox
- theJComboBox
to decorate with autocompletionitems
- the objects to display in thecomboBox
- Returns:
- an instance of the support class providing autocomplete features
public staticAutoCompleteSupport install(JComboBox comboBox, EventList items, E> filterator)
Installs support for autocompletion into thecomboBox
and returns the support object that is actually providing those facilities. The support object is returned so that the caller may invokeuninstall()
at some later time to remove the autocompletion features. This method assumes that theitems
can be converted into reasonable String representations viaObject.toString()
. Thefilterator
will be used to extract searchable text strings from each of theitems
. Anull
filterator implies the item's toString() method should be used when filtering it. The following must be true in order to successfully install support for autocompletion on aJComboBox
:
- The JComboBox must use a
JTextField
as its editor component- The JTextField must use an
AbstractDocument
as its model
- Parameters:
comboBox
- theJComboBox
to decorate with autocompletionitems
- the objects to display in thecomboBox
filterator
- extracts searchable text strings from each item;null
implies the item's toString() method should be used when filtering it
- Returns:
- an instance of the support class providing autocomplete features
public staticAutoCompleteSupport install(JComboBox comboBox, EventList items, E> filterator, Format format)
Installs support for autocompletion into thecomboBox
and returns the support object that is actually providing those facilities. The support object is returned so that the caller may invokeuninstall()
at some later time to remove the autocompletion features. This method uses the givenformat
to convert the givenitems
into Strings and back again. In other words, this method does NOT rely onObject.toString()
to produce a reasonable String representation of each item. Likewise, it does not rely on the existence of a valueOf(String) method for creating items out of Strings as is the default behaviour of JComboBox. It can be assumed that the only methods called on the givenformat
are:As a convenience, this method will install a custom
Format.format(Object)
Format.parseObject(String, ParsePosition)
ListCellRenderer
on thecomboBox
that displays the String value returned by theformat
. Though this is only done if the givenformat
is notnull
and if thecomboBox
does not already use a custom renderer. Thefilterator
will be used to extract searchable text strings from each of theitems
. Anull
filterator implies one of two default strategies will be used. If theformat
is not null then the String value returned from theformat
object will be used when filtering a given item. Otherwise, the item's toString() method will be used when it is filtered. The following must be true in order to successfully install support for autocompletion on aJComboBox
:
- The JComboBox must use a
JTextField
as its editor component- The JTextField must use an
AbstractDocument
as its model
- Parameters:
comboBox
- theJComboBox
to decorate with autocompletionitems
- the objects to display in thecomboBox
filterator
- extracts searchable text strings from each item. If theformat
is not null then the String value returned from theformat
object will be used when filtering a given item. Otherwise, the item's toString() method will be used when it is filtered.format
- a Format object capable of convertingitems
into Strings and back.null
indicates the standard JComboBox methods of converting are acceptable.
- Returns:
- an instance of the support class providing autocomplete features
public boolean getBeepOnStrictViolation()
Returns true if a beep sound is played when the user attempts to violate the strict invariant; false if no beep sound is played. This setting is only respected ifisStrict()
returns true.
- See Also:
setStrict(boolean)
public JComboBox getComboBox()
public boolean getCorrectsCase()
Returns true if user specified strings are converted to the case of the autocompletion term they match; false otherwise.
public int getFilterMode()
Returns the manner in which the contents of theComboBoxModel
are filtered. This method will return one ofTextMatcherEditor.CONTAINS
orTextMatcherEditor.STARTS_WITH
.TextMatcherEditor.CONTAINS
indicates elements of theComboBoxModel
are matched when they contain the text entered by the user.TextMatcherEditor.STARTS_WITH
indicates elements of theComboBoxModel
are matched when they start with the text entered by the user. In both modes, autocompletion only occurs when a given item starts with user-specified text. The filter mode only affects the filtering aspect of autocomplete support.
public E getFirstItem()
Returns the optional single value used as the first element in theComboBoxModel
or null if no first item has been set.
- Returns:
- the special first value presented in the
ComboBoxModel
or null if no first item has been set
public boolean getHidesPopupOnFocusLost()
Returns true if the popup menu is hidden whenever the combo box editor loses focus; false otherwise.
public EventListgetItemList()
Returns the filteredEventList
of items which backs theComboBoxModel
of the autocompletingJComboBox
.
public boolean getSelectsTextOnFocusGain()
Returns true if the combo box editor text is selected when it gains focus; false otherwise.
public Object getTextMatchingStrategy()
Returns the manner in which the contents of theComboBoxModel
are filtered and autocompletion terms are matched. The returnedstrategy
is one ofTextMatcherEditor.IDENTICAL_STRATEGY
orTextMatcherEditor.NORMALIZED_STRATEGY
or the Unicode strategy of the ICU4J extension.
public boolean isInstalled()
Returns true if this autocomplete support instance is currently installed and altering the behaviour of the combo box; false if it has beenuninstall()
ed.
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.
public E removeFirstItem()
Removes and returns the optional single value used as the first element in theComboBoxModel
or null if no first item has been set.
- Returns:
- the special first value presented in the
ComboBoxModel
or null if no first item has been set
public void setBeepOnStrictViolation(boolean beepOnStrictViolation)
Sets the policy for indicating strict-mode violations to the user by way of a beep sound.
- Parameters:
beepOnStrictViolation
- true if a beep sound should be played when the user attempts to violate the strict invariant; false if no beep sound should be played
public void setCorrectsCase(boolean correctCase)
IfcorrectCase
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.
- See Also:
setStrict(boolean)
public void setFilterMode(int mode)
Sets the manner in which the contents of theComboBoxModel
are filtered. The givenmode
must be one ofTextMatcherEditor.CONTAINS
orTextMatcherEditor.STARTS_WITH
.
- See Also:
getFilterMode()
public void setFirstItem(E item)
This method set a single optional value to be used as the first element in theComboBoxModel
. This value typically represents "no selection" or "blank". This value is always present and is not filtered away during autocompletion.
- Parameters:
item
- the first value to present in theComboBoxModel
public void setHidesPopupOnFocusLost(boolean hidesPopupOnFocusLost)
IfhidesPopupOnFocusLost
is true, then the popup menu of the combo box is always hidden whenever the combo box editor loses focus. If it is false the default behaviour is preserved. In practice this means that if focus is lost because of a MouseEvent, the behaviour is reasonable, but if focus is lost because of a KeyEvent (e.g. tabbing to the next focusable component) then the popup menu remains visible.
public void setSelectsTextOnFocusGain(boolean selectsTextOnFocusGain)
IfselectsTextOnFocusGain
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.
public void setStrict(boolean strict)
Ifstrict
is false, the user can specify values not appearing within the ComboBoxModel. If it is true each keystroke must continue to match some value in the ComboBoxModel or it will be discarded. Note: When strict mode is enabled, all user input is corrected to the case of the autocompletion term, regardless of the correctsCase setting.
- See Also:
setCorrectsCase(boolean)
public void setTextMatchingStrategy(Object strategy)
Sets the manner in which the contents of theComboBoxModel
are filtered and autocompletion terms are matched. The givenstrategy
must be one ofTextMatcherEditor.IDENTICAL_STRATEGY
orTextMatcherEditor.NORMALIZED_STRATEGY
or the Unicode strategy of the ICU4J extension.
- See Also:
getTextMatchingStrategy()
public TextFilterator super E> getTextFilterator()
Returns theTextFilterator
that extracts searchable strings from each item in theComboBoxModel
.
public void uninstall()
This method removes autocompletion support from theJComboBox
it was installed on. This method is useful when theEventList
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 theEventList
of items.