| java.lang.Object
 com.jidesoft.swing.Searchable
All known Subclasses: com.jidesoft.swing.ListSearchable, com.jidesoft.swing.ComboBoxSearchable, com.jidesoft.swing.TextComponentSearchable, com.jidesoft.swing.TreeSearchable, com.jidesoft.swing.TableSearchable,
| Searchable | | abstract public class Searchable (Code) | | JList, JTable and JTree are three data-rich components. They can be used
to display a huge amount of data so searching function will be very a useful feature in those components.
Searchable is such a class that can make JList, JTable and JTree searchable.
User can simply type in any string they want to search for and use arrow keys to navigate
to next or previous occurrence.
Searchable is a base abstract class. ListSearchable, TableSearchable and TreeSearchable
are implementations to make JList, JTable and JTree searchable respectively. For each implementation, there are
five methods need to be implemented.
protected abstract int getSelectedIndex()
protected abstract void setSelectedIndex(int index, boolean incremental)
protected abstract int getElementCount()
protected abstract Object getElementAt(int index)
protected abstract String convertElementToString(Object element)
Please look at the javadoc of each method to learn more details.
The keys used by this class are fully customizable. Subclass can override the methods such as
Searchable.isActivateKey(java.awt.event.KeyEvent) ,
Searchable.isDeactivateKey(java.awt.event.KeyEvent) ,
Searchable.isFindFirstKey(java.awt.event.KeyEvent) ,
Searchable.isFindLastKey(java.awt.event.KeyEvent) ,
Searchable.isFindNextKey(java.awt.event.KeyEvent) ,
Searchable.isFindPreviousKey(java.awt.event.KeyEvent) to provide its own set of keys.
In addition to press up/down arrow to find next occurrence or previous occurrence of
particular string, there are several other features that are very handy.
Multiple selection feature - If you press CTRL key and hold it while pressing up and down arrow,
it will find next/previous occurence while keeping existing selections.
Select all feature - If you type in a searching text and press CTRL+A, all the occurrences of
that searching string will be selected. This is a very handy feature.
For example you want to delete all rows in a table whose name column begins with "old".
So you can type in "old" and press CTRL+A, now all rows begining with "old" will
be selected. Pressing delete will delete all of them.
Basic regular expression support - It allows '?' to match any letter or digit,
or '*' to match several letters or digits.
Even though it's possible to implement full regular expression support, we don't want to do that.
The reason is the regular expression is very complex, it's probably not a good idea to let user
type in such a complex expression in a small popup window. However if your user is very familiar
with regular expression, you can add the feature to Searchable. All you need to do
is to override
Searchable.compare(String,String) method
and implement by yourself.
As this is an abstract class, please refer to to javadoc of
ListSearchable ,
TreeSearchable , and
TableSearchable to find out
how to use it with JList, JTree and JTable respectively.
This component has a timer. If user types very fast, it will accumulate them together and generate only one searching action.
The timer can be controlled by
Searchable.setSearchingDelay(int) .
By default we will use lightweight popup for the sake of performance. But if you use heavyweight component
which could obscure the lightweight popup, you can call
Searchable.setHeavyweightComponentEnabled(boolean) to true
so that heavyweight popup will be used.
|
| Inner Class :protected class SearchField extends JTextField | |
| Inner Class :abstract public class SearchPopup extends JidePopup | |
| PROPERTY_SEARCH_TEXT | | final public static String PROPERTY_SEARCH_TEXT(Code) | | |
| Searchable | | public Searchable(JComponent component)(Code) | | Creates a Searchable.
Parameters:
component - component where the Searchable will be installed. |
| Searchable | | public Searchable(JComponent component, SearchableProvider searchableProvider)(Code) | | Creates a Searchable.
Parameters:
component - component where the Searchable will be installed. |
| addPropertyChangeListener | | public void addPropertyChangeListener(PropertyChangeListener propertychangelistener)(Code) | | Adds the property change listener. The only property change event that will be fired is the "searchText"
property which will be fired when user types in a different search text in the popup.
Parameters:
propertychangelistener - |
| addSearchableListener | | public void addSearchableListener(SearchableListener l)(Code) | | Adds the specified listener to receive searchable events from this
searchable.
Parameters:
l - the searchable listener |
| compare | | protected boolean compare(Object element, String searchingText)(Code) | | Checks if the element matches the searching text.
Parameters:
element -
Parameters:
searchingText - true if matches. |
| convertElementToString | | abstract protected String convertElementToString(Object element)(Code) | | Converts the element that returns from getElementAt() to string.
Parameters:
element - the string representing the element in the component. |
| createSearchPopup | | protected SearchPopup createSearchPopup(String searchingText)(Code) | | Creates the popup to hold the searching text.
Parameters:
searchingText - the searching popup. |
| findFirst | | public int findFirst(String s)(Code) | | Finds the first element that matches the searching text.
Parameters:
s - the first element that matches with the searching text. |
| findFromCursor | | public int findFromCursor(String s)(Code) | | Finds the next matching index from the cursor. If it reaches the end, it will restart from the beginning.
However is the reverseOrder flag is true, it will finds the previous matching index from the cursor. If it reaches
the beginning, it will restart from the end.
Parameters:
s - the next index that the element matches the searching text. |
| findLast | | public int findLast(String s)(Code) | | Finds the last element that matches the searching text.
Parameters:
s - the last element that matches the searching text. |
| findNext | | public int findNext(String s)(Code) | | Finds the next matching index from the cursor.
Parameters:
s - the next index that the element matches the searching text. |
| findPrevious | | public int findPrevious(String s)(Code) | | Finds the previous matching index from the cursor.
Parameters:
s - the previous index that the element matches the searching text. |
| firePropertyChangeEvent | | public void firePropertyChangeEvent(String searchingText)(Code) | | |
| fireSearchableEvent | | protected void fireSearchableEvent(SearchableEvent e)(Code) | | Fires a searchable event.
Parameters:
e - the event |
| getBackground | | public Color getBackground()(Code) | | Gets the background color used inn the search popup.
the background. By default it will use the background of tooltip. |
| getComponent | | public Component getComponent()(Code) | | Gets the actual component which installed this Searchable.
the actual component which installed this Searchable. |
| getCursor | | public int getCursor()(Code) | | Gets the cursor which is the index of current location when searching. The value will be
used in findNext and findPrevious.
the current position of the cursor. |
| getElementAt | | abstract protected Object getElementAt(int index)(Code) | | Gets the element at the specified index. The element could be any data structure that
internally used in the component. The convertElementToString method will give you a chance
to convert the element to string which is used to compare with the string that user types in.
Parameters:
index - the index the element at the specified index. |
| getElementCount | | abstract protected int getElementCount()(Code) | | Gets the total element count in the component. Different concrete implementation could have different interpretation of
the count. This is totally OK as long as it's consistent in all the methods. For example, the index parameter in other methods
should be always a valid value within the total count.
the total element count. |
| getForeground | | public Color getForeground()(Code) | | Gets the foreground color used inn the search popup.
the foreground. By default it will use the foreground of tooltip. |
| getMismatchForeground | | public Color getMismatchForeground()(Code) | | Gets the foreground color when the searching text doesn't match with any of the elements in the component.
the forground color for mismatch. If you never callSearchable.setMismatchForeground(java.awt.Color). red color will be used. |
| getPopupLocationRelativeTo | | public Component getPopupLocationRelativeTo()(Code) | | Gets the component that the location of the popup relative to.
the component that the location of the popup relative to. |
| getResourceString | | protected String getResourceString(String key)(Code) | | Gets the localized string from resource bundle. Subclass can override it to provide its own string.
Available keys are defined in swing.properties that begin with "Searchable.".
Parameters:
key - the localized string. |
| getSearchLabel | | public String getSearchLabel()(Code) | | Gets the current text that appears in the search popup. By default it is "Search for: ".
the text that appears in the search popup. |
| getSearchableListeners | | public SearchableListener[] getSearchableListeners()(Code) | | Returns an array of all the SearchableListeners added
to this SearchableGroup with
addSearchableListener.
all of the SearchableListeners added or an emptyarray if no listeners have been added
See Also: Searchable.addSearchableListener |
| getSearchingDelay | | public int getSearchingDelay()(Code) | | If it returns a positive number, it will wait for that many ms
before doing the search. When the searching is complex, this
flag will be useful to make the searching efficient. In the other words,
if user types in several keys very quickly, there will be only one search.
If it returns 0 or negative number, each key will generate a search.
the number of ms delay before searching starts. |
| getSearchingText | | public String getSearchingText()(Code) | | Gets the searching text.
the searching text. |
| getSelectedIndex | | abstract protected int getSelectedIndex()(Code) | | Gets the selected index in the component. The concrete implementation
should call methods on the component to retrieve the current selected index.
If the component supports multiple selection,
it's OK just return the index of the first selection.
Here are some examples. In the case of JList, the index is the row index.
In the case of JTree, the index is the row index too. In the case of JTable, depending on the seleection mode,
the index could be row index (in row selection mode), could be column index (in column selection mode)
or could the cell index (in cell selection mode).
the selected index. |
| hidePopup | | public void hidePopup()(Code) | | Hides the popup.
|
| installListeners | | public void installListeners()(Code) | | Installs necessary listeners to the component. This method will be called automatically when Searchable is created.
|
| isActivateKey | | protected boolean isActivateKey(KeyEvent e)(Code) | | Checks if the key in KeyEvent should activate the search popup.
Parameters:
e - true if the keyChar is a letter or a digit or '*' or '?'. |
| isCaseSensitive | | public boolean isCaseSensitive()(Code) | | Checks if the case is sensitive during searching.
true if the searching is case sensitive. |
| isDeactivateKey | | protected boolean isDeactivateKey(KeyEvent e)(Code) | | Checks if the key in KeyEvent should hide the search popup. If this method return true and
the key is not used for navigation purpose (
Searchable.isNavigationKey(java.awt.event.KeyEvent) return false), the popup will be hidden.
Parameters:
e - true if the keyCode in the KeyEvent is escape key, enter key,or any of the arrow keys such as page up, page down, home, end, left, right, up and down. |
| isFindFirstKey | | protected boolean isFindFirstKey(KeyEvent e)(Code) | | Checks if the key is used as a key to find the first occurence.
Parameters:
e - true if the key in KeyEvent is a key to find the first occurence. By default, home key is used. |
| isFindLastKey | | protected boolean isFindLastKey(KeyEvent e)(Code) | | Checks if the key is used as a key to find the last occurence.
Parameters:
e - true if the key in KeyEvent is a key to find the last occurence. By default, end key is used. |
| isFindNextKey | | protected boolean isFindNextKey(KeyEvent e)(Code) | | Checks if the key is used as a key to find the next occurence.
Parameters:
e - true if the key in KeyEvent is a key to find the next occurence. By default, down arrow key is used. |
| isFindPreviousKey | | protected boolean isFindPreviousKey(KeyEvent e)(Code) | | Checks if the key is used as a key to find the previous occurence.
Parameters:
e - true if the key in KeyEvent is a key to find the previous occurence. By default, up arrow key is used. |
| isHeavyweightComponentEnabled | | public boolean isHeavyweightComponentEnabled()(Code) | | |
| isIncrementalSelectKey | | protected boolean isIncrementalSelectKey(KeyEvent e)(Code) | | Checks if the key will trigger incremental selection.
Parameters:
e - true if the key in KeyEvent is a key to trigger incremental selection. By default, ctrl down key is used. |
| isNavigationKey | | protected boolean isNavigationKey(KeyEvent e)(Code) | | Checks if the key is used as a navigation key. Navigation keys are keys which are used to
navigate to other occurences of the searching string.
Parameters:
e - true if the key in KeyEvent is a navigation key. |
| isPopupVisible | | public boolean isPopupVisible()(Code) | | Check if the searchable popup is visible.
true if visible. Otherwise, false. |
| isRepeats | | public boolean isRepeats()(Code) | | Checks if restart from the beginning when searching reaches the end
or restart from the end when reaches beginning. Default is false.
true or false. |
| isReverseOrder | | public boolean isReverseOrder()(Code) | | Checks the searching order. By default the searchable starts searching from top to bottom. If this flag
is false, it searchs from bottom to top.
the reverseOrder flag. |
| isSelectAllKey | | protected boolean isSelectAllKey(KeyEvent e)(Code) | | Checks if the key will trigger selecting all.
Parameters:
e - true if the key in KeyEvent is a key to trigger selecting all. |
| isWildcardEnabled | | public boolean isWildcardEnabled()(Code) | | Checks if it supports wildcard in searching text. By default it is true which means user can type
in "*" or "?" to match with any charactors or any charactor. If it's false, it will treat "*" or "?"
as a regular charactor.
true if it supports wildcard. |
| keyTypedOrPressed | | protected void keyTypedOrPressed(KeyEvent e)(Code) | | This method is called when a key is typed or pressed.
Parameters:
e - the KeyEvent. |
| removePropertyChangeListener | | public void removePropertyChangeListener(PropertyChangeListener propertychangelistener)(Code) | | Removes the property change listener.
Parameters:
propertychangelistener - |
| removeSearchableListener | | public void removeSearchableListener(SearchableListener l)(Code) | | Removes the specified searchable listener so that it no longer
receives searchable events.
Parameters:
l - the searchable listener |
| reverseFindFromCursor | | public int reverseFindFromCursor(String s)(Code) | | Finds the previous matching index from the cursor. If it reaches the beginning, it will restart from the end.
Parameters:
s - the next index that the element matches the searching text. |
| setBackground | | public void setBackground(Color background)(Code) | | Sets the background color used by popup.
Parameters:
background - |
| setCaseSensitive | | public void setCaseSensitive(boolean caseSensitive)(Code) | | Sets the case sensitive flag. By default, it's false meaning it's a case insensitive search.
Parameters:
caseSensitive - |
| setCursor | | public void setCursor(int cursor)(Code) | | Sets the cursor which is the index of current location when searching. The value will be
used in findNext and findPrevious.
Parameters:
cursor - the new position of the cursor. |
| setForeground | | public void setForeground(Color foreground)(Code) | | Sets the foreground color used by popup.
Parameters:
foreground - |
| setHeavyweightComponentEnabled | | public void setHeavyweightComponentEnabled(boolean heavyweightComponentEnabled)(Code) | | |
| setMismatchForeground | | public void setMismatchForeground(Color mismatchForeground)(Code) | | Sets the foreground for mismatch.
Parameters:
mismatchForeground - |
| setPopupLocationRelativeTo | | public void setPopupLocationRelativeTo(Component popupLocationRelativeTo)(Code) | | Sets the location of the popup relative to the specified component. Then based on the value of
Searchable.getPopupLocation() . If you never set, we will use the searchable component or its scroll pane (if exists)
as the popupLocationRelativeTo component.
Parameters:
popupLocationRelativeTo - |
| setRepeats | | public void setRepeats(boolean repeats)(Code) | | Sets the repeat flag. By default, it's false meaning it will stop searching
when reaching the end or reaching the beginning.
Parameters:
repeats - |
| setReverseOrder | | public void setReverseOrder(boolean reverseOrder)(Code) | | Sets the searching order. By default the searchable starts searching from top to bottom. If this flag
is false, it searchs from bottom to top.
Parameters:
reverseOrder - |
| setSearchLabel | | public void setSearchLabel(String searchLabel)(Code) | | Sets the text that appears in the search popup.
Parameters:
searchLabel - |
| setSearchingDelay | | public void setSearchingDelay(int searchingDelay)(Code) | | If this flag is set to a positive number, it will wait for that many ms
before doing the search. When the searching is complex, this
flag will be useful to make the searching efficient. In the other words,
if user types in several keys very quickly, there will be only one search.
If this flag is set to 0 or a negative number, each key will generate a search with no delay.
Parameters:
searchingDelay - the number of ms delay before searching start. |
| setSelectedIndex | | abstract protected void setSelectedIndex(int index, boolean incremental)(Code) | | Sets the selected index. The concrete implementation should call methods on the component to select
the element at the specified index. The incremental flag is used to do multiple select. If the flag is true,
the element at the index should be added to current selection. If false, you should clear previous
selection and then select the element.
Parameters:
index - the index to be selected
Parameters:
incremental - a flag to enable multiple selection. If the flag is true,the element at the index should be added to current selection. If false, you should clear previousselection and then select the element. |
| setWildcardEnabled | | public void setWildcardEnabled(boolean wildcardEnabled)(Code) | | Enable or disable the usage of wildcard.
Parameters:
wildcardEnabled -
See Also: Searchable.isWildcardEnabled() |
| showPopup | | public void showPopup(String searchingText)(Code) | | Shows the search popup. By default, the search popup will be visible
automatically when user types in the first key (in the case of JList, JTree, JTable)
or types in designated keystroke (in the case of JTextComponent). So this method is only
used when you want to show the popup manually.
Parameters:
searchingText - |
| uninstallListeners | | public void uninstallListeners()(Code) | | Uninstall the listeners that installed before. This method is never called because
we don't have the control of the life cyle of the component. However you can call this
method if you don't want the searchable component not searchable.
|
|
|