Skip navigation links

oracle.javatools.ui.search
Class SearchField

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
javax.swing.JPanel
oracle.javatools.ui.search.SearchField

All Implemented Interfaces:

java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, javax.accessibility.Accessible

public final class SearchField

extends javax.swing.JPanel

A custom text component that can be used as an immediate search control. This control provides support for displaying an inline prompt, next and previous search buttons and a cancel search button.

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.

Since:

11.0

See Also:

Serialized Form

Nested Class Summary

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.

Nested classes/interfaces inherited from class javax.swing.JPanel

javax.swing.JPanel.AccessibleJPanel

Nested classes/interfaces inherited from class javax.swing.JComponent

javax.swing.JComponent.AccessibleJComponent

Nested classes/interfaces inherited from class java.awt.Container

java.awt.Container.AccessibleAWTContainer

Nested classes/interfaces inherited from class java.awt.Component

java.awt.Component.AccessibleAWTComponent, java.awt.Component.BaselineResizeBehavior, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy

Field Summary

Fields inherited from class javax.swing.JComponent

accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

SearchField()

SearchField(PromptedTextField textField)

SearchField(PromptedTextField textField, SearchField.Style style)

SearchField(SearchField.Style style)

Method Summary

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.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.
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	setForeground(java.awt.Color color)
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()

Methods inherited from class javax.swing.JPanel

getAccessibleContext, getUI, getUIClassID, paramString, setUI

Methods inherited from class javax.swing.JComponent

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, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, 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, setEnabled, setFocusTraversalKeys, setFont, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update

Methods inherited from class java.awt.Container

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, transferFocusBackward, transferFocusDownCycle, validate, validateTree

Methods inherited from class java.awt.Component

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, hide, 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, transferFocusUpCycle

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SearchField

public SearchField()

SearchField

public SearchField(SearchField.Style style)

SearchField

public SearchField(PromptedTextField textField)

SearchField

public SearchField(PromptedTextField textField,
                   SearchField.Style style)

Method Detail

updateUI

public void updateUI()

Overrides:

updateUI in class javax.swing.JPanel

setNotifyOnEmptySearch

public void setNotifyOnEmptySearch(boolean notifyOnEmptySearch)

Parameters:

notifyOnEmptySearch -

setKeyEventTargetComponent

public void setKeyEventTargetComponent(java.awt.Component c)

Sets a component that will be sent all unprocessed key events from this component.

Parameters:

c - a component to send unprocessed key events to. May be null.

getKeyEventTargetComponent

public java.awt.Component getKeyEventTargetComponent()

Gets the component that is being sent all unprocessed key events from this component.

Returns:

a target component for key events.

setForeground

public void setForeground(java.awt.Color color)

Overrides:

setForeground in class javax.swing.JComponent

installFindNextKeyStroke

public void installFindNextKeyStroke(javax.swing.KeyStroke keyStroke)

Installs a keystroke to use to find next.

Parameters:

keyStroke - a keystroke to use.

installFindPreviousKeyStroke

public void installFindPreviousKeyStroke(javax.swing.KeyStroke keyStroke)

Installs a keystroke to use to find previous.

Parameters:

keyStroke - a keystroke to use.

showSearchWrapped

public void showSearchWrapped()

showSearchFailed

public void showSearchFailed()

getCategoriesPopup

public javax.swing.JPopupMenu getCategoriesPopup()

Returns:

the popup menu used for the category drop down

setCategoriesPopup

public void setCategoriesPopup(javax.swing.JPopupMenu menu)

Sets the popupmenu to be shown for the categories option.

setAutoFind

public void setAutoFind(boolean autoFind)

Sets whether this field will automatically trigger find next on keyboard presses when the style is SearchField.Style.FIND. The default for auto find is false.

Parameters:

autoFind - if true, this field will fire searchPerformed events on each keypress when the style is SearchField.Style.FIND.

setAllowEmptySearch

public 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. The default is to not allow it.

Parameters:

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.

isAutoFind

public boolean isAutoFind()

Returns true if this field will automatically trigger find next on keyboard presses when the style is SearchField.Style.FIND.

Returns:

true if the field fires find events on keypresses.

isAllowEmptySearch

public 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.

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.

clear

public void clear()

Clears the current search text.

setStyle

public void setStyle(SearchField.Style style)

Sets the style of search. See the SearchField.Style enum for details.

Parameters:

style - the style of search. Must not be null.

getStyle

public SearchField.Style getStyle()

Returns the current style of search.

Returns:

the current style of search

setPopDownAction

public 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.

Parameters:

action - Provides the behavior with actionPerformed() and optionally an icon and a text for the tooltip.

Throws:

java.lang.NullPointerException - if action is null.

getPopDownAction

public final javax.swing.Action getPopDownAction()

Returns the action of the search category button that will be shown on the left side of the search field.

addCategoryMenuItem

public void addCategoryMenuItem(javax.swing.JMenuItem item)

