T - the element type in the control.public abstract class Searchable<T>
extends java.lang.Object
The Searchable feature is to that user can type a character, the control will find the first entry that matches with the character. Searchable is such a class that makes it possible. An end user can simply type any string they want to search for and use arrow keys to navigate to the next or previous occurrence. See below for the list of controls that support searchable.
The main purpose of searchable is to make the searching for a particular string easier in a control having a lot of information. All features are related to how to make it quicker and easier to identify the matching text.
Navigation feature - After user types in a text and presses the up or down arrow keys, only items that match with the typed text will be selected. User can press the up and down keys to quickly look at what those items are. In addition, end users can use the home key in order to navigate to the first occurrence. Likewise, the end key will navigate to the last occurrence. The navigation keys are fully customizable. The next section will explain how to customize them.
Multiple selection feature - If you press and hold CTRL key while pressing up and down arrow, it will find next/previous occurrence while keeping existing selections. See the screenshot below. This way one can easily find several occurrences and apply an action to all of them later.
Select all feature ? Further extending the multiple selections feature, you can even select all. If you type in a searching text and press CTRL+A, all the occurrences matching the searching text 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". You can type in "old" and press CTRL+A, now all rows beginning with "old" will be selected. If you hook up delete key with the table, pressing delete key will delete all selected rows. Imagine without this searchable feature, users will have to hold CTRL key, look through each row, and click on the row they want to delete. In case they forgot to hold tight the CTRL key while clicking, they have to start over again.
Basic regular expression support - It allows '?' to match any character and '*' to match any number of characters. For example "a*c" will match "ac", "abc", "abbbc", or even "a b c" etc. "a?c" will only match "abc" or "a c".
Recursive search (only in TreeViewSearchable) ? In the case of TreeSearchable, there is an option called recursive. You can call TreeViewSearchable#setRecursive(true/false) to change it. If TreeViewSearchable is recursive, it will search all tree nodes including those, which are not visible to find the matching node. Obviously, if your tree has unlimited number of tree nodes or a potential huge number of tree nodes (such as a tree to represent file system), the recursive attribute should be false. To avoid this potential problem in this case, we default it to false.
Popup position ? the search popup position can be customized using setPopupPosition method using the JavaFX Pos. We currently only support TOP_XXX and BOTTOM_XXX total six positions. Furthermore, you can use setPopupPositionRelativeTo method to specify a Node which will be used to determine which Node the Pos is relative to.
Please refer to the JideFX Common Layer Developer Guide for more information.
| Type | Property and Description |
|---|---|
javafx.beans.property.BooleanProperty |
caeSensitive |
javafx.beans.property.BooleanProperty |
fromStart |
javafx.beans.property.ObjectProperty<T> |
matchingElement |
javafx.beans.property.IntegerProperty |
matchingIndex |
javafx.beans.property.ObjectProperty<javafx.geometry.Pos> |
popupPosition |
javafx.beans.property.ObjectProperty<javafx.scene.Node> |
popupPositionRelativeTo |
javafx.beans.property.BooleanProperty |
repeats |
javafx.beans.property.ObjectProperty<javafx.util.Duration> |
searchingDelay |
javafx.beans.property.StringProperty |
searchingLabel |
javafx.beans.property.BooleanProperty |
searching |
javafx.beans.property.StringProperty |
searchingText |
javafx.beans.property.StringProperty |
typedText |
javafx.beans.property.BooleanProperty |
wildcardEnabled |
| Modifier and Type | Class and Description |
|---|---|
protected class |
Searchable.SearchPopup |
| Modifier and Type | Field and Description |
|---|---|
protected javafx.beans.value.ChangeListener<javafx.geometry.Bounds> |
_boundsListener |
protected javafx.event.EventHandler<javafx.scene.input.KeyEvent> |
_keyListener |
protected javafx.scene.Node |
_node |
protected javafx.beans.value.ChangeListener<java.lang.Boolean> |
_visibleListener |
static java.lang.String |
PROPERTY_SEARCHABLE
The client property for Searchable instance.
|
| Constructor and Description |
|---|
Searchable(javafx.scene.Node node)
Creates a Searchable.
|
| Modifier and Type | Method and Description |
|---|---|
void |
adjustSelectedIndex(int index,
boolean incremental)
Sets the selected index.
|
javafx.beans.property.BooleanProperty |
caeSensitiveProperty() |
protected boolean |
compare(T element,
java.lang.String searchingText)
Checks if the element matches the searching text.
|
protected boolean |
compareAsString(java.lang.String text,
java.lang.String searchingText)
Checks if the element string matches the searching text.
|
protected abstract java.lang.String |
convertElementToString(T element)
Converts the element that returns from getElementAt() to string.
|
protected Searchable.SearchPopup |
createSearchPopup()
Creates the popup to hold the searching text.
|
java.util.List<java.lang.Integer> |
findAll(java.lang.String s)
findAll uses the Searchable to find all the element indices that match the searching string. |
int |
findFirst(java.lang.String s)
Finds the first element that matches the searching text.
|
int |
findFromCursor(java.lang.String s)
Finds the next matching index from the cursor.
|
int |
findLast(java.lang.String s)
Finds the last element that matches the searching text.
|
int |
findNext(java.lang.String s)
Finds the next matching index from the cursor.
|
int |
findPrevious(java.lang.String s)
Finds the previous matching index from the cursor.
|
javafx.beans.property.BooleanProperty |
fromStartProperty() |
protected int |
getCurrentIndex() |
int |
getCursor()
Gets the cursor which is the index of current location when searching.
|
protected abstract T |
getElementAt(int index)
Gets the element at the specified index.
|
java.lang.String |
getElementAtAsString(int index)
Gets the element at the specified index as string using
convertElementToString(Object) method. |
protected abstract int |
getElementCount()
Gets the total element count in the control.
|
javafx.util.Duration |
getHidePopupDelay()
Gets the duration before hiding the popup.
|
T |
getMatchingElement()
Gets the value of the property matchingElement.
|
int |
getMatchingIndex()
Gets the value of the property matchingIndex.
|
javafx.scene.Node |
getNode()
Gets the actual node which installed this Searchable.
|
javafx.geometry.Pos |
getPopupPosition()
Gets the popup position.
|
javafx.scene.Node |
getPopupPositionRelativeTo()
Gets the node that the position of the popup relative to.
|
protected java.lang.String |
getResourceString(java.lang.String key)
Gets the localized string from resource bundle.
|
static Searchable |
getSearchable(javafx.scene.Node node)
Gets the Searchable installed on the node.
|
javafx.util.Duration |
getSearchingDelay()
If it returns a positive number, it will wait for that many ms before doing the search.
|
java.lang.String |
getSearchingText()
Gets the value of the property searchingText.
|
java.lang.String |
getSearchLabel()
Gets the current text that appears in the search popup.
|
protected abstract int |
getSelectedIndex()
Gets the selected index in the control.
|
WildcardSupport |
getWildcardSupport()
Gets the WildcardSupport.
|
void |
hidePopup()
Hides the popup.
|
protected void |
highlightAll()
Highlight all matching cases in the target.
|
void |
installListeners()
Installs necessary listeners to the control.
|
protected boolean |
isActivateKey(javafx.scene.input.KeyEvent e)
Checks if the key in KeyEvent should activate the search popup.
|
boolean |
isCaseSensitive()
Checks if the case is sensitive during searching.
|
protected boolean |
isDeactivateKey(javafx.scene.input.KeyEvent e)
Checks if the key in KeyEvent should hide the search popup.
|
protected boolean |
isFindFirstKey(javafx.scene.input.KeyEvent e)
Checks if the key is used as a key to find the first occurrence.
|
protected boolean |
isFindLastKey(javafx.scene.input.KeyEvent e)
Checks if the key is used as a key to find the last occurrence.
|
protected boolean |
isFindNextKey(javafx.scene.input.KeyEvent e)
Checks if the key is used as a key to find the next occurrence.
|
protected boolean |
isFindPreviousKey(javafx.scene.input.KeyEvent e)
Checks if the key is used as a key to find the previous occurrence.
|
boolean |
isFromStart()
This is a property of how to compare searching text with the data.
|
protected boolean |
isIncrementalSelectKey(javafx.scene.input.KeyEvent e)
Checks if the key will trigger incremental selection.
|
protected boolean |
isNavigationKey(javafx.scene.input.KeyEvent e)
Checks if the key is used as a navigation key.
|
boolean |
isPopupVisible()
Check if the searchable popup is visible.
|
boolean |
isRepeats()
Checks if restart from the beginning when searching reaches the end or restart from the end when reaches
beginning.
|
boolean |
isReverseOrder()
Checks the searching order.
|
boolean |
isSearching()
Gets the value of the property searching.
|
protected boolean |
isSelectAllKey(javafx.scene.input.KeyEvent e)
Checks if the key will trigger selecting all.
|
boolean |
isWildcardEnabled()
Checks if it supports wildcard in searching text.
|
protected void |
keyTypedOrPressed(javafx.scene.input.KeyEvent e)
This method is called when a key is typed or pressed.
|
javafx.beans.property.ObjectProperty<T> |
matchingElementProperty() |
javafx.beans.property.IntegerProperty |
matchingIndexProperty() |
javafx.beans.property.ObjectProperty<javafx.geometry.Pos> |
popupPositionProperty() |
javafx.beans.property.ObjectProperty<javafx.scene.Node> |
popupPositionRelativeToProperty() |
javafx.beans.property.BooleanProperty |
repeatsProperty() |
int |
reverseFindFromCursor(java.lang.String s)
Finds the previous matching index from the cursor.
|
javafx.beans.property.ObjectProperty<javafx.util.Duration> |
searchingDelayProperty() |
javafx.beans.property.StringProperty |
searchingLabelProperty() |
javafx.beans.property.BooleanProperty |
searchingProperty() |
javafx.beans.property.StringProperty |
searchingTextProperty() |
protected void |
select(int index)
Select the index for the searching text.
|
void |
setCaseSensitive(boolean caseSensitive)
Sets the case sensitive flag.
|
void |
setCursor(int cursor)
Sets the cursor which is the index of current location when searching.
|
void |
setCursor(int cursor,
boolean incremental)
Sets the cursor which is the index of current location when searching.
|
void |
setFromStart(boolean fromStart)
Sets the fromStart property.
|
void |
setHidePopupDelay(javafx.util.Duration hidePopupDelay)
Sets the delay before hiding the popup.
|
void |
setMatchingElement(T matchingElement)
Sets the value of the property matchingElement.
|
void |
setMatchingIndex(int matchingIndex)
Sets the value of the property matchingIndex.
|
void |
setPopupPosition(javafx.geometry.Pos popupPosition)
Sets the popup position.
|
void |
setPopupPositionRelativeTo(javafx.scene.Node popupPositionRelativeTo)
Sets the position of the popup relative to the specified node.
|
void |
setRepeats(boolean repeats)
Sets the repeat flag.
|
void |
setReverseOrder(boolean reverseOrder)
Sets the searching order.
|
void |
setSearching(boolean searching)
Sets the value of the property searching.
|
void |
setSearchingDelay(javafx.util.Duration searchingDelay)
If this flag is set to Duration, it will wait for that many ms before doing the search.
|
void |
setSearchingText(java.lang.String searchingText)
Sets the value of the property searchingText.
|
void |
setSearchLabel(java.lang.String searchLabel)
Sets the text that appears in the search popup.
|
protected abstract void |
setSelectedIndex(int index,
boolean incremental)
Sets the selected index.
|
void |
setWildcardEnabled(java.lang.Boolean wildcardEnabled)
Enable or disable the usage of wildcard.
|
void |
setWildcardSupport(WildcardSupport wildcardSupport)
Sets the WildcardSupport.
|
void |
showPopup(java.lang.String searchingText)
Shows the search popup.
|
javafx.beans.property.StringProperty |
typedTextProperty() |
void |
uninstallListeners()
Uninstall the listeners that installed before.
|
javafx.beans.property.BooleanProperty |
wildcardEnabledProperty() |
public javafx.beans.property.BooleanProperty caeSensitiveProperty
public javafx.beans.property.ObjectProperty<javafx.util.Duration> searchingDelayProperty
getSearchingDelay(),
setSearchingDelay(Duration)public javafx.beans.property.BooleanProperty repeatsProperty
isRepeats(),
setRepeats(boolean)public javafx.beans.property.BooleanProperty wildcardEnabledProperty
isWildcardEnabled(),
setWildcardEnabled(Boolean)public javafx.beans.property.StringProperty searchingLabelProperty
public javafx.beans.property.ObjectProperty<javafx.geometry.Pos> popupPositionProperty
getPopupPosition(),
setPopupPosition(Pos)public javafx.beans.property.ObjectProperty<javafx.scene.Node> popupPositionRelativeToProperty
public javafx.beans.property.StringProperty searchingTextProperty
getSearchingText(),
setSearchingText(String)public javafx.beans.property.StringProperty typedTextProperty
public javafx.beans.property.BooleanProperty searchingProperty
isSearching(),
setSearching(boolean)public javafx.beans.property.IntegerProperty matchingIndexProperty
getMatchingIndex(),
setMatchingIndex(int)public javafx.beans.property.ObjectProperty<T> matchingElementProperty
getMatchingElement(),
setMatchingElement(T)public javafx.beans.property.BooleanProperty fromStartProperty
isFromStart(),
setFromStart(boolean)protected final javafx.scene.Node _node
protected javafx.beans.value.ChangeListener<java.lang.Boolean> _visibleListener
protected javafx.beans.value.ChangeListener<javafx.geometry.Bounds> _boundsListener
protected javafx.event.EventHandler<javafx.scene.input.KeyEvent> _keyListener
public static final java.lang.String PROPERTY_SEARCHABLE
public Searchable(javafx.scene.Node node)
node - node where the Searchable will be installed.protected abstract int getSelectedIndex()
Here are some examples. In the case of ListView, the index is the row index. In the case of TreeView, the index is the row index too. In the case of TableView, depending on the selection mode, the index could be row index (in row selection mode), or could be the cell index (in cell selection mode).
protected abstract void setSelectedIndex(int index,
boolean incremental)
index - the index to be selectedincremental - 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 previous selection and then select the
element.public void adjustSelectedIndex(int index,
boolean incremental)
setSelectedIndex(int, boolean).
Please do NOT try to override this method. Always override setSelectedIndex(int, boolean) instead.
index - the index to be selectedincremental - 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 previous selection and then select the
element.protected abstract int getElementCount()
protected abstract T getElementAt(int index)
index - the indexprotected abstract java.lang.String convertElementToString(T element)
element - the element to be convertedpublic void hidePopup()
public void installListeners()
public void uninstallListeners()
protected boolean compare(T element, java.lang.String searchingText)
element - the element to be checkedsearchingText - the searching textprotected boolean compareAsString(java.lang.String text,
java.lang.String searchingText)
compare(Object, String), this
method is after the element has been converted to string using convertElementToString(Object).text - the text to be checkedsearchingText - the searching textpublic int getCursor()
public void setCursor(int cursor)
cursor - the new position of the cursor.public void setCursor(int cursor,
boolean incremental)
setSelectedIndex(int, boolean) method from your code, you should call this method with the same parameters.cursor - the new position of the cursor.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 previous selection and then select the
element.protected void highlightAll()
In default implementation, it will just search all texts in the target to highlight all. If you have a really huge text to search, you may want to override this method to have a lazy behavior on visible areas only.
protected void select(int index)
index - the start offsetpublic int findNext(java.lang.String s)
s - the searching textprotected int getCurrentIndex()
public int findPrevious(java.lang.String s)
s - the searching textpublic int findFromCursor(java.lang.String s)
s - the searching textpublic int reverseFindFromCursor(java.lang.String s)
s - the searching textpublic int findFirst(java.lang.String s)
s - the searching textpublic int findLast(java.lang.String s)
s - the searching textprotected void keyTypedOrPressed(javafx.scene.input.KeyEvent e)
e - the KeyEvent.public void showPopup(java.lang.String searchingText)
searchingText - the searching textprotected Searchable.SearchPopup createSearchPopup()
protected boolean isFindFirstKey(javafx.scene.input.KeyEvent e)
e - the key eventprotected boolean isFindLastKey(javafx.scene.input.KeyEvent e)
e - the key eventprotected boolean isFindPreviousKey(javafx.scene.input.KeyEvent e)
e - the key eventprotected boolean isFindNextKey(javafx.scene.input.KeyEvent e)
e - the key eventprotected boolean isNavigationKey(javafx.scene.input.KeyEvent e)
e - the key eventprotected boolean isActivateKey(javafx.scene.input.KeyEvent e)
e - the key eventprotected boolean isDeactivateKey(javafx.scene.input.KeyEvent e)
isNavigationKey(KeyEvent) return false), the popup will be hidden.e - the key eventprotected boolean isSelectAllKey(javafx.scene.input.KeyEvent e)
e - the key eventprotected boolean isIncrementalSelectKey(javafx.scene.input.KeyEvent e)
e - the key eventpublic javafx.beans.property.BooleanProperty caeSensitiveProperty()
public boolean isCaseSensitive()
public void setCaseSensitive(boolean caseSensitive)
caseSensitive - the flag if searching is case sensitivepublic javafx.beans.property.ObjectProperty<javafx.util.Duration> searchingDelayProperty()
getSearchingDelay(),
setSearchingDelay(Duration)public javafx.util.Duration getSearchingDelay()
public void setSearchingDelay(javafx.util.Duration searchingDelay)
searchingDelay - the delay before searching start.public javafx.beans.property.BooleanProperty repeatsProperty()
isRepeats(),
setRepeats(boolean)public boolean isRepeats()
public void setRepeats(boolean repeats)
repeats - the repeat flagpublic javafx.beans.property.BooleanProperty wildcardEnabledProperty()
isWildcardEnabled(),
setWildcardEnabled(Boolean)public boolean isWildcardEnabled()
public void setWildcardEnabled(java.lang.Boolean wildcardEnabled)
wildcardEnabled - the flag if wildcard is enabledisWildcardEnabled()public WildcardSupport getWildcardSupport()
WildcardSupport will be used.public void setWildcardSupport(WildcardSupport wildcardSupport)
wildcardSupport - the new WildCardSupport.public javafx.beans.property.StringProperty searchingLabelProperty()
public java.lang.String getSearchLabel()
public void setSearchLabel(java.lang.String searchLabel)
searchLabel - the search labelpublic javafx.scene.Node getNode()
public javafx.beans.property.ObjectProperty<javafx.geometry.Pos> popupPositionProperty()
getPopupPosition(),
setPopupPosition(Pos)public javafx.geometry.Pos getPopupPosition()
public void setPopupPosition(javafx.geometry.Pos popupPosition)
popupPosition - the popup location. The valid values are defined in <code>Pos</code>. We currently only support
TOP_XXX and BOTTOM_XXX total six positions.public javafx.beans.property.ObjectProperty<javafx.scene.Node> popupPositionRelativeToProperty()
public javafx.scene.Node getPopupPositionRelativeTo()
public void setPopupPositionRelativeTo(javafx.scene.Node popupPositionRelativeTo)
getPopupPosition(). If you never set, we will use the searchable node or its scroll pane (if exists) as the
popupPositionRelativeTo Node.popupPositionRelativeTo - the relative nodepublic javafx.beans.property.StringProperty searchingTextProperty()
getSearchingText(),
setSearchingText(String)public java.lang.String getSearchingText()
public void setSearchingText(java.lang.String searchingText)
public javafx.beans.property.StringProperty typedTextProperty()
public javafx.beans.property.BooleanProperty searchingProperty()
isSearching(),
setSearching(boolean)public boolean isSearching()
public void setSearching(boolean searching)
public javafx.beans.property.IntegerProperty matchingIndexProperty()
getMatchingIndex(),
setMatchingIndex(int)public int getMatchingIndex()
public void setMatchingIndex(int matchingIndex)
public javafx.beans.property.ObjectProperty<T> matchingElementProperty()
getMatchingElement(),
setMatchingElement(T)public T getMatchingElement()
public void setMatchingElement(T matchingElement)
public boolean isReverseOrder()
public void setReverseOrder(boolean reverseOrder)
reverseOrder - the flag if searching from top to bottom or from bottom to topprotected java.lang.String getResourceString(java.lang.String key)
key - the resource string keypublic boolean isPopupVisible()
public javafx.beans.property.BooleanProperty fromStartProperty()
isFromStart(),
setFromStart(boolean)public boolean isFromStart()
String.startsWith(String) to do the comparison. Otherwise, it will use String.indexOf(String) to do the
comparison.public void setFromStart(boolean fromStart)
fromStart - true if the comparison matches from the start of the text only. Otherwise false. The difference
is if true, it will use String's startWith method to match. If false, it will use
contains method.public static Searchable getSearchable(javafx.scene.Node node)
node - the nodepublic javafx.util.Duration getHidePopupDelay()
setHidePopupDelay(Duration)public void setHidePopupDelay(javafx.util.Duration hidePopupDelay)
By default, the delay value is Duration.INDEFINITE, which means the hide popup will not be hidden unless users press ESCAPE key. You could set it to a positive value to automatically hide the search popup after an idle time.
hidePopupDelay - the delay in Durationpublic java.util.List<java.lang.Integer> findAll(java.lang.String s)
findAll uses the Searchable to find all the element indices that match the searching string.s - the searching string.public java.lang.String getElementAtAsString(int index)
convertElementToString(Object) method.index - the index.