MultiListBox (TotalCrossSDK 6.1.0 API)

java.lang.Object
- totalcross.ui.gfx.GfxSurface
- - totalcross.ui.Control
  - - totalcross.ui.Container
    - - totalcross.ui.ListBox
      - totalcross.ui.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.

Nested Class Summary
- Nested classes/interfaces inherited from class totalcross.ui.ListBox
  ListBox.CustomDrawingItem, ListBox.IconItem
- Nested classes/interfaces inherited from class totalcross.ui.Control
  Control.TranslucentShape

Field Summary

Fields
Modifier and Type	Field and Description
`boolean`	`changed` Internal use only.
`IntVector`	`clearValues` Fill this IntVector with the values that will be selected when the clear method is called.
`static java.lang.String`	`itemsText` Global suffix used to display the number of items in a ComboBox.
`java.lang.String`	`localItemsText` Local suffix to display the number of items in a ComboBox.
`protected int`	`maxSelections`
`protected static int`	`NO_OLD_SELECTION`
`protected int`	`oldSelection`
`protected IntVector`	`order`
`protected IntHashtable`	`selectedIndexes`
`boolean`	`showOrderInTip` Set to false to don't show the number of selected elements as they are clicked.
`int`	`tipDelay` The amount of time used to show how many itens.
`boolean`	`unselectFirstWhenMaxIsReached` Set to true if you want to unselect the first element once max is reached.

Fields inherited from class totalcross.ui.ListBox
autoResizeIcon, back0, back1, btnX, btnX0, customCursorColor, dataCol, DEFAULT_ITEM_HEIGHT_FACTOR, drawBorder, EXTRA_HEIGHT_FACTOR, extraHorizScrollButtonHeight, flick, iconGap, iconSize, ihFactor, ihtBackColors, ihtForeColors, itemCount, itemHeightFactor, items, offset, paddingBottom, paddingLeft, paddingRight, paddingTop, sbar, selectedIndex, simpleBorder, tempSelectedIndex, useFullWidthOnSelection, visibleItems, visibleLines, xOffset

Fields inherited from class totalcross.ui.Container
alwaysEraseBackground, BACKGROUND_CYLINDRIC_SHADED, BACKGROUND_SHADED, BACKGROUND_SHADED_INV, BACKGROUND_SOLID, backgroundStyle, BORDER_LOWERED, BORDER_NONE, BORDER_RAISED, BORDER_ROUNDED, BORDER_SIMPLE, BORDER_TOP, borderColor, borderRadius, children, controlFound, finishedStart, ignoreOnAddAgain, ignoreOnRemove, insets, lastH, lastScreenWidth, lastW, lastX, lastY, numChildren, started, tabOrder, tail, TRANSITION_TIME

Fields inherited from class totalcross.ui.Control
AFTER, alphaValue, appId, appObj, asContainer, asWindow, backColor, BEFORE, BOTTOM, BOTTOM_OF, BRIGHTER_BACKGROUND, callListenersOnAllTargets, CENTER, CENTER_OF, clearValueInt, clearValueStr, DARKER_BACKGROUND, DP, effect, enableUpdateScreen, esce, eventsEnabled, FILL, fillColor, FIT, floating, fm, fmH, focusHandler, focusLess, focusOnPenDown, focusTraversable, font, FONTSIZE, foreColor, height, ignoreInsets, isHighlighting, isTablet, KEEP, keepDisabled, keepEnabled, LEFT, next, nextTabControl, npParts, offscreen, offscreen0, onEventFirst, parent, PARENTSIZE, PARENTSIZEMAX, PARENTSIZEMIN, PREFERRED, prev, RANGE, repositionAllowed, RIGHT, RIGHT_OF, SAME, SCREENSIZE, SCREENSIZEMAX, SCREENSIZEMIN, setFont, setH, setRel, setW, setX, SETX_NOT_SET, setY, tempW, textShadowColor, TOP, translucentShape, transparentBackground, uiAdjustmentsBasedOnFontHeightIsSupported, uiAndroid, UICONST, uiFlat, uiHolo, uiMaterial, uiVista, visible, width, WILL_RESIZE, x, y