Adds a custom menu item to the categories drop down list. The specified menu item will be added after the items for any categories added using addCategory( SearchCategory ).

Parameters:

item - a menu item to add. Must not be null.

removeCategoryMenuItem

public void removeCategoryMenuItem(javax.swing.JMenuItem item)

Removes a menu item previously added to the categories drop down list using addCategoryMenuItem( JMenuItem ).

Parameters:

item - a menu item to remove. Must not be null.

clearCategoryMenuItems

public void clearCategoryMenuItems()

Removes all custom menu items added to the categories drop down list using addCategoryMenuItem( JMenuItem ).

addCategory

public void addCategory(SearchCategory category)

Adds a category to the search field. The category will be available in a drop down list on the search button. Listeners receive notification when the search category changes via the 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.

Parameters:

category - a category to add. Must not be null.

removeCategory

public void removeCategory(SearchCategory category)

Removes a category from the search field. If the removed category is the currently selected category, then the first category will be selected. If no more categories are available, then the category will be reset to null.

Parameters:

category - a category to remove from the search field.

clearCategories

public void clearCategories()

Removes all categories from the search field. The category will be reset to null.

getSelectedCategory

public SearchCategory getSelectedCategory()

Returns the currently selected category.

Returns:

the currently selected category.

setSelectedCategory

public void setSelectedCategory(SearchCategory selectedCategory)

Sets the currently selected category. This will fire a searchCategoryChanged event to all registered listeners.

Parameters:

selectedCategory - the new selected category. May only be null if there are no categories.

Throws:

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).

processKeyBinding

protected boolean processKeyBinding(javax.swing.KeyStroke ks,
                                    java.awt.event.KeyEvent e,
                                    int condition,
                                    boolean pressed)

Overrides:

processKeyBinding in class javax.swing.JComponent

fireSearchPerformed

protected final void fireSearchPerformed(SearchEvent.Direction direction,
                                         boolean keypress)

Fires the searchPerformed event to all registered listeners.

fireSearchCategoryChanged

protected final void fireSearchCategoryChanged()

Fires the searchCategoryChanged event to all registered listeners.

fireSearchCleared

protected final void fireSearchCleared(java.lang.String textBeforeClear)

Fires the searchPeformed event to all registered listeners notifying them that the search text was cleared.

Parameters:

textBeforeClear - the text of the field before it was cleared.

addSearchListener

public void addSearchListener(SearchListener sl)

Registers a SearchListener with this SearchField. The listener will be notified of search events.

Parameters:

sl - a listener to register. Must not be null.

removeSearchListener

public void removeSearchListener(SearchListener sl)

Deregisters a SearchListener from this SearchField.

Parameters:

sl - a listener to register.

setPrompt

public void setPrompt(java.lang.String prompt)

Sets the prompt to display in the SearchField. The prompt will be displayed inside the text field itself.

Parameters:

prompt - the prompt text to display.

setTypingDelay

public void setTypingDelay(SearchField.TypingDelay delay)

Sets the typing delay to use when the style is SearchField.Style.FILTER or SearchField.Style.FIND with autoFind.

Parameters:

delay - the delay after a key is pressed before search is initiated.

Throws:

java.lang.IllegalStateException - if the style is not SearchField.Style.FILTER.

getTypingDelay

public SearchField.TypingDelay getTypingDelay()

Returns the typing delay of this field when the style is SearchField.Style.FILTER or SearchField.Style.FIND with autoFind.

Returns:

the typing delay.

getText

public java.lang.String getText()

Returns the current text in the search field.

Returns:

the text in the search field.

getTextField

public PromptedTextField getTextField()

Returns the wrapped prompted text field.

Returns:

setText

public void setText(java.lang.String text)

Sets the current search text.

Parameters:

text - the current search text.

setText

public void setText(java.lang.String newText,
                    boolean isAdjusting)

Set the text in the search field.

Parameters:

newText -

isAdjusting - - if true then this control will not fire an search event due to the setting of this text.

doSearch

public void doSearch(SearchCategory category,
                     java.lang.String searchText,
                     SearchEvent.Direction direction)

Programmatically initiate a search.

Parameters:

category - category for the search

searchText - text for the search

direction - direction of the search

doSearch

public void doSearch(SearchCategory category,
                     java.lang.String searchText,
                     SearchEvent.Direction direction,
                     boolean force)

Programmatically initiate a search.

Parameters:

category - category for the search

searchText - text for the search

direction - direction of the search

force - trigger performing the search even if the search text hasn't changed

addImpl

protected void addImpl(java.awt.Component comp,
                       java.lang.Object constraints,
                       int index)

Overrides:

addImpl in class java.awt.Container

requestFocus

public void requestFocus()

Overrides:

requestFocus in class javax.swing.JComponent

getPreviousButton

public javax.swing.JButton getPreviousButton()

getNextButton

public javax.swing.JButton getNextButton()

Skip navigation links