Package docking.widgets

# Class DropDownTextField<T>

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
javax.swing.text.JTextComponent
javax.swing.JTextField
docking.widgets.DropDownTextField<T>

Type Parameters:
  `T` - The type of object that this model manipulates

All Implemented Interfaces:
  `GComponent`, `ImageObserver`, `MenuContainer`, `Serializable`, `Accessible`, `Scrollable`, `SwingConstants`

Direct Known Subclasses:
  `DropDownSelectionTextField`

public class DropDownTextField<T> extends JTextField implements GComponent
A text field that handles comparing text typed by the user to the list of objects and then presenting potential matches in a drop down window. The items in this window cannot be selected.

This class will fire `fireEditingStopped()` and `fireEditingCancelled()` events when the user makes a choice by pressing the ENTER key, thus allowing the client code to use this class similar in fashion to a property editor. This behavior can be configured to:

- Not consume the ENTER key press (it consumes by default), allowing the parent container to process the event (see `setConsumeEnterKeyPress(boolean)`
- Ignore the ENTER key press completely (see `setIgnoreEnterKeyPress(boolean)`

This class is subclassed to not only have the matching behavior, but to also allow for user selections.

See Also:
  - Serialized Form

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `protected class`
  `DropDownTextField.DropDownList`
  `class`
  `DropDownTextField.SearchModeBounds`
  Represents the bounds of the search mode area in this text field.

  ## Nested classes/interfaces inherited from class javax.swing.JTextField

  `JTextField.AccessibleJTextField`

  ## Nested classes/interfaces inherited from class javax.swing.text.JTextComponent

  `JTextComponent.AccessibleJTextComponent, JTextComponent.DropLocation, JTextComponent.KeyBinding`

  ## 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
  Modifier and Type
  Field
  Description
  `protected final DropDownTextFieldDataModel<T>`
  `dataModel`
  `protected boolean`
  `internallyDrivenUpdate`
  `protected DropDownTextField<T>.DropDownList`
  `list`
  `protected static final Color`
  `PREVIEW_WINDOW_BGCOLOR`
  `protected static final Color`
  `PREVIEW_WINDOW_FGCOLOR`

  ### Fields inherited from class javax.swing.JTextField

  `notifyAction`

  ### Fields inherited from class javax.swing.text.JTextComponent

  `DEFAULT_KEYMAP, FOCUS_ACCELERATOR_KEY`

  ### Fields inherited from class javax.swing.JComponent

  `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

  `accessibleContext, BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT`

  ### Fields inherited from interface docking.widgets.GComponent

  `HTML_DISABLE_STRING`

  ### Fields inherited from interface java.awt.image.ImageObserver

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

  ### 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`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DropDownTextField(DropDownTextFieldDataModel<T> dataModel)`
  Constructor.
  `DropDownTextField(DropDownTextFieldDataModel<T> dataModel, int updateMinDelay)`
  Constructor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addCellEditorListener(CellEditorListener listener)`
  Adds a listener to be notified when cell editing is canceled or completed.
  `void`
  `addDropDownSelectionChoiceListener(DropDownSelectionChoiceListener<T> listener)`
  Adds a listener that will be called back when the user makes a choice from the drop-down list.
  `void`
  `closeDropDownWindow()`
  Closes the drop down window
  `protected ListSelectionModel`
  `createListSelectionModel()`
  `protected List<T>`
  `getMatchingData(String searchText)`
  `protected ListSelectionListener`
  `getPreviewListener()`
  `protected JComponent`
  `getPreviewPaneComponent()`
  `DropDownTextFieldDataModel.SearchMode`
  `getSearchMode()`
  `DropDownTextField<T>.SearchModeBounds`
  `getSearchModeBounds()`
  Returns the search mode bounds.
  `T`
  `getSelectedValue()`
  Returns the user's selection or null if the user has not made a selection.
  `protected boolean`
  `hasPreview()`
  `protected void`
  `hideMatchingWindow()`
  `boolean`
  `isMatchingListShowing()`
  `protected void`
  `paintComponent(Graphics g)`
  `void`
  `removeCellEditorListener(CellEditorListener listener)`
  Removes the given listener from this class if it has previously been added.
  `void`
  `setConsumeEnterKeyPress(boolean consume)`
  When true, this field will not pass Enter key press events up to it's parent when the drop-down selection window is open.
  `void`
  `setIgnoreEnterKeyPress(boolean ignore)`
  True signals to do nothing when the user presses Enter.
  `void`
  `setMatchingWindowHeight(int height)`
  Sets the height of the matching window.
  `protected void`
  `setPreviewPaneAttributes()`
  `void`
  `setSearchMode(DropDownTextFieldDataModel.SearchMode newMode)`
  `protected void`
  `setSelectedItems()`
  `void`
  `setSelectedValue(T value)`
  Sets the current selection on this text field.
  `void`
  `setShowMatchingListOnEmptyText(boolean show)`
  Allows this text field to show all potential matches when the text of the field is empty.
  `void`
  `setText(String text)`
  Overridden to allow for the setting of text without showing the completion window.
  `protected void`
  `setTextFromList()`
  `protected void`
  `setTextFromSelectedListItemAndKeepMatchingWindowOpen()`
  `protected void`
  `setTextWithoutClosingCompletionWindow(String text)`
  `protected boolean`
  `shouldReplaceTextFieldTextWithSelectedItem(String textFieldText, T selectedItem)`
  `void`
  `showMatchingList()`
  Shows the matching list.
  `void`
  `updateUI()`

  ### Methods inherited from class javax.swing.JTextField

  `actionPropertyChanged, addActionListener, configurePropertiesFromAction, createActionPropertyChangeListener, createDefaultModel, fireActionPerformed, getAccessibleContext, getAction, getActionListeners, getActions, getColumns, getColumnWidth, getHorizontalAlignment, getHorizontalVisibility, getPreferredSize, getScrollOffset, getUIClassID, isValidateRoot, paramString, postActionEvent, removeActionListener, scrollRectToVisible, setAction, setActionCommand, setColumns, setDocument, setFont, setHorizontalAlignment, setScrollOffset`

  ### Methods inherited from class javax.swing.text.JTextComponent

  `addCaretListener, addInputMethodListener, addKeymap, copy, cut, fireCaretUpdate, getCaret, getCaretColor, getCaretListeners, getCaretPosition, getDisabledTextColor, getDocument, getDragEnabled, getDropLocation, getDropMode, getFocusAccelerator, getHighlighter, getInputMethodRequests, getKeymap, getKeymap, getMargin, getNavigationFilter, getPreferredScrollableViewportSize, getPrintable, getScrollableBlockIncrement, getScrollableTracksViewportHeight, getScrollableTracksViewportWidth, getScrollableUnitIncrement, getSelectedText, getSelectedTextColor, getSelectionColor, getSelectionEnd, getSelectionStart, getText, getText, getToolTipText, getUI, isEditable, loadKeymap, modelToView, modelToView2D, moveCaretPosition, paste, print, print, print, processInputMethodEvent, read, removeCaretListener, removeKeymap, removeNotify, replaceSelection, restoreComposedText, saveComposedText, select, selectAll, setCaret, setCaretColor, setCaretPosition, setComponentOrientation, setDisabledTextColor, setDragEnabled, setDropMode, setEditable, setFocusAccelerator, setHighlighter, setKeymap, setMargin, setNavigationFilter, setSelectedTextColor, setSelectionColor, setSelectionEnd, setSelectionStart, setUI, viewToModel, viewToModel2D, write`

  ### 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, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, hide, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingOrigin, isPaintingTile, isRequestFocusEnabled, paint, paintBorder, paintChildren, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, 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, 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, transferFocusDownCycle, validate, validateTree`

  ### Methods inherited from class java.awt.Component

  `action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, 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, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, 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, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, resize, resize, setBounds, setBounds, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setMixingCutoutShape, 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`

  ### Methods inherited from interface docking.widgets.GComponent

  `isHTMLRenderingEnabled, setHTMLRenderingEnabled`

- ## Field Details

  - ### PREVIEW_WINDOW_BGCOLOR

    protected static final Color PREVIEW_WINDOW_BGCOLOR

  - ### PREVIEW_WINDOW_FGCOLOR

    protected static final Color PREVIEW_WINDOW_FGCOLOR

  - ### list

    protected DropDownTextField<T>.DropDownList list

  - ### dataModel

    protected final DropDownTextFieldDataModel<T> dataModel

  - ### internallyDrivenUpdate

    protected boolean internallyDrivenUpdate

- ## Constructor Details

  - ### DropDownTextField

    public DropDownTextField(DropDownTextFieldDataModel<T> dataModel)
    Constructor.

    Uses the default refresh delay of 350ms.

    Parameters:
      `dataModel` - provides element storage and search capabilities to this component.

  - ### DropDownTextField

    public DropDownTextField(DropDownTextFieldDataModel<T> dataModel, int updateMinDelay)
    Constructor.
    Parameters:
      `dataModel` - provides element storage and search capabilities to this component.
      `updateMinDelay` - suggestion list refresh delay, triggered after search results have changed. Too low a value may cause an inconsistent view as filtering tasks complete; too high a value delivers an unresponsive user experience.

- ## Method Details

  - ### updateUI

    public void updateUI()
    Overrides:
      `updateUI` in class `JTextComponent`

  - ### getSearchMode

    public DropDownTextFieldDataModel.SearchMode getSearchMode()

  - ### setSearchMode

    public void setSearchMode(DropDownTextFieldDataModel.SearchMode newMode)

  - ### createListSelectionModel

    protected ListSelectionModel createListSelectionModel()

  - ### setPreviewPaneAttributes

    protected void setPreviewPaneAttributes()

  - ### setSelectedItems

    protected void setSelectedItems()

  - ### getPreviewListener

    protected ListSelectionListener getPreviewListener()

  - ### getPreviewPaneComponent

    protected JComponent getPreviewPaneComponent()

  - ### setText

    public void setText(String text)
    Overridden to allow for the setting of text without showing the completion window. This is useful for setting the current value to be edited before the using initiates editing.
    Overrides:
      `setText` in class `JTextComponent`
    Parameters:
      `text` - The text to set on this text field.

  - ### setTextWithoutClosingCompletionWindow

    protected void setTextWithoutClosingCompletionWindow(String text)

  - ### hasPreview

    protected boolean hasPreview()

  - ### getMatchingData

    protected List<T> getMatchingData(String searchText)

  - ### isMatchingListShowing

    public boolean isMatchingListShowing()

  - ### showMatchingList

    public void showMatchingList()
    Shows the matching list. This can be used to show all data when the user has not typed any text. For data models that have large data sets, this call may not show the matching list. This behavior is determine by the current data model.

  - ### setConsumeEnterKeyPress

    public void setConsumeEnterKeyPress(boolean consume)
    When true, this field will not pass Enter key press events up to it's parent when the drop-down selection window is open. However, an Enter key press will still be "unconsumed" when the drop-down window is not open. When set to false, this method will always pass the Enter key press up to it's parent.

    The default is true. Clients will set this to false when they wish to respond to an Enter event. For example, a dialog may want to close itself on an Enter key press, even when the drop-down selection text field is still open. Contrastingly, when this field is embedded inside of a larger editor, like a multi-editor field dialog, the Enter key press should simply trigger the drop-down window to close and the editing to stop, but should not trigger the overall dialog to close.

    Parameters:
      `consume` - true to consume

  - ### setIgnoreEnterKeyPress

    public void setIgnoreEnterKeyPress(boolean ignore)
    True signals to do nothing when the user presses Enter. The default is to respond to the Enter key, using any existing selection to set this field's `selected value`.

    This can be set to true to allow clients to show drop-down matches without allowing the user to select them, triggering the window to be closed.

    Parameters:
      `ignore` - true to ignore Enter presses; false is the default

  - ### setShowMatchingListOnEmptyText

    public void setShowMatchingListOnEmptyText(boolean show)
    Allows this text field to show all potential matches when the text of the field is empty. The default is false.
    Parameters:
      `show` - true to allow the list to be shown

  - ### setMatchingWindowHeight

    public void setMatchingWindowHeight(int height)
    Sets the height of the matching window. The default value is 300.
    Parameters:
      `height` - the new height

  - ### addDropDownSelectionChoiceListener

    public void addDropDownSelectionChoiceListener(DropDownSelectionChoiceListener<T> listener)
    Adds a listener that will be called back when the user makes a choice from the drop-down list. A choice is a user action that triggers the selection window to be closed and updates the text field.

    Note: the listener is stored in a `weak data structure`, so you must maintain a reference to the listener you pass in--anonymous classes or lambdas will not work.

    Parameters:
      `listener` - the listener

  - ### addCellEditorListener

    public void addCellEditorListener(CellEditorListener listener)
    Adds a listener to be notified when cell editing is canceled or completed.
    Parameters:
      `listener` - The listener to add
    Throws:
      `IllegalArgumentException` - if the listener has already been added

  - ### removeCellEditorListener

    public void removeCellEditorListener(CellEditorListener listener)
    Removes the given listener from this class if it has previously been added.
    Parameters:
      `listener` - The listener to remove.

  - ### setTextFromList

    protected void setTextFromList()

  - ### shouldReplaceTextFieldTextWithSelectedItem

    protected boolean shouldReplaceTextFieldTextWithSelectedItem(String textFieldText, T selectedItem)

  - ### getSelectedValue

    public T getSelectedValue()
    Returns the user's selection or null if the user has not made a selection.

    Note: the value returned from this method may not match the text in the field in the case that the user has selected a value and then typed some text.

    Returns:
      the user's selection or null if the user has not made a selection.

  - ### setSelectedValue

    public void setSelectedValue(T value)
    Sets the current selection on this text field. This will store the provided value and set the text of the text field to be the name of that value. If the given value is null, then the text of this field will be cleared.
    Parameters:
      `value` - The value that is to be the current selection or null to clear the selected value of this text field.

  - ### closeDropDownWindow

    public void closeDropDownWindow()
    Closes the drop down window

  - ### hideMatchingWindow

    protected void hideMatchingWindow()

  - ### paintComponent

    protected void paintComponent(Graphics g)
    Overrides:
      `paintComponent` in class `JComponent`

  - ### getSearchModeBounds

    public DropDownTextField<T>.SearchModeBounds getSearchModeBounds()
    Returns the search mode bounds. This is the area of the text field that shows the current search mode. This area can be hovered and clicked by the user. If there are not multiple search modes available, then this area is not painted and the bounds will be null. This value will get updated as this text field is resized.
    Returns:
      the search mode bounds

  - ### setTextFromSelectedListItemAndKeepMatchingWindowOpen

    protected void setTextFromSelectedListItemAndKeepMatchingWindowOpen()