com.jidesoft.swing
Class SearchableBar

java.lang.Object
  java.awt.Component
      java.awt.Container
          javax.swing.JComponent
              javax.swing.JToolBar
                  com.jidesoft.swing.SearchableBar

All Implemented Interfaces:

SearchableProvider, ImageObserver, MenuContainer, Serializable, Accessible, SwingConstants

public class SearchableBar
extends JToolBar
implements SearchableProvider

SearchableBar is a convenient component to enable searching feature for components. As long as the component support Searchable feature, it can work with SearchableBar.

Different from Searchable feature which uses a small popup window to allow user typing in the searching text, SearchableBar provides a full-size panel. Although they both pretty provide the same set of features, they should be used in different cases to achieve the most desirable result.

First of all, SearchableBar is a lot bigger than Searchable's popup and need more space on the screen. The component that installs SearchableBar should be large enough. In comparison, Searchable can be installed on components of any size as it's a floating popup.

Secondly, SearchableBar can be set visible all the time or can be set visible by a keystroke and stay visible unless user explicitly hides it. If your user is not computer savvy, SearchableBar is more appropriate because user can see searching feature very easily. SearchableBar can also be a better replacement the traditional "Find" or "Search" dialog because SearchableBar doesn't block user input like modal dialog. In comparison, Searchable's popup is very transient. Mouse clicks outside the popup will hide the popup. For computer savvy it is very helpful but it could be hard for non-computer savvy to "understand" it. A good example is IntelliJ IDEA heavily uses Searchable popup because the users are all Java developers. Firefox, on the other hand, uses SearchableBar because the users are just regular computer users.

Although appearance wise, these two are very different, they both based on Searchable interface. So as developer, both are almost the same. SearchableBar based on Searchable. So if you have an interface of Searchable, all you need is to call

 SearchableBar.install(searchable, KeyStroke.getKeyStroke(KeyEvent.VK_F,
 KeyEvent.CTRL_DOWN_MASK),
 new SearchableBar.Installer() {
     public void openSearchBar(SearchableBar searchableBar) {
        // add code to show search bar
     }
 

     public void closeSearchBar(SearchableBar searchableBar) {
        // add code to close search bar
 }
 });
 

Or if you want fully control the SearchableBar, you can create one using one of its constructors and add to wherever you want.

There are a few options you can set on SearchableBar. You can set compact or full mode. Compact mode will only use icon for buttons v.s. full mode will use both icon and text for buttons. All buttons on the SearchableBar can be shown/hidden by using setVisibleButtons(int) method. You can also set the text field background for mismatch by using setMismatchForeground(java.awt.Color).

See Also:

Serialized Form

Nested Class Summary

static interface

SearchableBar.Installer The installer for SearchableBar.

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

JToolBar.AccessibleJToolBar, JToolBar.Separator

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

JComponent.AccessibleJComponent

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

Container.AccessibleAWTContainer

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

Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy

Field Summary

protected AbstractButton	_closeButton
protected JComboBox	_comboBox
protected AbstractButton	_findNextButton
protected AbstractButton	_findPrevButton
protected AbstractButton	_highlightsButton
protected JLabel	_leadingLabel
protected AbstractButton	_matchCaseCheckBox
protected AbstractButton	_repeatCheckBox
protected JLabel	_statusLabel
protected JTextField	_textField
protected AbstractButton	_wholeWordsCheckBox
static String	PROPERTY_MAX_HISTORY_LENGTH
static int	SHOW_ALL
static int	SHOW_CLOSE
static int	SHOW_HIGHLIGHTS
static int	SHOW_MATCHCASE
static int	SHOW_NAVIGATION
static int	SHOW_REPEATS
static int	SHOW_STATUS
static int	SHOW_WHOLE_WORDS

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 javax.swing.SwingConstants

BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST

Fields inherited from interface java.awt.image.ImageObserver

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

Constructor Summary

SearchableBar(Searchable searchable)
Creates a searchable bar.

SearchableBar(Searchable searchable, boolean compact)
Creates a searchable bar in compact mode or full mode.

SearchableBar(Searchable searchable, String initialText, boolean compact)
Creates a searchable bar with initial searching text and in compact mode or full mode.

Method Summary

