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 Details

    • items

      private final List<V> items
    • listeners

      private final List<ComboBox.Listener> listeners
    • text

      private String text
    • selectedIndex

      private int selectedIndex
    • readOnly

      private boolean readOnly
    • textInputPosition

      private int textInputPosition
  • Constructor Details

    • 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(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(String initialText, 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(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 Details

    • 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:
      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:
      IndexOutOfBoundsException - if the index is out of range
    • getText

      public 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:
      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(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
    • handleReadOnlyCBKeyStroke

      private Interactable.Result handleReadOnlyCBKeyStroke(KeyStroke keyStroke)
    • showPopup

      protected void showPopup(KeyStroke keyStroke)
    • handleEditableCBKeyStroke

      private Interactable.Result handleEditableCBKeyStroke(KeyStroke keyStroke)