Package totalcross.ui

Class MultiListBox

  • All Implemented Interfaces:
    Scrollable
    public class MultiListBox
extends ListBox
    MultiListBox is a listbox that allows more than one item to be selected. The maximum number of selections can be defined using setMaxSelections.

    To create a ComboBox with a MultiListBox, use: 
     MultiListBox mlb;
 new ComboBox(mlb = new MultiListBox())
    Be sure to save a reference to the MultiListBox so you can call the specific methods of this class. For instance, getSelectedIndex returns just the last selected index; to retrieve all indexes, use getSelectedIndexes.

    In penless devices, there will be a cursor which will be used to highlight an item; to select or unselect it, you must press the left key.

    MultiListBox requires the useFullWidthOnSelection on penless devices.
    Since:
    TotalCross 1.0.

    • Field Detail

      • maxSelections

        protected int maxSelections

      • oldSelection

        protected int oldSelection

      • changed

        public boolean changed
        Internal use only.

      • clearValues

        public IntVector clearValues
        Fill this IntVector with the values that will be selected when the clear method is called.

      • showOrderInTip

        public boolean showOrderInTip
        Set to false to don't show the number of selected elements as they are clicked.
        Since:
        TotalCross 1.3

      • unselectFirstWhenMaxIsReached

        public boolean unselectFirstWhenMaxIsReached
        Set to true if you want to unselect the first element once max is reached. Note that this implies that setOrderIsImportant(true) and also setMaxSelections were both called, otherwise it has no effects.

      • itemsText

        public static java.lang.String itemsText
        Global suffix used to display the number of items in a ComboBox. Defaults to " items".

      • localItemsText

        public java.lang.String localItemsText
        Local suffix to display the number of items in a ComboBox. Defaults to " items".

      • tipDelay

        public int tipDelay
        The amount of time used to show how many itens.

    • Constructor Detail

      • MultiListBox

        public MultiListBox()
        Constructs an empty MultiListBox.

      • MultiListBox

        public MultiListBox​(java.lang.Object[] items)
        Constructs a MultiListBox with the given items.

    • Method Detail

      • setOrderIsImportant

        public void setOrderIsImportant​(boolean set)
        Call this method if you want to keep track of the order in which the items were selected. Note that this makes the listbox slower. Calling this method clears all selected items.

      • isOrderImportant

        public boolean isOrderImportant()
        Returns true if you requested that the order is important.

      • getSelectedIndex

        public int getSelectedIndex()
        Returns the selected index. If more than one item is selected, returns the last one.
        Overrides:
        getSelectedIndex in class ListBox

      • getLastSelectedItem

        public java.lang.Object getLastSelectedItem()
        Returns the last selected item if you had set order is important, otherwise returns null.

      • setMaxSelections

        public void setMaxSelections​(int max)
        Defines the maximum number of items that can be selected. If currently there are more selected than the allowed, all selections are cleared.

      • getSelectedIndexes

        public IntVector getSelectedIndexes()
        Return a vector with the indexes which have been selected. The elements of the Vector are the indexes in the Vector of the items. So if this Vector is holding [3, 12, 5] it means that the items 3, 5 and 12 have been selected. If order is important, then the order intvector is returned (caution: do not change the returned array!). Note that the indexes are not in order; to order them, call qsort.

      • isSelected

        public boolean isSelected​(int index)
        Returns if given index is selected.

      • removeAll

        public void removeAll()
        Description copied from class: ListBox
        Empties this ListBox, setting all elements of the array to null so they can be garbage collected. Attention! If you used the same object array to initialize two ListBoxes (or ComboBoxes), this method will null both ListBoxes (because they use the same array reference), and you'll get a null pointer exception!
        Overrides:
        removeAll in class ListBox

      • onColorsChanged

        protected void onColorsChanged​(boolean colorsChanged)
        Description copied from class: Control
        Called after a setEnabled, setForeColor and setBackColor and when a control has been added to a Container. If colorsChanged is true, it was called from setForeColor/setBackColor/Container.add; otherwise, it was called from setEnabled
        Overrides:
        onColorsChanged in class ListBox

      • drawSelectedItem

        protected void drawSelectedItem​(Graphics g,
                                int from,
                                int to)
        Draw all selected indexes
        Overrides:
        drawSelectedItem in class ListBox

      • drawItems

        protected void drawItems​(Graphics g,
                         int dx,
                         int dy,
                         int greatestVisibleItemIndex)
        Overrides:
        drawItems in class ListBox

      • getCursorColor

        protected int getCursorColor​(int index)
        Overrides:
        getCursorColor in class ListBox

      • setSelectedIndex

        public void setSelectedIndex​(int index,
                             boolean set)
        Sets or clear an index. Can also be used to set or clear all indexes, passing -1 as the index. Both operations are limited by the defined max selections.
        Overrides:
        setSelectedIndex in class ListBox

      • handleSelection

        protected void handleSelection​(int newSelection)
        Overrides:
        handleSelection in class ListBox

      • cbddOnPopup

        protected void cbddOnPopup()
        Called by ComboBoxDropDown when its being popped.

      • cbddOnUnpop

        protected void cbddOnUnpop()
        Called by ComboBoxDropDown when its being unpopped. Sends a PRESSED event if a change was made in the selected indexes.

      • postPressedEvent

        public void postPressedEvent()
        Description copied from class: Control
        Posts a ControlEvent.PRESSED event with this control as target.
        Overrides:
        postPressedEvent in class Control

      • handleClick

        protected void handleClick​(int index)

      • getText

        public java.lang.String getText()
        Returns the String with the selected item (if single) or a string with the number of selected items. You can change the suffix itemsText or localItemsText to another one. If order is important, returns the last selected item.
        Overrides:
        getText in class ListBox

      • handleGeographicalFocusChangeKeys

        public Control handleGeographicalFocusChangeKeys​(KeyEvent ke)
        Description copied from class: Control
        Used by the main event loop to give the currently focused control an opportunity to act directly on the KeyEvent.
        Overrides:
        handleGeographicalFocusChangeKeys in class ListBox
        Parameters:
        ke - The KeyEvent to be processed
        Returns:
        The control that should get focus as a result of this KeyEvent. Null if this control did not handle the KeyEvent.
        See Also:
        Settings.geographicalFocus

      • clear

        public void clear()
        Description copied from class: ListBox
        Clears this control, selecting index clearValueInt.
        Overrides:
        clear in class ListBox