JIDE Common Layer 2.7.6

com.jidesoft.swing
Class SearchableBar

java.lang.Object
  extended by java.awt.Component
      extended by java.awt.Container
          extended by javax.swing.JComponent
              extended by javax.swing.JToolBar
                  extended by com.jidesoft.swing.SearchableBar
All Implemented Interfaces:
SearchableProvider, java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, javax.accessibility.Accessible, javax.swing.SwingConstants

public class SearchableBar
extends javax.swing.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
javax.swing.JToolBar.AccessibleJToolBar, javax.swing.JToolBar.Separator
 
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
protected  javax.swing.AbstractButton _closeButton
           
protected  javax.swing.AbstractButton _findNextButton
           
protected  javax.swing.AbstractButton _findPrevButton
           
protected  javax.swing.AbstractButton _highlightsButton
           
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
           
 
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, java.lang.String initialText, boolean compact)
          Creates a searchable bar with initial searching text and in compact mode or full mode.
 
Method Summary
protected  javax.swing.AbstractButton createCloseButton(javax.swing.AbstractAction closeAction)
          Creates the close button.
protected  javax.swing.AbstractButton createFindNextButton(javax.swing.AbstractAction findNextAction)
          Creates the find next button.
protected  javax.swing.AbstractButton createFindPrevButton(javax.swing.AbstractAction findPrevAction)
          Creates the find prev button.
protected  javax.swing.AbstractButton createHighlightButton()
          Creates the highlight button.
protected  javax.swing.AbstractButton createMatchCaseButton()
          Creates the match case button.
protected  javax.swing.AbstractButton createRepeatsButton()
          Creates the repeat button.
protected  javax.swing.JTextField createTextField()
          Creates the text field where user types the text to be searched.
 void focusSearchField()
          Makes the search field having focus.
protected  javax.swing.ImageIcon getImageIcon(java.lang.String name)
          Gets the icons from SearchableBarIconsFactory.
 SearchableBar.Installer getInstaller()
           
 java.awt.Color getMismatchBackground()
          Gets the background color when the searching text doesn't match with any of the elements in the component.
protected  java.lang.String getResourceString(java.lang.String key)
          Gets the localized string from resource bundle.
 Searchable getSearchable()
          Gets the underlying Searchable object.
 java.lang.String getSearchingText()
          Gets the searching text.
 int getVisibleButtons()
           
static SearchableBar install(Searchable searchable, javax.swing.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 isPassive()
          Returns false.
 void processKeyEvent(java.awt.event.KeyEvent e)
           
protected  void select(int index, java.lang.String searchingText, boolean incremental)
           
 void setCompact(boolean compact)
          Sets the SearchableBar to compact or full mode.
 void setInstaller(SearchableBar.Installer installer)
          Sets the installer.
 void setMismatchForeground(java.awt.Color mismatchBackground)
          Sets the background for mismatch.
 void setSearchingText(java.lang.String searchingText)
          Sets the searching text.
 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, 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, transferFocusBackward, transferFocusUpCycle
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

_closeButton

protected javax.swing.AbstractButton _closeButton

_findPrevButton

protected javax.swing.AbstractButton _findPrevButton

_findNextButton

protected javax.swing.AbstractButton _findNextButton

_highlightsButton

protected javax.swing.AbstractButton _highlightsButton

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_ALL

public static final int SHOW_ALL
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,
                     java.lang.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 javax.swing.JTextField createTextField()
Creates the text field where user types the text to be searched.

Returns:
a text field.

getSearchable

public Searchable getSearchable()
Gets the underlying Searchable object.

Returns:
the Searchable object.

createCloseButton

protected javax.swing.AbstractButton createCloseButton(javax.swing.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 javax.swing.AbstractButton createFindNextButton(javax.swing.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 javax.swing.AbstractButton createFindPrevButton(javax.swing.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 javax.swing.AbstractButton createHighlightButton()
Creates the highlight button.

Returns:
the highlight button.

createRepeatsButton

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

installComponents

protected void installComponents()
Adds the buttons to the SearchableBar. Subclass can override this method to rearrange the layout of those buttons.


focusSearchField

public void focusSearchField()
Makes the search field having focus.


select

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

getSearchingText

public java.lang.String getSearchingText()
Gets the searching text.

Specified by:
getSearchingText in interface SearchableProvider
Returns:
the searching text.

setSearchingText

public void setSearchingText(java.lang.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(java.awt.Color mismatchBackground)
Sets the background for mismatch.

Parameters:
mismatchBackground - the mismatch background

getMismatchBackground

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

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,
                                    javax.swing.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(java.awt.event.KeyEvent e)
Specified by:
processKeyEvent in interface SearchableProvider
Overrides:
processKeyEvent in class javax.swing.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 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 javax.swing.ImageIcon getImageIcon(java.lang.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 java.lang.String getResourceString(java.lang.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.

JIDE Common Layer 2.7.6