Holger's Java API

## com.antelmann.util.gui
Class JSearchList

    java.lang.Object
      java.awt.Component
          java.awt.Container
              javax.swing.JComponent
                  com.antelmann.util.gui.JSearchList

All Implemented Interfaces:
  ListRetriever<Object>, ValueRetriever<Object>, ImageObserver, MenuContainer, Serializable

    public class JSearchList

extends JComponent
implements ValueRetriever<Object>, ListRetriever<Object>

provides a selection list that can be case-insensitively filtered by its toString() representation through a text field. This component already registers appropriate selection listeners that fire a `PropertyChangeEvent` upon selection changes. The list itself is sorted by the global UniversalComparator.

Author:
  Holger Antelmann
See Also:
  `JSearchTable`, `JPreviewPane`, Serialized Form

Nested Class Summary

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

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
`JSearchList()` needed to make this component appear like a bean
`JSearchList(Collection<?> list)`
`JSearchList(Object... elements)` elements must not contain null

Method Summary
`protected boolean` `acceptListEntry(Object element, String searchText)` may be overwritten to specialize the filtering behavior based on the current text selection.
`boolean` `contains(Object element)`
`Object[]` `getElements()`
`JList` `getJList()` returns the filtered active list
`List<Object>` `getRelevantList()` returns the currently relevant list of the denotes objects
`String` `getRelevantListDescription()`
`Object` `getRelevantValue()` returns the relevant value for this instance at the time of calling
`JTextField` `getSearchField()` return the search field used to enter search criteria
`String` `getSearchText()` returns the current search pattern used for convenience
`Object` `getSelectedItem()` convenience method
`Object[]` `getSelectedItems()` convenience method
`boolean` `isImmediateSearch()`
`boolean` `isMultiWordSearchOption()`
`static JComboBox` `makeMultipleSelectComboBox(String dialogTitle, Object[] items, Object... initialSelection)` Deprecated. use `JMultipleSelectionComboBox` directly instead
`static void` `makeSearchable(JComboBox combo, String dialogTitle)` registers a MouseListener that will provide a JSearchList upon double-click
`boolean` `requestFocusInWindow()`
`void` `selectAll()` convenience method
`void` `setDefaultToolTipRenderer()` a convenience method that will set a Renderer on the JList that will display the toString()-value upon mouse over
`void` `setElements(Collection<?> newElements)`

`

`<T> void`

`

`setElements(Collection<T> newElements, Comparator<? super T> c)`

`void` `setElements(Object[] newElements)`
`void` `setElements(Object[] newElements, Comparator<Object> comparator)` if the comparator is null, the given newElements are not sorted
`void` `setImmediateSearch(boolean immediateSearch)`
`void` `setMultiWordSearchOption(boolean multiWordSearchOption)`
`void` `setRenderer(ListCellRenderer renderer)` shortcut
`void` `setRenderer(PatternExtractor<Object,String> pe)` shortcut for using a `FormattedCellRenderer`
`void` `setSearchText(String txt)`
`void` `setSelectedItem(Object obj)` convenience method
`void` `setSelectedItems(Object... items)` convenience method
`static Object[]` `showMultipleSelectDialog(Component parent, String title, Object[] elements, boolean sortByRendererIfApplicable, ListCellRenderer renderer, Object... currentSelection)`
`static Object[]` `showMultipleSelectDialog(Component parent, String title, Object[] elements, ListCellRenderer renderer, Object... currentSelection)`
`static Object[]` `showMultipleSelectDialog(Component parent, String title, Object[] elements, Object... currentSelection)`
`static Object` `showSelectDialog(Component parent, String title, boolean immediateSearch, boolean multiWordSearchOption, Object[] elements, Object currentSelected)`
`static Object` `showSelectDialog(Component parent, String title, boolean immediateSearch, boolean multiWordSearchOption, Object[] elements, Object currentSelected, boolean sortByRendererIfApplicable, ListCellRenderer renderer, Dimension dim)`
`static Object` `showSelectDialog(Component parent, String title, boolean immediateSearch, boolean multiWordSearchOption, Object[] elements, Object currentSelected, ListCellRenderer renderer)`
`static Object` `showSelectDialog(Component parent, String title, boolean immediateSearch, boolean multiWordSearchOption, Object[] elements, Object currentSelected, ListCellRenderer renderer, Dimension dim)`