protected AbstractButton	createCloseButton(AbstractAction closeAction) Creates the close button.
protected JComboBox	createComboBox() Creates the combo box where user types the text to be searched.
protected AbstractButton	createFindNextButton(AbstractAction findNextAction) Creates the find next button.
protected AbstractButton	createFindPrevButton(AbstractAction findPrevAction) Creates the find prev button.
protected AbstractButton	createHighlightButton() Creates the highlight button.
protected AbstractButton	createMatchCaseButton() Creates the match case button.
protected AbstractButton	createRepeatsButton() Creates the repeat button.
protected JTextField	createTextField() Creates the text field where user types the text to be searched.
protected AbstractButton	createWholeWordsButton() Creates the whole words button.
void	focusSearchField() Makes the search field having focus.
protected ImageIcon	getImageIcon(String name) Gets the icons from SearchableBarIconsFactory.
SearchableBar.Installer	getInstaller()
int	getMaxHistoryLength() Gets the maximum search history length.
Color	getMismatchBackground() Gets the background color when the searching text doesn't match with any of the elements in the component.
protected String	getResourceString(String key) Gets the localized string from resource bundle.
Searchable	getSearchable() Gets the underlying Searchable object.
String[]	getSearchHistory() Gets the search history.
String	getSearchingText() Gets the searching text.
int	getVisibleButtons()
static SearchableBar	install(Searchable searchable, KeyStroke keyStroke, SearchableBar.Installer installer) Installs a SearchableBar on a component.
protected void	installComponents() Adds the buttons to the SearchableBar.
boolean	isCompact() Checks if SearchableBar is in compact mode.
boolean	isHighlightAll() Get if the SearchableBar is highlighting all matches.
boolean	isPassive() Returns false.
boolean	isShowMatchCount() Gets the flag indicating if the match count should be displayed in the status label.
void	processKeyEvent(KeyEvent e)
protected void	select(int index, String searchingText, boolean incremental)
void	setCompact(boolean compact) Sets the SearchableBar to compact or full mode.
void	setHighlightAll(boolean highlightAll) Set if the SearchableBar will highlight all matches.
void	setInstaller(SearchableBar.Installer installer) Sets the installer.
void	setMaxHistoryLength(int maxHistoryLength) Sets the maximum search history length.
void	setMismatchForeground(Color mismatchBackground) Sets the background for mismatch.
void	setSearchHistory(String[] searchHistory) Sets the search history.
void	setSearchingText(String searchingText) Sets the searching text.
void	setShowMatchCount(boolean showMatchCount) Sets the flag indicating if the match count should be displayed in the status label.
void	setVisibleButtons(int visibleButtons) Sets visible buttons on SearchableBar.

Methods inherited from class javax.swing.JToolBar

add, addImpl, addSeparator, addSeparator, createActionChangeListener, createActionComponent, getAccessibleContext, getComponentAtIndex, getComponentIndex, getMargin, getOrientation, getUI, getUIClassID, isBorderPainted, isFloatable, isRollover, paintBorder, paramString, setBorderPainted, setFloatable, setLayout, setMargin, setOrientation, setRollover, setUI, updateUI

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, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, 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, 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

Field Detail

_statusLabel

protected JLabel _statusLabel

_leadingLabel

protected JLabel _leadingLabel

_textField

protected JTextField _textField

_comboBox

protected JComboBox _comboBox

_closeButton

protected AbstractButton _closeButton

_findPrevButton

protected AbstractButton _findPrevButton

_findNextButton

protected AbstractButton _findNextButton

_highlightsButton

protected AbstractButton _highlightsButton

_matchCaseCheckBox

protected AbstractButton _matchCaseCheckBox

_wholeWordsCheckBox

protected AbstractButton _wholeWordsCheckBox

_repeatCheckBox

protected AbstractButton _repeatCheckBox

SHOW_CLOSE

public static final int SHOW_CLOSE

See Also:

Constant Field Values

SHOW_NAVIGATION

public static final int SHOW_NAVIGATION

See Also:

Constant Field Values

SHOW_HIGHLIGHTS

public static final int SHOW_HIGHLIGHTS

See Also:

Constant Field Values

SHOW_MATCHCASE

public static final int SHOW_MATCHCASE

See Also:

Constant Field Values

SHOW_REPEATS

public static final int SHOW_REPEATS

See Also:

Constant Field Values

SHOW_STATUS

public static final int SHOW_STATUS

See Also:

Constant Field Values

