public final class SearchField
extends javax.swing.JPanel
It is intended to be used in places where "search as you type" is supported, i.e. the search is performed immediately as the user types the query and they do not have to click a secondary button or press enter to initiate the search.
To receive notification when a search should be performed, you should
attach a SearchListener
using the addSearchListener( SearchListener )
method. Events are not fired on each keystroke. Each keystroke resets a
countdown timer; only when this timer reaches zero is an event fired. The
timer delay can be configured using the setTimerDelay(TimeUnit,long)
method.
Modifier and Type | Class and Description |
---|---|
static class |
SearchField.Style
The style of search supported by an instance of
SearchField . |
static class |
SearchField.TypingDelay
When the
style of a
SearchField is SearchField.Style.FILTER , searching is triggered
on a delay after the user stops typing. |
javax.swing.JPanel.AccessibleJPanel
javax.swing.JComponent.AccessibleJComponent
listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Constructor and Description |
---|
SearchField() |
SearchField(PromptedTextField textField) |
SearchField(PromptedTextField textField,
SearchField.Style style) |
SearchField(SearchField.Style style) |
Modifier and Type | Method and Description |
---|---|
void |
addCategory(SearchCategory category)
Adds a category to the search field.
|
void |
addCategoryMenuItem(javax.swing.JMenuItem item)
Adds a custom menu item to the categories drop down list.
|
protected void |
addImpl(java.awt.Component comp,
java.lang.Object constraints,
int index) |
void |
addSearchListener(SearchListener sl)
Registers a
SearchListener with this SearchField. |
void |
clear()
Clears the current search text.
|
void |
clearCategories()
Removes all categories from the search field.
|
void |
clearCategoryMenuItems()
Removes all custom menu items added to the categories drop down list
using
addCategoryMenuItem( JMenuItem ) . |
void |
doSearch(SearchCategory category,
java.lang.String searchText,
SearchEvent.Direction direction)
Programmatically initiate a search.
|
void |
doSearch(SearchCategory category,
java.lang.String searchText,
SearchEvent.Direction direction,
boolean force)
Programmatically initiate a search.
|
protected void |
fireSearchCategoryChanged()
Fires the
searchCategoryChanged
event to all registered listeners. |
protected void |
fireSearchCleared(java.lang.String textBeforeClear)
Fires the
searchPeformed
event to all registered listeners notifying them that the search text
was cleared. |
protected void |
fireSearchPerformed(SearchEvent.Direction direction,
boolean keypress)
Fires the
searchPerformed
event to all registered listeners. |
javax.swing.JPopupMenu |
getCategoriesPopup() |
java.lang.String |
getInfoText() |
java.awt.Component |
getKeyEventTargetComponent()
Gets the component that is being sent all unprocessed key events from
this component.
|
javax.swing.JButton |
getNextButton() |
javax.swing.Action |
getPopDownAction()
Returns the action of the search category button that will be shown on the
left side of the search field.
|
javax.swing.JButton |
getPreviousButton() |
SearchCategory |
getSelectedCategory()
Returns the currently selected category.
|
SearchField.Style |
getStyle()
Returns the current style of search.
|
java.lang.String |
getText()
Returns the current text in the search field.
|
PromptedTextField |
getTextField()
Returns the wrapped prompted text field.
|
SearchField.TypingDelay |
getTypingDelay()
Returns the typing delay of this field when the
style is SearchField.Style.FILTER or
SearchField.Style.FIND with autoFind . |
void |
installFindNextKeyStroke(javax.swing.KeyStroke keyStroke)
Installs a keystroke to use to find next.
|
void |
installFindPreviousKeyStroke(javax.swing.KeyStroke keyStroke)
Installs a keystroke to use to find previous.
|
boolean |
isAllowEmptySearch()
Returns true, this field will enable the search
action even if there is not text on it when the style is set to
SearchField.Style.SEARCH . |
boolean |
isAutoFind()
Returns true if this field will automatically trigger find next
on keyboard presses when the style is
SearchField.Style.FIND . |
boolean |
isHideCancel() |
protected boolean |
processKeyBinding(javax.swing.KeyStroke ks,
java.awt.event.KeyEvent e,
int condition,
boolean pressed) |
void |
removeCategory(SearchCategory category)
Removes a category from the search field.
|
void |
removeCategoryMenuItem(javax.swing.JMenuItem item)
Removes a menu item previously added to the categories drop down list
using
addCategoryMenuItem( JMenuItem ) . |
void |
removeSearchListener(SearchListener sl)
Deregisters a
SearchListener from this SearchField. |
void |
requestFocus() |
void |
setAllowEmptySearch(boolean allowEmptySearch)
Sets whether this field will keep the search action enabled (and thus
the search button) when the style is
SearchField.Style.SEARCH and there is
no text to use as search query. |
void |
setAutoFind(boolean autoFind)
Sets whether this field will automatically trigger find next on keyboard
presses when the style is
SearchField.Style.FIND . |
void |
setCategoriesPopup(javax.swing.JPopupMenu menu)
Sets the popupmenu to be shown for the categories option.
|
void |
setEnabled(boolean enabled) |
void |
setForeground(java.awt.Color color) |
void |
setHideCancel(boolean hideCancel)
The cancel button may be hidden (if the style of search supports cancel) by calling this
method with true
|
void |
setInfoText(java.lang.String text)
The search field can contain an extra info label that appears between the buttons and the search text.
|
void |
setKeyEventTargetComponent(java.awt.Component c)
Sets a component that will be sent all unprocessed key events from this
component.
|
void |
setNotifyOnEmptySearch(boolean notifyOnEmptySearch) |
void |
setPopDownAction(javax.swing.Action action)
Customize the button to be shown on the left of the search field.
The drop-down overlay will appear when action.isEnabled() is true. |
void |
setPrompt(java.lang.String prompt)
Sets the prompt to display in the SearchField.
|
void |
setSelectedCategory(SearchCategory selectedCategory)
Sets the currently selected category.
|
void |
setStyle(SearchField.Style style)
Sets the style of search.
|
void |
setText(java.lang.String text)
Sets the current search text.
|
void |
setText(java.lang.String newText,
boolean isAdjusting)
Set the text in the search field.
|
void |
setTypingDelay(SearchField.TypingDelay delay)
Sets the typing delay to use when the
style is
SearchField.Style.FILTER or SearchField.Style.FIND with autoFind . |
void |
showSearchFailed() |
void |
showSearchWrapped() |
void |
updateUI() |
getAccessibleContext, getUI, getUIClassID, paramString, setUI
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, hide, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingOrigin, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setFocusTraversalKeys, setFont, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusDownCycle, validate, validateTree
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle
public SearchField()
public SearchField(SearchField.Style style)
public SearchField(PromptedTextField textField)
public SearchField(PromptedTextField textField, SearchField.Style style)
public void updateUI()
updateUI
in class javax.swing.JPanel
public void setNotifyOnEmptySearch(boolean notifyOnEmptySearch)
notifyOnEmptySearch
- public void setKeyEventTargetComponent(java.awt.Component c)
c
- a component to send unprocessed key events to. May be null.public java.awt.Component getKeyEventTargetComponent()
public void setForeground(java.awt.Color color)
setForeground
in class javax.swing.JComponent
public void installFindNextKeyStroke(javax.swing.KeyStroke keyStroke)
keyStroke
- a keystroke to use.public void installFindPreviousKeyStroke(javax.swing.KeyStroke keyStroke)
keyStroke
- a keystroke to use.public void setEnabled(boolean enabled)
setEnabled
in class javax.swing.JComponent
public void showSearchWrapped()
public void showSearchFailed()
public javax.swing.JPopupMenu getCategoriesPopup()
public void setCategoriesPopup(javax.swing.JPopupMenu menu)
public void setAutoFind(boolean autoFind)
SearchField.Style.FIND
. The default for auto
find is false.autoFind
- if true, this field will fire
searchPerformed events on each keypress when the style is
SearchField.Style.FIND
.public void setAllowEmptySearch(boolean allowEmptySearch)
SearchField.Style.SEARCH
and there is
no text to use as search query. The default is to not allow it.allowEmptySearch
- if true, this field will enable the search
action even if there is not text on it when the style is set to SearchField.Style.SEARCH
.public boolean isAutoFind()
SearchField.Style.FIND
.public boolean isAllowEmptySearch()
SearchField.Style.SEARCH
.SearchField.Style.SEARCH
.public void clear()
public void setStyle(SearchField.Style style)
SearchField.Style
enum for details.style
- the style of search. Must not be null.public SearchField.Style getStyle()
public void setHideCancel(boolean hideCancel)
hideCancel
- public boolean isHideCancel()
public void setPopDownAction(javax.swing.Action action)
action
- Provides the behavior with actionPerformed() and
optionally an icon and a text for the tooltip.java.lang.NullPointerException
- if action is null.public final javax.swing.Action getPopDownAction()
public void addCategoryMenuItem(javax.swing.JMenuItem item)
addCategory( SearchCategory )
.item
- a menu item to add. Must not be null.public void removeCategoryMenuItem(javax.swing.JMenuItem item)
addCategoryMenuItem( JMenuItem )
.item
- a menu item to remove. Must not be null.public void clearCategoryMenuItems()
addCategoryMenuItem( JMenuItem )
.public void addCategory(SearchCategory category)
searchCategoryChanged
event.The first category to be added will immediately be set as the currently selected category and an event will be fired to any registered listeners.
category
- a category to add. Must not be null.public void removeCategory(SearchCategory category)
category
- a category to remove from the search field.public void clearCategories()
public SearchCategory getSelectedCategory()
public void setSelectedCategory(SearchCategory selectedCategory)
searchCategoryChanged
event to all registered listeners.selectedCategory
- the new selected category. May only be null if there
are no categories.java.lang.IllegalStateException
- if there are categories and a null category
is passed as the selectedCategory parameter.java.lang.IllegalArgumentException
- if the specified category has not been
added using addCategory(SearchCategory)
.protected boolean processKeyBinding(javax.swing.KeyStroke ks, java.awt.event.KeyEvent e, int condition, boolean pressed)
processKeyBinding
in class javax.swing.JComponent
protected final void fireSearchPerformed(SearchEvent.Direction direction, boolean keypress)
searchPerformed
event to all registered listeners.protected final void fireSearchCategoryChanged()
searchCategoryChanged
event to all registered listeners.protected final void fireSearchCleared(java.lang.String textBeforeClear)
searchPeformed
event to all registered listeners notifying them that the search text
was cleared.textBeforeClear
- the text of the field before it was cleared.public void addSearchListener(SearchListener sl)
SearchListener
with this SearchField. The
listener will be notified of search events.sl
- a listener to register. Must not be null.public void removeSearchListener(SearchListener sl)
SearchListener
from this SearchField.sl
- a listener to register.public void setPrompt(java.lang.String prompt)
prompt
- the prompt text to display.public void setTypingDelay(SearchField.TypingDelay delay)
style
is
SearchField.Style.FILTER
or SearchField.Style.FIND
with autoFind
.delay
- the delay after a key is pressed before search is initiated.java.lang.IllegalStateException
- if the style
is not
SearchField.Style.FILTER
.public SearchField.TypingDelay getTypingDelay()
style
is SearchField.Style.FILTER
or
SearchField.Style.FIND
with autoFind
.public java.lang.String getText()
public java.lang.String getInfoText()
public void setInfoText(java.lang.String text)
text
- additional text to display, or nullpublic PromptedTextField getTextField()
public void setText(java.lang.String text)
text
- the current search text.public void setText(java.lang.String newText, boolean isAdjusting)
newText
- isAdjusting
- - if true then this control will not fire an search event
due to the setting of this text.public void doSearch(SearchCategory category, java.lang.String searchText, SearchEvent.Direction direction)
category
- category for the searchsearchText
- text for the searchdirection
- direction of the searchpublic void doSearch(SearchCategory category, java.lang.String searchText, SearchEvent.Direction direction, boolean force)
category
- category for the searchsearchText
- text for the searchdirection
- direction of the searchforce
- trigger performing the search even if the search text hasn't changedprotected void addImpl(java.awt.Component comp, java.lang.Object constraints, int index)
addImpl
in class java.awt.Container
public void requestFocus()
requestFocus
in class javax.swing.JComponent
public javax.swing.JButton getPreviousButton()
public javax.swing.JButton getNextButton()