`static

`<T> T`

`

`showSelectDialog(Component parent, String title, Collection<T> elements)`

`static

`<T> T`

`

`showSelectDialog(Component parent, String title, Collection<T> elements, Object currentSelected)`

`static Object` `showSelectDialog(Component parent, String title, Object[] elements)` shows a JDialog to choose from the given objects.
`static Object` `showSelectDialog(Component parent, String title, Object[] elements, Object currentSelected)`
`void` `sortByRenderer()` useful after setting a custom renderer on the JList

Methods inherited from class javax.swing.JComponent

`addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getAccessibleContext, 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, getUIClassID, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, paramString, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, 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, updateUI`

Methods inherited from class java.awt.Container

`add, add, add, add, add, addContainerListener, addImpl, 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

### JSearchList

    public JSearchList()

  needed to make this component appear like a bean

### JSearchList

    public JSearchList(Collection<?> list)

### JSearchList

    public JSearchList(Object... elements)

  elements must not contain null

Method Detail

### requestFocusInWindow

    public boolean requestFocusInWindow()

  Overrides:
    `requestFocusInWindow` in class `JComponent`

### sortByRenderer

    public void sortByRenderer()

  useful after setting a custom renderer on the JList

### isImmediateSearch

    public boolean isImmediateSearch()

### setImmediateSearch

    public void setImmediateSearch(boolean immediateSearch)

### isMultiWordSearchOption

    public boolean isMultiWordSearchOption()

### setMultiWordSearchOption

    public void setMultiWordSearchOption(boolean multiWordSearchOption)

### acceptListEntry

    protected boolean acceptListEntry(Object element,
                                      String searchText)

  may be overwritten to specialize the filtering behavior based on the current text selection. This default implementation checks whether the given searchText is present in the `toString()` value of the given element (case-insensitive) by default; additionally, if a renderer is present that uses a JLabel, the text of the same is used instead. If `isMultiWordSearchOption()` is enabled, the search pattern is taken as several search strings separated by space where all strings need to be present.

  Parameters:
    `searchText` - the current value of the search field; is never null, but may be of length 0 if no search text is entered

### setDefaultToolTipRenderer

    public void setDefaultToolTipRenderer()

  a convenience method that will set a Renderer on the JList that will display the toString()-value upon mouse over

### setRenderer

    public void setRenderer(ListCellRenderer renderer)

  shortcut

### setRenderer

    public void setRenderer(PatternExtractor<Object,String> pe)

  shortcut for using a `FormattedCellRenderer`

### setSearchText

    public void setSearchText(String txt)

### setElements

    public void setElements(Collection<?> newElements)

### setElements

    public <T> void setElements(Collection<T> newElements,
                                Comparator<? super T> c)

### setElements

    public void setElements(Object[] newElements)

### setElements

    public void setElements(Object[] newElements,
                            Comparator<Object> comparator)

  if the comparator is null, the given newElements are not sorted

### contains

    public boolean contains(Object element)

### getElements

    public Object[] getElements()

### getSearchField

    public JTextField getSearchField()

  return the search field used to enter search criteria

### getJList

    public JList getJList()

  returns the filtered active list

### getSearchText

    public String getSearchText()

  returns the current search pattern used for convenience

### getRelevantValue

    public Object getRelevantValue()

  Description copied from interface: `ValueRetriever`
  returns the relevant value for this instance at the time of calling

  Specified by:
    `getRelevantValue` in interface `ValueRetriever<Object>`

### getSelectedItem

    public Object getSelectedItem()

  convenience method

### setSelectedItem

    public void setSelectedItem(Object obj)

  convenience method

### getRelevantList

    public List<Object> getRelevantList()

  Description copied from interface: `ListRetriever`
  returns the currently relevant list of the denotes objects

  Specified by:
    `getRelevantList` in interface `ListRetriever<Object>`

### getRelevantListDescription

    public String getRelevantListDescription()

  Specified by:
    `getRelevantListDescription` in interface `ListRetriever<Object>`

### getSelectedItems

    public Object[] getSelectedItems()

  convenience method

### selectAll

    public void selectAll()

  convenience method

### setSelectedItems

    public void setSelectedItems(Object... items)

  convenience method

### showSelectDialog

    public static <T> T showSelectDialog(Component parent,
                                         String title,
                                         Collection<T> elements)

### showSelectDialog

    public static <T> T showSelectDialog(Component parent,
                                         String title,
                                         Collection<T> elements,
                                         Object currentSelected)

### showSelectDialog

    public static Object showSelectDialog(Component parent,
                                          String title,
                                          Object[] elements)

  shows a JDialog to choose from the given objects.

  Returns:
    the selected object or null if no object was selected

### showSelectDialog

    public static Object showSelectDialog(Component parent,
                                          String title,
                                          Object[] elements,
                                          Object currentSelected)

### showSelectDialog

    public static Object showSelectDialog(Component parent,
                                          String title,
                                          boolean immediateSearch,
                                          boolean multiWordSearchOption,
                                          Object[] elements,
                                          Object currentSelected)

### showSelectDialog

    public static Object showSelectDialog(Component parent,
                                          String title,
                                          boolean immediateSearch,
                                          boolean multiWordSearchOption,
                                          Object[] elements,
                                          Object currentSelected,
                                          ListCellRenderer renderer)

### showSelectDialog

    public static Object showSelectDialog(Component parent,
                                          String title,
                                          boolean immediateSearch,
                                          boolean multiWordSearchOption,
                                          Object[] elements,
                                          Object currentSelected,
                                          ListCellRenderer renderer,
                                          Dimension dim)

### showSelectDialog

    public static Object showSelectDialog(Component parent,
                                          String title,
                                          boolean immediateSearch,
                                          boolean multiWordSearchOption,
                                          Object[] elements,
                                          Object currentSelected,
                                          boolean sortByRendererIfApplicable,
                                          ListCellRenderer renderer,
                                          Dimension dim)

### showMultipleSelectDialog

    public static Object[] showMultipleSelectDialog(Component parent,
                                                    String title,
                                                    Object[] elements,
                                                    Object... currentSelection)

### showMultipleSelectDialog

    public static Object[] showMultipleSelectDialog(Component parent,
                                                    String title,
                                                    Object[] elements,
                                                    ListCellRenderer renderer,
                                                    Object... currentSelection)

### showMultipleSelectDialog

    public static Object[] showMultipleSelectDialog(Component parent,
                                                    String title,
                                                    Object[] elements,
                                                    boolean sortByRendererIfApplicable,
                                                    ListCellRenderer renderer,
                                                    Object... currentSelection)

### makeSearchable

    public static void makeSearchable(JComboBox combo,
                                      String dialogTitle)

  registers a MouseListener that will provide a JSearchList upon double-click

### makeMultipleSelectComboBox

    @Deprecated
    public static JComboBox makeMultipleSelectComboBox(String dialogTitle,
                                                                  Object[] items,
                                                                  Object... initialSelection)

  Deprecated. use `JMultipleSelectionComboBox` directly instead

  returns a special JComboBox which - upon double-mouse-click - provides a multiple-select search list that is reflected in the JComboBox's method `JComboBox.getSelectedObjects()` and displays a special multiple-select object when a multiple selection is present. The returned JComboBox uses a `DefaultComboBoxModel`, which may at times contain a special 'multipleSelect'-Object. Note that `JComboBox.getSelectedItem()` may return an irritating value (a 'multiple-select' object), which indicates that there is a multiple selection present; thus it is recommended to always call `JComboBox.getSelectedObjects()` to obtain the correct selection.

  See Also:
    `JMultipleSelectionComboBox`

(c) Holger Antelmann since 2001- all rights reserved (contact: info@antelmann.com)
see www.antelmann.com/developer for further details and available downloads