SHOW_WHOLE_WORDS

public static final int SHOW_WHOLE_WORDS

See Also:

Constant Field Values

SHOW_ALL

public static final int SHOW_ALL

See Also:

Constant Field Values

PROPERTY_MAX_HISTORY_LENGTH

public static final String PROPERTY_MAX_HISTORY_LENGTH

See Also:

Constant Field Values

Constructor Detail

SearchableBar

public SearchableBar(Searchable searchable)

Creates a searchable bar.

Parameters:

searchable - the searchable

SearchableBar

public SearchableBar(Searchable searchable,
                     boolean compact)

Creates a searchable bar in compact mode or full mode.

Parameters:

searchable - the searchable

compact - the flag indicating compact mode or full mode

SearchableBar

public SearchableBar(Searchable searchable,
                     String initialText,
                     boolean compact)

Creates a searchable bar with initial searching text and in compact mode or full mode.

Parameters:

searchable - the searchable

initialText - the initial text

compact - the flag indicating compact mode or full mode

Method Detail

createTextField

protected JTextField createTextField()

Creates the text field where user types the text to be searched.

Returns:

a text field.

createComboBox

protected JComboBox createComboBox()

Creates the combo box where user types the text to be searched.

Returns:

a combo box.

Since:

3.4.1

getSearchable

public Searchable getSearchable()

Gets the underlying Searchable object.

Returns:

the Searchable object.

createCloseButton

protected AbstractButton createCloseButton(AbstractAction closeAction)

Creates the close button. Subclass can override it to create your own close button.

Parameters:

closeAction - the close action

Returns:

the close button.

createFindNextButton

protected AbstractButton createFindNextButton(AbstractAction findNextAction)

Creates the find next button. Subclass can override it to create your own find next button.

Parameters:

findNextAction - the find next action

Returns:

the find next button.

createFindPrevButton

protected AbstractButton createFindPrevButton(AbstractAction findPrevAction)

Creates the find prev button. Subclass can override it to create your own find prev button.

Parameters:

findPrevAction - the find previous action

Returns:

the find prev button.

createHighlightButton

protected AbstractButton createHighlightButton()

Creates the highlight button.

Returns:

the highlight button.

createRepeatsButton

protected AbstractButton createRepeatsButton()

Creates the repeat button. By default it will return a JCheckBox. Subclass class can override it to return your own button or customize the button created by default as long as it can set underlying Searchable's repeats property.

Returns:

the repeat button.

createMatchCaseButton

protected AbstractButton createMatchCaseButton()

Creates the match case button. By default it will return a JCheckBox. Subclass class can override it to return your own button or customize the button created by default as long as it can set underlying Searchable's caseSensitive property.

Returns:

the match case button.

createWholeWordsButton

protected AbstractButton createWholeWordsButton()

Creates the whole words button. By default it will return a JCheckBox. Subclass class can override it to return your own button or customize the button created by default as long as it can set underlying Searchable's toEnd property.

Returns:

the whole words button.

Since:

3.5.2

installComponents

protected void installComponents()

Adds the buttons to the SearchableBar. Subclass can override this method to rearrange the layout of those buttons.

isHighlightAll

public boolean isHighlightAll()

Get if the SearchableBar is highlighting all matches.

Even you set it to true, after the customer press previous or next button, this flag will be cleared.

Returns:

true if all matches are highlighted. Otherwise false.

setHighlightAll

public void setHighlightAll(boolean highlightAll)

Set if the SearchableBar will highlight all matches.

Parameters:

highlightAll - the flag

See Also:

isHighlightAll()

focusSearchField

public void focusSearchField()

Makes the search field having focus.

select

protected void select(int index,
                      String searchingText,
                      boolean incremental)

getSearchingText

public String getSearchingText()

Gets the searching text.

Specified by:

getSearchingText in interface SearchableProvider

Returns:

the searching text.

setSearchingText

public void setSearchingText(String searchingText)

Sets the searching text.

Parameters:

searchingText - the new searching text.

isPassive

public boolean isPassive()

Returns false.

Specified by:

isPassive in interface SearchableProvider

Returns:

false.

setMismatchForeground

public void setMismatchForeground(Color mismatchBackground)

Sets the background for mismatch.

Parameters:

mismatchBackground - the mismatch background

getMismatchBackground

public Color getMismatchBackground()

