Package docking.widgets

Class DropDownTextField<T>

  • Type Parameters:
    T - The type of object that this model manipulates
    All Implemented Interfaces:
    GComponent, java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, javax.accessibility.Accessible, javax.swing.Scrollable, javax.swing.SwingConstants
    Direct Known Subclasses:
    DropDownSelectionTextField
    public class DropDownTextField<T>
extends javax.swing.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:

    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/interfaces inherited from class javax.swing.JTextField

        javax.swing.JTextField.AccessibleJTextField

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

        javax.swing.text.JTextComponent.AccessibleJTextComponent, javax.swing.text.JTextComponent.DropLocation, javax.swing.text.JTextComponent.KeyBinding

      • 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

      Fields 
      Modifier and Type Field Description
      protected DropDownTextFieldDataModel<T> dataModel  
      protected boolean internallyDrivenUpdate  
      protected GList<T> list  
      protected static java.awt.Color TOOLTIP_WINDOW_BGCOLOR  

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

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addCellEditorListener​(javax.swing.event.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 javax.swing.ListSelectionModel createListSelectionModel()  
      protected java.util.List<T> getMatchingData​(java.lang.String searchText)  
      protected javax.swing.event.ListSelectionListener getPreviewListener()  
      protected javax.swing.JComponent getPreviewPaneComponent()  
      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 boolean processKeyBinding​(javax.swing.KeyStroke ks, java.awt.event.KeyEvent e, int condition, boolean pressed)  
      void removeCellEditorListener​(javax.swing.event.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()  
      protected void setSelectedItems()  
      void setSelectedValue​(T value)
      Sets the current selection on this text field.
      void setText​(java.lang.String text)
      Overridden to allow for the setting of text without showing the completion window.
      protected void setTextFromList()  
      protected void setTextFromSelectedListItemAndKeepMatchingWindowOpen()  
      protected void setTextWithoutClosingCompletionWindow​(java.lang.String text)  

      • 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, updateUI, 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, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, 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

    • Field Detail

      • TOOLTIP_WINDOW_BGCOLOR

        protected static final java.awt.Color TOOLTIP_WINDOW_BGCOLOR

      • list

        protected GList<T> list

      • internallyDrivenUpdate

        protected boolean internallyDrivenUpdate

    • Constructor Detail

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

      • createListSelectionModel

        protected javax.swing.ListSelectionModel createListSelectionModel()

      • setPreviewPaneAttributes

        protected void setPreviewPaneAttributes()

      • setSelectedItems

        protected void setSelectedItems()

      • getPreviewListener

        protected javax.swing.event.ListSelectionListener getPreviewListener()

      • getPreviewPaneComponent

        protected javax.swing.JComponent getPreviewPaneComponent()

      • processKeyBinding

        protected boolean processKeyBinding​(javax.swing.KeyStroke ks,
                                    java.awt.event.KeyEvent e,
                                    int condition,
                                    boolean pressed)
        Overrides:
        processKeyBinding in class javax.swing.JComponent

      • setText

        public void setText​(java.lang.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 javax.swing.text.JTextComponent
        Parameters:
        text - The text to set on this text field.

      • setTextWithoutClosingCompletionWindow

        protected void setTextWithoutClosingCompletionWindow​(java.lang.String text)

      • hasPreview

        protected boolean hasPreview()

      • getMatchingData

        protected java.util.List<T> getMatchingData​(java.lang.String searchText)

      • isMatchingListShowing

        public boolean isMatchingListShowing()

      • 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

      • 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

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

      • addCellEditorListener

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

      • removeCellEditorListener

        public void removeCellEditorListener​(javax.swing.event.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()

      • getSelectedValue

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

        Note: the 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()

      • setTextFromSelectedListItemAndKeepMatchingWindowOpen

        protected void setTextFromSelectedListItemAndKeepMatchingWindowOpen()