Constructor Summary

Constructors
Constructor and Description

MultiListBox()
Constructs an empty MultiListBox.

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

Constructors
Constructor and Description
`MultiListBox()` Constructs an empty MultiListBox.
`MultiListBox(java.lang.Object[] items)` Constructs a MultiListBox with the given items.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`cbddOnPopup()` Called by ComboBoxDropDown when its being popped.
`protected void`	`cbddOnUnpop()` Called by ComboBoxDropDown when its being unpopped.
`void`	`clear()` Clears this control, selecting index clearValueInt.
`protected void`	`drawItems(Graphics g, int dx, int dy, int greatestVisibleItemIndex)`
`protected void`	`drawSelectedItem(Graphics g, int from, int to)` Draw all selected indexes
`protected void`	`endSelection()`
`protected int`	`getCursorColor(int index)`
`java.lang.Object`	`getLastSelectedItem()` Returns the last selected item if you had set order is important, otherwise returns null.
`int`	`getSelectedIndex()` Returns the selected index.
`IntVector`	`getSelectedIndexes()` Return a vector with the indexes which have been selected.
`java.lang.String`	`getText()` Returns the String with the selected item (if single) or a string with the number of selected items.
`protected void`	`handleClick(int index)`
`Control`	`handleGeographicalFocusChangeKeys(KeyEvent ke)` Used by the main event loop to give the currently focused control an opportunity to act directly on the KeyEvent.
`protected void`	`handleSelection(int newSelection)`
`boolean`	`isOrderImportant()` Returns true if you requested that the order is important.
`boolean`	`isSelected(int index)` Returns if given index is selected.
`protected void`	`leftReached()`
`protected void`	`onColorsChanged(boolean colorsChanged)` Called after a setEnabled, setForeColor and setBackColor and when a control has been added to a Container.
`void`	`onEvent(Event e)` Handles the events for this control.
`void`	`postPressedEvent()` Posts a ControlEvent.PRESSED event with this control as target.
`void`	`removeAll()` Empties this ListBox, setting all elements of the array to `null` so they can be garbage collected.
`void`	`setMaxSelections(int max)` Defines the maximum number of items that can be selected.
`void`	`setOrderIsImportant(boolean set)` Call this method if you want to keep track of the order in which the items were selected.
`void`	`setSelectedIndex(int index)` In this MultiListBox, inverts the status of the given index, or clears all if i is -1.
`void`	`setSelectedIndex(int index, boolean set)` Sets or clear an index.

Methods inherited from class totalcross.ui.Container
add, add, add, add, broadcastEvent, fillBackground, findChild, findNearestChild, findNextFocusControl, getBorderRadius, getBorderStyle, getChildren, getChildrenCount, getClientRect, getClientRect, getFirstChild, getInsets, incLastX, incLastY, initUI, isPressed, moveFocusToNextControl, moveFocusToNextEditable, onAddAgain, onRemove, onSwapFinished, paintChildren, resize, resizeHeight, resizeWidth, setBorderRadius, setBorderStyle, setFocusTraversable, setHighlighting, setInsets, setPressColor, setPressed, swapToTopmostWindow

