public final class AutoCompleteSupport<E> extends Object
install(javax.swing.JComboBox, org.jadice.util.glazedlists.EventList<E>)
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
A single 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.
ComboBoxEditor Focus
getSelectsTextOnFocusGain()
returns
true
getHidesPopupOnFocusLost()
returns true
Each value in the ComboBoxModel must be converted to a String for many reasons: filtering,
setting into the ComboBoxEditor, displaying in the renderer, etc. By default, JComboBox relies on
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
install(javax.swing.JComboBox, org.jadice.util.glazedlists.EventList<E>)
is called:
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)
install(JComboBox, EventList, TextFilterator, Format)
isInstalled()
uninstall()
setCorrectsCase(boolean)
setStrict(boolean)
setBeepOnStrictViolation(boolean)
setSelectsTextOnFocusGain(boolean)
setHidesPopupOnFocusLost(boolean)
setFilterMode(int)
setFirstItem(Object)
removeFirstItem()
Modifier and Type | Class and Description |
---|---|
static class |
AutoCompleteSupport.AutoCompleteCellEditor<E>
This extension of DefaultCellEditor exists solely to provide a handle to the
AutoCompleteSupport object that is providing autocompletion capabilities to the JComboBox.
|
Modifier and Type | Method and Description |
---|---|
static <E> AutoCompleteSupport.AutoCompleteCellEditor<E> |
createTableCellEditor(Comparator uniqueComparator,
TableFormat<E> tableFormat,
EventList<E> tableData,
int columnIndex)
This factory method creates and returns a
AutoCompleteSupport.AutoCompleteCellEditor which adapts an
autocompleting JComboBox for use as a Table Cell Editor. |
static <E> AutoCompleteSupport.AutoCompleteCellEditor<E> |
createTableCellEditor(EventList<E> source)
This factory method creates and returns a
AutoCompleteSupport.AutoCompleteCellEditor which adapts an
autocompleting JComboBox for use as a Table Cell Editor. |
static <E> AutoCompleteSupport.AutoCompleteCellEditor<E> |
createTableCellEditor(TableFormat<E> tableFormat,
EventList<E> tableData,
int columnIndex)
This factory method creates and returns a
AutoCompleteSupport.AutoCompleteCellEditor which adapts an
autocompleting JComboBox for use as a Table Cell Editor. |
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. |
JComboBox |
getComboBox()
|
boolean |
getCorrectsCase()
Returns
true if user specified strings are converted to the case of the autocompletion
term they match; false otherwise. |
int |
getFilterMode()
Returns the manner in which the contents of the
ComboBoxModel are filtered. |
E |
getFirstItem()
Returns the optional single value used as the first element in the
ComboBoxModel or
null if no first item has been set. |
boolean |
getHidesPopupOnFocusLost()
Returns
true if the popup menu is hidden whenever the combo box editor loses focus;
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. |
TextFilterator<? super E> |
getTextFilterator()
Returns the
TextFilterator that extracts searchable strings from each item in the
ComboBoxModel . |
Object |
getTextMatchingStrategy()
Returns the manner in which the contents of the
ComboBoxModel are filtered and
autocompletion terms are matched. |
static <E> AutoCompleteSupport<E> |
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<? super E> filterator)
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<? super E> filterator,
Format format)
Installs support for autocompletion into the
comboBox and returns the support
object that is actually providing those facilities. |
boolean |
isInstalled()
Returns
true if this autocomplete support instance is currently installed and altering
the behaviour of the combo box; false if it has been uninstall() ed. |
boolean |
isStrict()
Returns
true if the user is able to specify values which do not appear in the popup
list of suggestions; false otherwise. |
E |
removeFirstItem()
Removes and returns the optional single value used as the first element in the
ComboBoxModel or null if no first item has been set. |
void |
setBeepOnStrictViolation(boolean beepOnStrictViolation)
Sets the policy for indicating strict-mode violations to the user by way of a beep sound.
|
void |
setCorrectsCase(boolean correctCase)
If
correctCase is true , user specified strings will be converted to the
case of the element they match. |
void |
setFilterMode(int mode)
Sets the manner in which the contents of the
ComboBoxModel are filtered. |
void |
setFirstItem(E item)
This method set a single optional value to be used as the first element in the
ComboBoxModel . |
void |
setHidesPopupOnFocusLost(boolean hidesPopupOnFocusLost)
If
hidesPopupOnFocusLost is true , then the popup menu of the combo box is
always hidden whenever the combo box editor loses focus. |
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 false , the user can specify values not appearing within the
ComboBoxModel. |
void |
setTextMatchingStrategy(Object strategy)
Sets the manner in which the contents of the
ComboBoxModel are filtered and
autocompletion terms are matched. |
void |
uninstall()
This method removes autocompletion support from the
JComboBox it was installed on. |
public static <E> AutoCompleteSupport<E> install(JComboBox comboBox, EventList<E> items)
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()
.
The following must be true in order to successfully install support for autocompletion on a
JComboBox
:
JTextField
as its editor component
AbstractDocument
as its model
comboBox
- the JComboBox
to decorate with autocompletionitems
- the objects to display in the comboBox
IllegalStateException
- if this method is called from any Thread other than the Swing
Event Dispatch Threadpublic static <E> AutoCompleteSupport<E> install(JComboBox comboBox, EventList<E> items, TextFilterator<? super E> filterator)
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()
.
The filterator
will be used to extract searchable text strings from each of the
items
. A null
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 a
JComboBox
:
JTextField
as its editor component
AbstractDocument
as its model
comboBox
- the JComboBox
to decorate with autocompletionitems
- the objects to display in the comboBox
filterator
- extracts searchable text strings from each item; null
implies
the item's toString() method should be used when filtering itIllegalStateException
- if this method is called from any Thread other than the Swing
Event Dispatch Threadpublic static <E> AutoCompleteSupport<E> install(JComboBox comboBox, EventList<E> items, TextFilterator<? super E> filterator, Format format)
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 uses the given format
to convert the given items
into
Strings and back again. In other words, this method does NOT rely on
Object.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 given format
are:
As a convenience, this method will install a custom ListCellRenderer
on the
comboBox
that displays the String value returned by the format
.
Though this is only done if the given format
is not null
and if the
comboBox
does not already use a custom renderer.
The filterator
will be used to extract searchable text strings from each of the
items
. A null
filterator implies one of two default strategies will
be used. If the format
is not null then the String value returned from the
format
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 a
JComboBox
:
JTextField
as its editor component
AbstractDocument
as its model
comboBox
- the JComboBox
to decorate with autocompletionitems
- the objects to display in the comboBox
filterator
- extracts searchable text strings from each item. If the format
is not null then the String value returned from the format
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 converting items
into Strings and back.
null
indicates the standard JComboBox methods of converting are
acceptable.IllegalStateException
- if this method is called from any Thread other than the Swing
Event Dispatch Threadpublic JComboBox getComboBox()
public TextFilterator<? super E> getTextFilterator()
TextFilterator
that extracts searchable strings from each item in the
ComboBoxModel
.public EventList<E> getItemList()
EventList
of items which backs the ComboBoxModel
of the
autocompleting JComboBox
.public boolean getCorrectsCase()
true
if user specified strings are converted to the case of the autocompletion
term they match; false
otherwise.public void setCorrectsCase(boolean correctCase)
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.
IllegalStateException
- if this method is called from any Thread other than the Swing
Event Dispatch ThreadsetStrict(boolean)
public boolean isStrict()
true
if the user is able to specify values which do not appear in the popup
list of suggestions; false
otherwise.public void setStrict(boolean strict)
strict
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.
IllegalStateException
- if this method is called from any Thread other than the Swing
Event Dispatch ThreadsetCorrectsCase(boolean)
public boolean getBeepOnStrictViolation()
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 if
isStrict()
returns true
.setStrict(boolean)
public void setBeepOnStrictViolation(boolean beepOnStrictViolation)
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
playedIllegalStateException
- if this method is called from any Thread other than the Swing
Event Dispatch Threadpublic boolean getSelectsTextOnFocusGain()
true
if the combo box editor text is selected when it gains focus;
false
otherwise.public void setSelectsTextOnFocusGain(boolean selectsTextOnFocusGain)
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.IllegalStateException
- if this method is called from any Thread other than the Swing
Event Dispatch Threadpublic boolean getHidesPopupOnFocusLost()
true
if the popup menu is hidden whenever the combo box editor loses focus;
false
otherwise.public void setHidesPopupOnFocusLost(boolean hidesPopupOnFocusLost)
hidesPopupOnFocusLost
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.IllegalStateException
- if this method is called from any Thread other than the Swing
Event Dispatch Threadpublic int getFilterMode()
ComboBoxModel
are filtered. This method
will return one of TextMatcherEditor.CONTAINS
or TextMatcherEditor.STARTS_WITH
.
TextMatcherEditor.CONTAINS
indicates elements of the ComboBoxModel
are matched
when they contain the text entered by the user.
TextMatcherEditor.STARTS_WITH
indicates elements of the ComboBoxModel
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 void setFilterMode(int mode)
ComboBoxModel
are filtered. The given
mode
must be one of TextMatcherEditor.CONTAINS
or
TextMatcherEditor.STARTS_WITH
.IllegalStateException
- if this method is called from any Thread other than the Swing
Event Dispatch ThreadgetFilterMode()
public void setTextMatchingStrategy(Object strategy)
ComboBoxModel
are filtered and
autocompletion terms are matched. The given strategy
must be one of
TextMatcherEditor.IDENTICAL_STRATEGY
or TextMatcherEditor.NORMALIZED_STRATEGY
or the Unicode strategy of the ICU4J extension.IllegalStateException
- if this method is called from any Thread other than the Swing
Event Dispatch ThreadgetTextMatchingStrategy()
public Object getTextMatchingStrategy()
ComboBoxModel
are filtered and
autocompletion terms are matched. The returned strategy
is one of
TextMatcherEditor.IDENTICAL_STRATEGY
or TextMatcherEditor.NORMALIZED_STRATEGY
or the Unicode strategy of the ICU4J extension.public void setFirstItem(E item)
ComboBoxModel
. This value typically represents "no selection" or "blank". This value is
always present and is not filtered away during autocompletion.item
- the first value to present in the ComboBoxModel
public E getFirstItem()
ComboBoxModel
or
null
if no first item has been set.ComboBoxModel
or null
if no
first item has been setpublic E removeFirstItem()
ComboBoxModel
or null
if no first item has been set.ComboBoxModel
or null
if no
first item has been setpublic boolean isInstalled()
true
if this autocomplete support instance is currently installed and altering
the behaviour of the combo box; false
if it has been uninstall()
ed.IllegalStateException
- if this method is called from any Thread other than the Swing
Event Dispatch Threadpublic void uninstall()
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.IllegalStateException
- if this method is called from any Thread other than the Swing
Event Dispatch Threadpublic static <E> AutoCompleteSupport.AutoCompleteCellEditor<E> createTableCellEditor(TableFormat<E> tableFormat, EventList<E> tableData, int columnIndex)
AutoCompleteSupport.AutoCompleteCellEditor
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
.
This version of createTableCellEditor
assumes that the values stored in the
TableModel at the given columnIndex
are all Comparable
, and that the
natural ordering defined by those Comparable
values also determines which are
duplicates (and thus can safely be removed) and which are unique (and thus must remain in the
ComboBoxModel
).
Note that this factory method is only appropriate for use when the values in the
ComboBoxModel
should be the unique set of values in a table column. If some other list
of values will be used then createTableCellEditor(EventList)
is the appropriate
factory method to use.
If the appearance or function of the autocompleting JComboBox
is to be customized, it
can be retrieved using DefaultCellEditor.getComponent()
.
tableFormat
- specifies how each row object within a table is broken apart into column
valuestableData
- the EventList
backing the TableModelcolumnIndex
- the index of the column for which to return a AutoCompleteSupport.AutoCompleteCellEditor
AutoCompleteSupport.AutoCompleteCellEditor
which contains an autocompleting combobox whose
contents remain consistent with the data in the table column at the given
columnIndex
public static <E> AutoCompleteSupport.AutoCompleteCellEditor<E> createTableCellEditor(Comparator uniqueComparator, TableFormat<E> tableFormat, EventList<E> tableData, int columnIndex)
AutoCompleteSupport.AutoCompleteCellEditor
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
.
This version of createTableCellEditor
makes no assumption about the values stored
in the TableModel at the given columnIndex
. Instead, it uses the given
uniqueComparator
to determine which values are duplicates (and thus can safely be
removed) and which are unique (and thus must remain in the ComboBoxModel
).
Note that this factory method is only appropriate for use when the values in the
ComboBoxModel
should be the unique set of values in a table column. If some other list
of values will be used then createTableCellEditor(EventList)
is the appropriate
factory method to use.
If the appearance or function of the autocompleting JComboBox
is to be customized, it
can be retrieved using DefaultCellEditor.getComponent()
.
uniqueComparator
- the Comparator
that strips away duplicate elements from the
ComboBoxModel
tableFormat
- specifies how each row object within a table is broken apart into column
valuestableData
- the EventList
backing the TableModelcolumnIndex
- the index of the column for which to return a AutoCompleteSupport.AutoCompleteCellEditor
AutoCompleteSupport.AutoCompleteCellEditor
which contains an autocompleting combobox whose
contents remain consistent with the data in the table column at the given
columnIndex
public static <E> AutoCompleteSupport.AutoCompleteCellEditor<E> createTableCellEditor(EventList<E> source)
AutoCompleteSupport.AutoCompleteCellEditor
which adapts an
autocompleting JComboBox
for use as a Table Cell Editor. The values within the
source
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()
.
source
- the source of data for the JComboBox within the table cell editorAutoCompleteSupport.AutoCompleteCellEditor
which contains an autocompleting combobox whose model
contents are determined by the given source
Copyright © 2024 levigo holding gmbh. All rights reserved.