Package 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:

  • Field Details

  • Constructor Details

    • 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 Details

    • 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:

    • 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

    • 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

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