Class ComboBox<V>

  • Type Parameters:
    V - Type to use for the items in the combo box
    All Implemented Interfaces:
    Component, Interactable, TextGUIElement

    public class ComboBox<V>
    extends AbstractInteractableComponent<ComboBox<V>>
    This is a simple combo box implementation that allows the user to select one out of multiple items through a drop-down menu. If the combo box is not in read-only mode, the user can also enter free text in the combo box, much like a TextBox.
    • Field Detail

      • items

        private final java.util.List<V> items
      • text

        private java.lang.String text
      • selectedIndex

        private int selectedIndex
      • readOnly

        private boolean readOnly
      • dropDownFocused

        private boolean dropDownFocused
      • textInputPosition

        private int textInputPosition
      • dropDownNumberOfRows

        private int dropDownNumberOfRows
    • Constructor Detail

      • ComboBox

        @SafeVarargs
        public ComboBox​(V... items)
        Creates a new ComboBox initialized with N number of items supplied through the varargs parameter. If at least one item is given, the first one in the array will be initially selected. By default 10 items will be displayed at once, more than that and there will be a scroll bar.
        Parameters:
        items - Items to populate the new combo box with
      • ComboBox

        public ComboBox​(java.util.Collection<V> items)
        Creates a new ComboBox initialized with N number of items supplied through the items parameter. If at least one item is given, the first one in the collection will be initially selected. By default 10 items will be displayed at once, more than that and there will be a scroll bar.
        Parameters:
        items - Items to populate the new combo box with
      • ComboBox

        public ComboBox​(java.lang.String initialText,
                        java.util.Collection<V> items)
        Creates a new ComboBox initialized with N number of items supplied through the items parameter. The initial text in the combo box is set to a specific value passed in through the initialText parameter, it can be a text which is not contained within the items and the selection state of the combo box will be "no selection" (so getSelectedIndex() will return -1) until the user interacts with the combo box and manually changes it. By default 10 items will be displayed at once, more than that and there will be a scroll bar.
        Parameters:
        initialText - Text to put in the combo box initially
        items - Items to populate the new combo box with
      • ComboBox

        public ComboBox​(java.util.Collection<V> items,
                        int selectedIndex)
        Creates a new ComboBox initialized with N number of items supplied through the items parameter. The initially selected item is specified through the selectedIndex parameter. By default 10 items will be displayed at once, more than that and there will be a scroll bar.
        Parameters:
        items - Items to populate the new combo box with
        selectedIndex - Index of the item which should be initially selected
    • Method Detail

      • addItem

        public ComboBox<V> addItem​(V item)
        Adds a new item to the combo box, at the end
        Parameters:
        item - Item to add to the combo box
        Returns:
        Itself
      • addItem

        public ComboBox<V> addItem​(int index,
                                   V item)
        Adds a new item to the combo box, at a specific index
        Parameters:
        index - Index to add the item at
        item - Item to add
        Returns:
        Itself
      • clearItems

        public ComboBox<V> clearItems()
        Removes all items from the combo box
        Returns:
        Itself
      • removeItem

        public ComboBox<V> removeItem​(V item)
        Removes a particular item from the combo box, if it is present, otherwise does nothing
        Parameters:
        item - Item to remove from the combo box
        Returns:
        Itself
      • removeItem

        public ComboBox<V> removeItem​(int index)
        Removes an item from the combo box at a particular index
        Parameters:
        index - Index of the item to remove
        Returns:
        Itself
        Throws:
        java.lang.IndexOutOfBoundsException - if the index is out of range
      • setItem

        public ComboBox<V> setItem​(int index,
                                   V item)
        Updates the combo box so the item at the specified index is swapped out with the supplied value in the item parameter
        Parameters:
        index - Index of the item to swap out
        item - Item to replace with
        Returns:
        Itself
      • getItemCount

        public int getItemCount()
        Counts and returns the number of items in this combo box
        Returns:
        Number of items in this combo box
      • getItem

        public V getItem​(int index)
        Returns the item at the specific index
        Parameters:
        index - Index of the item to return
        Returns:
        Item at the specific index
        Throws:
        java.lang.IndexOutOfBoundsException - if the index is out of range
      • getText

        public java.lang.String getText()
        Returns the text currently displayed in the combo box, this will likely be the label of the selected item but for writable combo boxes it's also what the user has typed in
        Returns:
        String currently displayed in the combo box
      • setReadOnly

        public ComboBox<V> setReadOnly​(boolean readOnly)
        Sets the combo box to either read-only or writable. In read-only mode, the user cannot type in any text in the combo box but is forced to pick one of the items, displayed by the drop-down. In writable mode, the user can enter any string in the combo box
        Parameters:
        readOnly - If the combo box should be in read-only mode, pass in true, otherwise false for writable mode
        Returns:
        Itself
      • isReadOnly

        public boolean isReadOnly()
        Returns true if this combo box is in read-only mode
        Returns:
        true if this combo box is in read-only mode, false otherwise
      • isDropDownFocused

        public boolean isDropDownFocused()
        Returns true if the users input focus is currently on the drop-down button of the combo box, so that pressing enter would trigger the popup window. This is generally used by renderers only and is always true for read-only combo boxes as the component won't allow you to focus on the text in that mode.
        Returns:
        true if the input focus is on the drop-down "button" of the combo box
      • getTextInputPosition

        public int getTextInputPosition()
        For writable combo boxes, this method returns the position where the text input cursor is right now. Meaning, if the user types some character, where are those are going to be inserted in the string that is currently displayed. If the text input position equals the size of the currently displayed text, new characters will be appended at the end. The user can usually move the text input position by using left and right arrow keys on the keyboard.
        Returns:
        Current text input position
      • getDropDownNumberOfRows

        public int getDropDownNumberOfRows()
        Returns the number of items to display in drop down at one time, if there are more items in the model there will be a scrollbar to help the user navigate. If this returns 0, the combo box will always grow to show all items in the list, which might cause undesired effects if you put really a lot of items into the combo box.
        Returns:
        Number of items (rows) that will be displayed in the combo box, or 0 if the combo box will always grow to accommodate
      • setDropDownNumberOfRows

        public void setDropDownNumberOfRows​(int dropDownNumberOfRows)
        Sets the number of items to display in drop down at one time, if there are more items in the model there will be a scrollbar to help the user navigate. Use this method if your combo boxes have large models that fills up the whole screen. Set it to 0 if you don't want to limit the number.
        Parameters:
        dropDownNumberOfRows - Max number of items (rows) to display at one time in the combo box
      • setSelectedIndex

        public void setSelectedIndex​(int selectedIndex)
        Programmatically selects one item in the combo box, which causes the displayed text to change to match the label of the selected index.
        Parameters:
        selectedIndex - Index of the item to select, or -1 if the selection should be cleared
        Throws:
        java.lang.IndexOutOfBoundsException - if the index is out of range
      • setSelectedIndex

        private void setSelectedIndex​(int selectedIndex,
                                      boolean changedByUserInteraction)
      • setSelectedItem

        public void setSelectedItem​(V item)
        Programmatically selects one item in the combo box by passing in the value the should be selected. If the value isn't in the combo box model, nothing happens for read-only combo boxes and for editable ones the text content is changed to match the result from calling the toString() method of item.

        If called with null, the selection is cleared.

        Parameters:
        item - Item in the combo box to select, or null if the selection should be cleared
      • updateText

        private void updateText​(java.lang.String newText)
      • getSelectedIndex

        public int getSelectedIndex()
        Returns the index of the currently selected item or -1 for no selection
        Returns:
        Index of the currently selected item
      • getSelectedItem

        public V getSelectedItem()
        Returns the item at the selected index, this is the same as calling:
        
             getSelectedIndex() > -1 ? getItem(getSelectedIndex()) : null
         
        Returns:
        The item at the selected index
      • addListener

        public ComboBox<V> addListener​(ComboBox.Listener listener)
        Adds a new listener to the ComboBox that will be called on certain user actions
        Parameters:
        listener - Listener to attach to this ComboBox
        Returns:
        Itself
      • removeListener

        public ComboBox<V> removeListener​(ComboBox.Listener listener)
        Removes a listener from this ComboBox so that if it had been added earlier, it will no longer be called on user actions
        Parameters:
        listener - Listener to remove from this ComboBox
        Returns:
        Itself
      • afterEnterFocus

        protected void afterEnterFocus​(Interactable.FocusChangeDirection direction,
                                       Interactable previouslyInFocus)
        Description copied from class: AbstractInteractableComponent
        Called by AbstractInteractableComponent automatically after this component has received input focus. You can override this method if you need to trigger some action based on this.
        Overrides:
        afterEnterFocus in class AbstractInteractableComponent<ComboBox<V>>
        Parameters:
        direction - How focus was transferred, keep in mind this is from the previous component's point of view so if this parameter has value DOWN, focus came in from above
        previouslyInFocus - Which interactable component had focus previously
      • afterLeaveFocus

        protected void afterLeaveFocus​(Interactable.FocusChangeDirection direction,
                                       Interactable nextInFocus)
        Description copied from class: AbstractInteractableComponent
        Called by AbstractInteractableComponent automatically after this component has lost input focus. You can override this method if you need to trigger some action based on this.
        Overrides:
        afterLeaveFocus in class AbstractInteractableComponent<ComboBox<V>>
        Parameters:
        direction - How focus was transferred, keep in mind this is from the this component's point of view so if this parameter has value DOWN, focus is moving down to a component below
        nextInFocus - Which interactable component is going to receive focus
      • createDefaultRenderer

        protected InteractableRenderer<ComboBox<V>> createDefaultRenderer()
        Description copied from class: AbstractComponent
        When you create a custom component, you need to implement this method and return a Renderer which is responsible for taking care of sizing the component, rendering it and choosing where to place the cursor (if Interactable). This value is intended to be overridden by custom themes.
        Specified by:
        createDefaultRenderer in class AbstractInteractableComponent<ComboBox<V>>
        Returns:
        Renderer to use when sizing and drawing this component
      • handleKeyStroke

        public Interactable.Result handleKeyStroke​(KeyStroke keyStroke)
        Description copied from class: AbstractInteractableComponent
        This method can be overridden to handle various user input (mostly from the keyboard) when this component is in focus. The input method from the interface, handleInput(..) is final in AbstractInteractableComponent to ensure the input filter is properly handled. If the filter decides that this event should be processed, it will call this method.
        Overrides:
        handleKeyStroke in class AbstractInteractableComponent<ComboBox<V>>
        Parameters:
        keyStroke - What input was entered by the user
        Returns:
        Result of processing the key-stroke
      • showPopup

        protected void showPopup​(KeyStroke keyStroke)