Gets the background color when the searching text doesn't match with any of the elements in the component.

Returns:

the foreground color for mismatch. If you never call setMismatchForeground(java.awt.Color). red color will be used.

getSearchHistory

public String[] getSearchHistory()

Gets the search history.

Returns:

the search history.

Since:

3.4.1

setSearchHistory

public void setSearchHistory(String[] searchHistory)

Sets the search history.

Parameters:

searchHistory - the search history

Since:

3.4.1

getMaxHistoryLength

public int getMaxHistoryLength()

Gets the maximum search history length.

Returns:

the maximum search history length.

Since:

3.4.1

See Also:

#setMaxHistoryLength(int)}

setMaxHistoryLength

public void setMaxHistoryLength(int maxHistoryLength)

Sets the maximum search history length.

By default, it's 0, which means there is no history to shown to keep the behavior backward compatibility. To show history with a JComboBox, please use this method to set a positive or negative value. Any negative value means that the history size is unlimited.

Parameters:

maxHistoryLength - the maximum history length

Since:

3.4.1

isShowMatchCount

public boolean isShowMatchCount()

Gets the flag indicating if the match count should be displayed in the status label.

Returns:

true if the match count should be displayed. Otherwise false.

Since:

3.5.2

See Also:

setShowMatchCount(boolean)

setShowMatchCount

public void setShowMatchCount(boolean showMatchCount)

Sets the flag indicating if the match count should be displayed in the status label.

By default, the flag is set to false to keep the original behavior.

Parameters:

showMatchCount -

Since:

3.5.2

getInstaller

public SearchableBar.Installer getInstaller()

setInstaller

public void setInstaller(SearchableBar.Installer installer)

Sets the installer. Installer is responsible for the installation and uninstallation of SearchableBar.

Parameters:

installer - the installer

install

public static SearchableBar install(Searchable searchable,
                                    KeyStroke keyStroke,
                                    SearchableBar.Installer installer)

Installs a SearchableBar on a component. This is just a convenient method for you, you can install it in your own code. See below for the actual code we used in this method.

 final SearchableBar searchableBar = new SearchableBar(searchable);
 searchableBar.setInstaller(installer);
 ((JComponent) searchable.getComponent()).registerKeyboardAction(new AbstractAction() {
     public void actionPerformed(ActionEvent e) {
         searchableBar.getInstaller().openSearchBar(searchableBar);
         searchableBar.focusSearchField();
     }
 }, keyStroke, JComponent.WHEN_FOCUSED);
 return searchableBar;
 

Parameters:

searchable - the searchable

keyStroke - the key stroke

installer - the installer

Returns:

the SearchableBar that is created.

processKeyEvent

public void processKeyEvent(KeyEvent e)

Specified by:

processKeyEvent in interface SearchableProvider

Overrides:

processKeyEvent in class JComponent

getVisibleButtons

public int getVisibleButtons()

setVisibleButtons

public void setVisibleButtons(int visibleButtons)

Sets visible buttons on SearchableBar.

Parameters:

visibleButtons - bit-wise all of several constants. Valid constants are

• SHOW_CLOSE - the close button
• SHOW_NAVIGATION - the find next and find previous buttons
• SHOW_HIGHLIGHTS - highlights all button
• SHOW_MATCHCASE - match case button
• SHOW_WHOLE_WORDS - word only button
• SHOW_REPEATS - repeats button
• SHOW_STATUS - status area
• SHOW_ALL - all buttons

For example, if you want to show only close and highlights all button, call setVisibleButtons(SearchableBar.SHOW_CLOSE | SearchableBar.SHOW_HIGHLIGHTS).

isCompact

public boolean isCompact()

Checks if SearchableBar is in compact mode.

Returns:

true if in compact. Otherwise, false.

setCompact

public void setCompact(boolean compact)

Sets the SearchableBar to compact or full mode. In compact mode will only use icon for buttons v.s. full mode will use both icon and text for buttons.

Parameters:

compact - the flag

getImageIcon

protected ImageIcon getImageIcon(String name)

Gets the icons from SearchableBarIconsFactory. Subclass can override this method if they want to provide their own icon.

Parameters:

name - the icon name

Returns:

the icon of the specified name.

getResourceString

protected String getResourceString(String key)

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 "SearchableBar.".

Parameters:

key - the resource key

Returns:

the localized string.