Package org.jdesktop.swingx

Class JXSearchField

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
javax.swing.text.JTextComponent
javax.swing.JTextField
org.jdesktop.swingx.JXTextField
org.jdesktop.swingx.JXSearchField
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, Scrollable, SwingConstants
@JavaBean public class JXSearchField extends JXTextField
A text field with a find icon in which the user enters text that identifies items to search for. JXSearchField almost looks and behaves like a native Windows Vista search box, a Mac OS X search field, or a search field like the one used in Mozilla Thunderbird 2.0 - depending on the current look and feel. JXSearchField is a text field that contains a find button and a cancel button. The find button normally displays a lens icon appropriate for the current look and feel. The cancel button is used to clear the text and therefore only visible when text is present. It normally displays a 'x' like icon. Text can also be cleared, using the 'Esc' key. The position of the find and cancel buttons can be customized by either changing the search fields (text) margin or button margin, or by changing the JXSearchField.LayoutStyle. JXSearchField supports two different search modes: JXSearchField.SearchMode.INSTANT and JXSearchField.SearchMode.REGULAR. A search can be performed by registering an ActionListener. The ActionEvents command property contains the text to search for. The search should be cancelled, when the command text is empty or null.
Author:
Peter Weishapl petw@gmx.net
See Also:

  • Constructor Details

    • JXSearchField

      public JXSearchField()
      Creates a new search field with a default prompt.

    • JXSearchField

      public JXSearchField(String prompt)
      Creates a new search field with the given prompt and JXSearchField.SearchMode.INSTANT.
      Parameters:
      prompt -

  • Method Details

    • getSearchMode

      public JXSearchField.SearchMode getSearchMode()
      Returns the current JXSearchField.SearchMode.
      Returns:
      the current JXSearchField.SearchMode.

    • isInstantSearchMode

      public boolean isInstantSearchMode()
      Returns true if the current JXSearchField.SearchMode is JXSearchField.SearchMode.INSTANT.
      Returns:
      true if the current JXSearchField.SearchMode is JXSearchField.SearchMode.INSTANT

    • isRegularSearchMode

      public boolean isRegularSearchMode()
      Returns true if the current JXSearchField.SearchMode is JXSearchField.SearchMode.REGULAR.
      Returns:
      true if the current JXSearchField.SearchMode is JXSearchField.SearchMode.REGULAR

    • setSearchMode

      public void setSearchMode(JXSearchField.SearchMode searchMode)
      Sets the current search mode. See JXSearchField.SearchMode for a description of the different search modes.
      Parameters:
      searchMode - JXSearchField.SearchMode.INSTANT or JXSearchField.SearchMode.REGULAR

    • getInstantSearchDelay

      public int getInstantSearchDelay()
      Get the instant search delay in milliseconds. The default delay is 50 Milliseconds.
      Returns:
      the instant search delay in milliseconds
      See Also:

    • setInstantSearchDelay

      public void setInstantSearchDelay(int instantSearchDelay)
      Set the instant search delay in milliseconds. In JXSearchField.SearchMode.INSTANT, when the user changes the text, an action event will be fired after the specified instant search delay. It is recommended to use a instant search delay to avoid the firing of unnecessary events. For example when the user replaces the whole text with a different text the search fields underlying Document typically fires 2 document events. The first one, because the old text is removed and the second one because the new text is inserted. If the instant search delay is 0, this would result in 2 action events being fired. When a instant search delay is used, the first document event typically is ignored, because the second one is fired before the delay is over, which results in a correct behavior because only the last and only relevant event will be delivered.
      Parameters:
      instantSearchDelay -

    • getLayoutStyle

      public JXSearchField.LayoutStyle getLayoutStyle()
      Get the current JXSearchField.LayoutStyle.
      Returns:

    • isVistaLayoutStyle

      public boolean isVistaLayoutStyle()
      Returns true if the current JXSearchField.LayoutStyle is JXSearchField.LayoutStyle.VISTA.
      Returns:

    • isMacLayoutStyle

      public boolean isMacLayoutStyle()
      Returns true if the current JXSearchField.LayoutStyle is JXSearchField.LayoutStyle.MAC.
      Returns:

    • setLayoutStyle

      public void setLayoutStyle(JXSearchField.LayoutStyle layoutStyle)
      Set the current JXSearchField.LayoutStyle. See JXSearchField.LayoutStyle for a description of how this affects layout and behavior of the search field.
      Parameters:
      layoutStyle - JXSearchField.LayoutStyle.MAC or JXSearchField.LayoutStyle.VISTA

    • setMargin

      public void setMargin(Insets m)
      Set the margin space around the search field's text.
      Overrides:
      setMargin in class JTextComponent
      See Also:

    • getCancelAction

      public final ActionListener getCancelAction()
      Returns the cancel action, or an instance of JXSearchField.ClearAction, if none has been set.
      Returns:
      the cancel action

    • setCancelAction

      public final void setCancelAction(ActionListener cancelAction)
      Sets the action that is invoked, when the user presses the 'Esc' key or clicks the cancel button.
      Parameters:
      cancelAction -

    • getCancelButton

      public final JButton getCancelButton()
      Returns the cancel button. Calls createCancelButton() to create the cancel button and registers an ActionListener that delegates actions to the ActionListener returned by getCancelAction(), if needed.
      Returns:
      the cancel button

    • createCancelButton

      protected JButton createCancelButton()
      Creates and returns the cancel button. Override to use a custom cancel button.
      Returns:
      the cancel button
      See Also:

    • getFindAction

      public final ActionListener getFindAction()
      Returns the action that is invoked when the enter key is pressed or the find button is clicked. If no action has been set, a new instance of JXSearchField.FindAction will be returned.
      Returns:
      the find action

    • setFindAction

      public final void setFindAction(ActionListener findAction)
      Sets the action that is invoked when the enter key is pressed or the find button is clicked.

    • getFindButton

      public final JButton getFindButton()
      Returns the find button. Calls createFindButton() to create the find button and registers an ActionListener that delegates actions to the ActionListener returned by getFindAction(), if needed.
      Returns:
      the find button

    • createFindButton

      protected JButton createFindButton()
      Creates and returns the find button. The buttons action is set to the action returned by getSearchAction() Override to use a custom find button.
      Returns:
      the find button
      See Also:

    • getPopupButton

      public final JButton getPopupButton()
      Returns the popup button. If a find popup menu is set, it will be displayed when this button is clicked. This button will only be visible, if isUseSeperatePopupButton() returns true. Otherwise the popup menu will be displayed when the find button is clicked.
      Returns:
      the popup button

    • createPopupButton

      protected JButton createPopupButton()
      Creates and returns the popup button. Override to use a custom popup button.
      Returns:
      the popup button
      See Also:

    • isUseSeperatePopupButton

      public boolean isUseSeperatePopupButton()
      Returns true if the popup button should be visible and used for displaying the find popup menu. Otherwise, the find popup menu will be displayed when the find button is clicked.
      Returns:
      true if the popup button should be used

    • setUseSeperatePopupButton

      public void setUseSeperatePopupButton(boolean useSeperatePopupButton)
      Set if the popup button should be used for displaying the find popup menu.
      Parameters:
      useSeperatePopupButton -

    • isUseNativeSearchFieldIfPossible

      public boolean isUseNativeSearchFieldIfPossible()

    • setUseNativeSearchFieldIfPossible

      public void setUseNativeSearchFieldIfPossible(boolean useNativeSearchFieldIfPossible)

    • setEditable

      public void setEditable(boolean b)
      Updates the cancel, find and popup buttons enabled state in addition to setting the search fields editable state.
      Overrides:
      setEditable in class JTextComponent
      See Also:

    • setEnabled

      public void setEnabled(boolean enabled)
      Updates the cancel, find and popup buttons enabled state in addition to setting the search fields enabled state.
      Overrides:
      setEnabled in class JComponent
      See Also:

    • updateButtonState

      protected void updateButtonState()
      Enables the cancel action if this search field is editable and enabled, otherwise it will be disabled. Enabled the search action and popup button if this search field is enabled, otherwise it will be disabled.

    • setFindPopupMenu

      public void setFindPopupMenu(JPopupMenu findPopupMenu)
      Sets the popup menu that will be displayed when the popup button is clicked. If a find popup menu is set and isUseSeperatePopupButton() returns false, the popup button will be displayed instead of the find button. Otherwise the popup button will be displayed in addition to the find button. The find popup menu is managed using NativeSearchFieldSupport to achieve compatibility with the native search field support provided by the Mac Look And Feel since Mac OS 10.5. If a recent searches save key has been set and therefore a recent searches popup menu is installed, this method does nothing. You must first remove the recent searches save key, by calling setRecentSearchesSaveKey(String) with a null parameter.
      Parameters:
      findPopupMenu - the popup menu, which will be displayed when the popup button is clicked
      See Also:

    • getFindPopupMenu

      public JPopupMenu getFindPopupMenu()
      Returns the find popup menu.
      Returns:
      the find popup menu
      See Also:

    • isManagingRecentSearches

      public final boolean isManagingRecentSearches()
      Returns:

    • getRecentSearchesSaveKey

      public String getRecentSearchesSaveKey()
      Returns the key used to persist recent searches.
      Returns:
      See Also:

    • setRecentSearchesSaveKey

      public void setRecentSearchesSaveKey(String recentSearchesSaveKey)
      Installs and manages a recent searches popup menu as the find popup menu, if recentSearchesSaveKey is not null. Otherwise, removes the popup menu and stops managing recent searches.
      Parameters:
      recentSearchesSaveKey - this key is used to persist the recent searches.
      See Also:

    • getRecentSearches

      public RecentSearches getRecentSearches()
      Returns:

    • getInstantSearchTimer

      public Timer getInstantSearchTimer()
      Returns the Timer used to delay the firing of action events in instant search mode when the user enters text. This timer calls postActionEvent().
      Returns:
      the Timer used to delay the firing of action events

    • hasFocus

      public boolean hasFocus()
      Returns true if this search field is the focus owner or the find popup menu is visible. This is a hack to make the search field paint the focus indicator in Mac OS X Aqua when the find popup menu is visible.
      Overrides:
      hasFocus in class Component
      Returns:
      true if this search field is the focus owner or the find popup menu is visible

    • updateUI

      public void updateUI()
      Overriden to also update the find popup menu if set.
      Overrides:
      updateUI in class JTextComponent

    • setPromptFontStyle

      public void setPromptFontStyle(Integer fontStyle)
      Hack to enable the UI delegate to set default values depending on the current Look and Feel, without overriding custom values.
      Overrides:
      setPromptFontStyle in class JXTextField
      See Also:

    • customSetUIProperty

      public void customSetUIProperty(String propertyName, Object value)
      Hack to enable the UI delegate to set default values depending on the current Look and Feel, without overriding custom values.
      Parameters:
      propertyName - the name of the property to change
      value - the new value of the property

    • customSetUIProperty

      public void customSetUIProperty(String propertyName, Object value, boolean override)
      Hack to enable the UI delegate to set default values depending on the current Look and Feel, without overriding custom values.
      Parameters:
      propertyName - the name of the property to change
      value - the new value of the property
      override - override custom values

    • postActionEvent

      public void postActionEvent()
      Overriden to prevent any delayed ActionEvents from being sent after posting this action. For example, if the current JXSearchField.SearchMode is JXSearchField.SearchMode.INSTANT and the instant search delay is greater 0. The user enters some text and presses enter. This method will be invoked immediately because the users presses enter. However, this method would be invoked after the instant search delay, if we would not prevent it here.
      Overrides:
      postActionEvent in class JTextField