Methods inherited from class totalcross.ui.Control
_onEvent, addEnabledStateListener, addFocusListener, addFontChangeHandler, addGridListener, addHandler, addHighlightListener, addKeyListener, addListContainerListener, addMouseListener, addMultiTouchListener, addPenListener, addPressListener, addPushNotificationListener, addSizeChangeHandler, addTimer, addTimer, addTimerListener, addValueChangeHandler, addWindowListener, bringToFront, changeHighlighted, contains, drawTranslucentBackground, getAbsoluteRect, getBackColor, getDoEffect, getEventListeners, getFont, getForeColor, getGap, getGraphics, getHeight, getNext, getParent, getParentWindow, getPos, getPressedEvent, getPrev, getRect, getSize, getTextShadowColor, getWidth, getX, getX2, getY, getY2, hadParentScrolled, hasFocus, internalSetEnabled, intXYWH, isActionEvent, isChildOf, isDisplayed, isEnabled, isFloating, isInsideOrNear, isObscured, isTopMost, isVisible, isVisibleAndInside, onFontChanged, onWindowPaintFinished, post, postEvent, releaseScreenShot, removeEnabledStateListener, removeFocusListener, removeGridListener, removeHandler, removeHighlightListener, removeKeyListener, removeListContainerListener, removeMouseListener, removeMultiTouchListener, removePenListener, removePressListener, removePushNotificationListener, removeTimer, removeTimerListener, removeWindowListener, repaint, repaintNow, reposition, reposition, repositionChildren, requestFocus, resetSetPositions, resetStyle, safeRepaintNow, safeUpdateScreen, sendToBack, setBackColor, setBackForeColors, setDoEffect, setFloating, setFocusLess, setFont, setForeColor, setNinePatch, setNinePatch, setRect, setRect, setRect, setRect, setSet, setTextShadowColor, setTranslucent, setVisible, showTip, takeInitialScreenShot, takeScreenShot, translateFromOrigin, uiStyleChanged, updateScreen, updateTemporary, willOpenKeyboard

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - NO_OLD_SELECTION
```
protected static final int NO_OLD_SELECTION
```
    See Also:
    
    Constant Field Values
  - maxSelections
```
protected int maxSelections
```
  - oldSelection
```
protected int oldSelection
```
  - selectedIndexes
```
protected IntHashtable selectedIndexes
```
  - order
```
protected IntVector order
```
  - 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)
```
    In this MultiListBox, inverts the status of the given index, or clears all if i is -1.
    
    Overrides:
    
    setSelectedIndex in class ListBox
    
    See Also:
    
    setSelectedIndex(int, boolean)
  - leftReached
```
protected void leftReached()
```
    Overrides:
    
    leftReached 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
  - endSelection
```
protected void endSelection()
```
    Overrides:
    
    endSelection in class ListBox
  - 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
  - onEvent
```
public void onEvent(Event e)
```
    Description copied from class: ListBox
    
    Handles the events for this control.
    
    Overrides:
    
    onEvent in class ListBox
    
    Parameters:
    
    e - the event to process
    
    See Also:
    
    Event, KeyEvent, PenEvent
  - 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

Class MultiListBox

Nested Class Summary

Nested classes/interfaces inherited from class totalcross.ui.ListBox

Nested classes/interfaces inherited from class totalcross.ui.Control

Field Summary

Fields inherited from class totalcross.ui.ListBox

Fields inherited from class totalcross.ui.Container

Fields inherited from class totalcross.ui.Control

Constructor Summary

Method Summary

Methods inherited from class totalcross.ui.ListBox

Methods inherited from class totalcross.ui.Container

Methods inherited from class totalcross.ui.Control

Methods inherited from class java.lang.Object

Field Detail

NO_OLD_SELECTION

maxSelections

oldSelection

selectedIndexes

order

changed

clearValues

showOrderInTip

unselectFirstWhenMaxIsReached

itemsText

localItemsText

tipDelay

Constructor Detail

MultiListBox

MultiListBox

Method Detail

setOrderIsImportant

isOrderImportant

getSelectedIndex

getLastSelectedItem

setMaxSelections

getSelectedIndexes

isSelected

removeAll

onColorsChanged

drawSelectedItem

drawItems

getCursorColor

setSelectedIndex

leftReached

setSelectedIndex

handleSelection

cbddOnPopup

cbddOnUnpop

postPressedEvent

endSelection

handleClick

getText

onEvent

handleGeographicalFocusChangeKeys

clear