public class List<T>

ImplementsActionSource, Animation, Editable, StyleListener

Known subtypesRSSReader, ComboBox, MultiList

A set of elements that is rendered using a com.codename1.ui.list.ListCellRenderer and are extracted via the com.codename1.ui.list.ListModel, notice that we strongly discourage usage of lists.

A list can represent many UI concepts ranging from a carousel to a “todo” checklist, this is made possible thanks to extensive use of Swing’s style of MVC. Specifically a list component is relatively simple, it invokes the model in order to extract the displayed/selected information and shows it to the user by invoking the cell renderer.

The list class itself is completely decoupled from everything, thus it allows us to extract its content from any source (e.g. network, storage etc.) and display the information in any form (e.g. checkboxed elemenents, icons etc.).

Important

List is a pretty complex class to use so we generally recommend developers use com.codename1.ui.Container, com.codename1.components.InfiniteScrollAdapter or com.codename1.ui.InfiniteContainer coupled with widgets such as com.codename1.components.MultiButton. Arranging those in a com.codename1.ui.layouts.BoxLayout on the com.codename1.ui.layouts.BoxLayout#Y_AXIS can produce the functionality of the List with better performance and far simpler code!

Another simpler alternative although not as attractive is the com.codename1.ui.list.MultiList class that removes a lot of the com.codename1.ui.list.ListCellRenderer related complexities inherent in building a list.

Sample Usage

The sample below uses the com.codename1.ui.list.GenericListCellRenderer class instead of the com.codename1.ui.list.DefaultListCellRenderer. We generally recommend using the builtin classes as the renderer is probably the greatest source of pitfalls in Lists.

public void showForm() {
    com.codename1.ui.List list = new com.codename1.ui.List(createGenericListCellRendererModelData());
    list.setRenderer(new GenericListCellRenderer(createGenericRendererContainer(), createGenericRendererContainer()));
    Form hi = new Form("GenericListCellRenderer", new BorderLayout());
    hi.add(BorderLayout.CENTER, list);
    hi.show();
}

private Container createGenericRendererContainer() {
    Label name = new Label();
    name.setFocusable(true);
    name.setName("Name");
    Label surname = new Label();
    surname.setFocusable(true);
    surname.setName("Surname");
    CheckBox selected = new CheckBox();
    selected.setName("Selected");
    selected.setFocusable(true);
    Container c = BorderLayout.center(name).
            add(BorderLayout.SOUTH, surname).
            add(BorderLayout.WEST, selected);
    c.setUIID("ListRenderer");
    return c;
}

private Object[] createGenericListCellRendererModelData() {
    Map[] data = new HashMap[5];
    data[0] = new HashMap<>();
    data[0].put("Name", "Shai");
    data[0].put("Surname", "Almog");
    data[0].put("Selected", Boolean.TRUE);
    data[1] = new HashMap<>();
    data[1].put("Name", "Chen");
    data[1].put("Surname", "Fishbein");
    data[1].put("Selected", Boolean.TRUE);
    data[2] = new HashMap<>();
    data[2].put("Name", "Ofir");
    data[2].put("Surname", "Leitner");
    data[3] = new HashMap<>();
    data[3].put("Name", "Yaniv");
    data[3].put("Surname", "Vakarat");
    data[4] = new HashMap<>();
    data[4].put("Name", "Meirav");
    data[4].put("Surname", "Nachmanovitch");
    return data;
}

Fields

`public static final int FIXED_NONE = 0`	Indicates the list isn’t fixed and that selection is movable
`public static final int FIXED_NONE_CYCLIC = 1`	Indicates that the list is not fixed in place but cycles its elements
`public static final int FIXED_NONE_ONE_ELEMENT_MARGIN_FROM_EDGE = 2`	Indicates the list selection will only reach the edge when there are no more elements in the list.
`public static final int FIXED_LEAD = 10`	Indicates the list selection is fixed into place at the top of the list or at the left of the list
`public static final int FIXED_TRAIL = 11`	Indicates the list selection is fixed into place at the bottom of the list or at the right of the list
`public static final int FIXED_CENTER = 12`	Indicates the list selection is fixed into place at the center of the list
`public static final int VERTICAL = 0`	Indicates the list orientation is VERTICAL
`public static final int HORIZONTAL = 1`	Indicates the list orientation is HORIZONTAL

Constructors

`public List(Vector items)`	Creates a new instance of List
`public List(T... items)`	Creates a new instance of List
`public List()`	Creates a new instance of List with an empty default model
`public List(ListModel model)`	Creates a new instance of List with the given model

Methods

`public static boolean isDefaultIgnoreFocusComponentWhenUnfocused()`	Indicates whether the list should not paint the focus component if the list itself has no focus.
`public static void setDefaultIgnoreFocusComponentWhenUnfocused(boolean aDefaultIgnoreFocusComponentWhenUnfocused)`	Indicates whether the list should not paint the focus component if the list itself has no focus.
`public static boolean isDefaultFireOnClick()`	Default value for the fire on click behavior
`public static void setDefaultFireOnClick(boolean aDefaultFireOnClick)`	Default value for the fire on click behavior
`protected void initLaf(UIManager uim)`	This method initializes the Component defaults constants
`protected void laidOut()`	This is a callback method to inform the Component when it’s been laidout on the parent Container
`protected void modelChanged(int status, int index)`	Callback to allow subclasses to react to a change in the model
`protected void listSelectionChanged(int oldSelected, int newSelected)`	Callback to allow subclasses to react to a selection change in the model
`public int getSideGap()`	Returns the gap to be left for the side scrollbar on the Y axis.
`public boolean isScrollableY()`	Indicates whether the component should/could scroll on the Y axis
`public boolean isScrollableX()`	Indicates whether the component should/could scroll on the X axis
`public int getMaxElementHeight()`	Maximum number of elements shown in a list, this member is used to calculate the list preferred size.
`public void setMaxElementHeight(int maxElementHeight)`	Maximum number of elements shown in a list, this member is used to calculate the list preferred size.
`public int getMinElementHeight()`	Minimum number of elements shown in a list, this member is used to calculate the list preferred size.
`public void setMinElementHeight(int minElementHeight)`	Minimum number of elements shown in a list, this member is used to calculate the list preferred size.
`public int size()`	Returns the number of elements in the list, shorthand for getModel().getSize()
`public` `Rectangle getAccessibilityItemBounds(int index, Rectangle out)`	Returns the bounds of a renderer-backed row for the portable virtual accessibility tree.
`public` `String getAccessibilityItemText(int index)`	Returns the accessible name produced by the list renderer for an item.
`public int[] getAccessibilityVisibleItemIndices()`	Returns the model indices that should currently be materialized as virtual accessibility children.
`public int getCurrentSelected()`	Returns the visual selection during a drag operation, otherwise equivalent to model.getSelectedIndex
`public int getSelectedIndex()`	Returns the current selected offset in the list
`public void setSelectedIndex(int index)`	Sets the current selected offset in the list, by default this implementation will scroll the list to the selection if the selection is outside of the screen
`protected` `Rectangle getVisibleBounds()`	Returns the component bounds for scrolling which might differ from the getBounds for large components e.g. list.
`protected int getDragRegionStatus(int x, int y)`	Indicates if the section within the X/Y area is a “drag region” where we expect people to drag or press in which case we can instantly start dragging making perceived performance faster.
`public void setSelectedIndex(int index, boolean scrollToSelection)`	Sets the current selected offset in the list
`public T getSelectedItem()`	Returns the current selected item in the list or null for no selection
`public void setSelectedItem(T item)`	Sets the current selected item in the list
`public` `ListModel<T> getModel()`	Returns the model underlying the list
`public void setModel(ListModel model)`	Replaces/sets the model underlying the list
`public void setShouldCalcPreferredSize(boolean shouldCalcPreferredSize)`	Indicates the values within the component have changed and preferred size should be recalculated
`public boolean isNumericKeyActions()`	Indicate whether pressing the number keys should trigger an action
`public void setNumericKeyActions(boolean numericKeyActions)`	Indicate whether pressing the number keys should trigger an action
`public boolean isCommandList()`	Indicates that the list should be treated as a list of commands, if the user “clicks” a command from the list its action performed method is invoked.
`public void setCommandList(boolean commandList)`	Indicates that the list should be treated as a list of commands, if the user “clicks” a command from the list its action performed method is invoked.
`public boolean isIgnoreFocusComponentWhenUnfocused()`	Indicates whether the list should not paint the focus component if the list itself has no focus.
`public void setIgnoreFocusComponentWhenUnfocused(boolean ignoreFocusComponentWhenUnfocused)`	Indicates whether the list should not paint the focus component if the list itself has no focus.
`public boolean isMutableRendererBackgrounds()`	Indicates that the background of a cell renderer might mutate between one entry and the next, it is recommended that this flag remains false for performance reasons.
`public void setMutableRendererBackgrounds(boolean mutableRendererBackgrounds)`	Indicates that the background of a cell renderer might mutate between one entry and the next, it is recommended that this flag remains false for performance reasons.
`public int getListSizeCalculationSampleCount()`	Indicates the number of elements the list should check to determine the element sizes.
`public void setListSizeCalculationSampleCount(int listSizeCalculationSampleCount)`	Indicates the number of elements the list should check to determine the element sizes.
`public boolean isLongPointerPressActionEnabled()`	Enable/disable list action on long pointer press event
`public void setLongPointerPressActionEnabled(boolean longPointerPressAction)`	Enable/disable list action on long pointer press event
`public void setListCellRenderer(ListCellRenderer renderer)`	Deprecated Sets the renderer which is used to draw list elements
`public final` `ListCellRenderer getRenderer()`	Returns the renderer which is used to draw list elements
`public final void setRenderer(ListCellRenderer renderer)`	Sets the renderer which is used to draw list elements
`public int getOrientation()`	Returns the list orientation
`public void setOrientation(int orientation)`	Sets the list orientation HORIZONTAL or VERTICAL
`public void refreshTheme(boolean merge)`	Makes sure the component is up to date with the current theme, ONLY INVOKE THIS METHOD IF YOU CHANGED THE THEME!
`public void scrollRectToVisible(Rectangle rect)`	Makes sure the selected index is visible if it is not in the current view rect the list will scroll so it fits within
`public void setHandlesInput(boolean b)`	Prevents key events from being grabbed for focus traversal.
`protected void fireClicked()`	When working in 3 softbutton mode “fire” key (center softbutton) is sent to this method in order to allow 3 button devices to work properly.
`protected boolean isSelectableInteraction()`	This method allows a component to indicate that it is interested in an “implicit” select command to appear in the “fire” button when 3 softbuttons are defined in a device.
`public void keyReleased(int keyCode)`	If this Component is focused, the key released event will call this method
`public void keyPressed(int keyCode)`	If this Component is focused, the key pressed event will call this method
`public void paint(Graphics g)`	This method paints the Component on the screen, it should be overriden by subclasses to perform custom drawing or invoke the UI API’s to let the PLAF perform the rendering.
`protected boolean shouldRenderSelection()`	Allows subclasses to override the selection rendering for the component, specifically the spinner in some themes
`public void addSelectionListener(SelectionListener l)`	Invoked to indicate interest in future selection events
`public void removeSelectionListener(SelectionListener l)`	Invoked to indicate no further interest in future selection events
`public void addActionListener(ActionListener l)`	Allows binding a listener to user selection actions
`public` `Vector getActionListeners()`	Deprecated This method allows extracting the action listeners from the current list
`public` `Collection getListeners()`	This method allows extracting the action listeners from the current list
`public void removeActionListener(ActionListener l)`	Allows binding a listener to user selection actions
`protected void fireActionEvent()`	Fires an action event for the current event source.
`protected void fireActionEvent(ActionEvent a)`	Triggers the event to the listeners
`public void setInputOnFocus(boolean inputOnFocus)`	A list can start handling input implicitly upon gaining focus, this can make for a more intuitive UI when no other focus elements exist or when their use case is infrequent.
`public void setPaintFocusBehindList(boolean paintFocusBehindList)`	This method determines if the animated focus is drawn on top of the List or behind the List when moving.
`public int getItemGap()`	Returns the gap between items
`public void setItemGap(int itemGap)`	Set the gap between items
`public T getRenderingPrototype()`	See set rendering prototype
`public void setRenderingPrototype(T renderingPrototype)`	The rendering prototype is optionally used in calculating the size of the List and is recommended for performance reasons.
`public void longPointerPress(int x, int y)`	If this Component is focused this method is invoked when the user presses and holds the pointer on the Component
`public void pointerPressed(int x, int y)`	If this Component is focused, the pointer pressed event will call this method
`public void pointerHover(int[] x, int[] y)`	Invoked for devices where the pointer can hover without actually clicking the display.
`public void pointerDragged(int x, int y)`	If this Component is focused, the pointer dragged event will call this method
`public` `Rectangle getSelectedRect()`	Returns the component bounds with absolute screen coordinates, for components that include an internal selection behavior and are not containers (currently only List) this method allows returning the position of the selection itself which i…
`public void setFireOnClick(boolean fireOnClick)`	This method determines if the List fires the action event when the pointer was clicked on one of the items, or only if the item was the selected item By default the value is true, this setting is only relevant for none fixed Lists
`public void pointerHoverReleased(int[] x, int[] y)`	Invoked for devices where the pointer can hover without actually clicking the display.
`public void pointerReleased(int x, int y)`	If this Component is focused, the pointer released event will call this method
`protected` `Dimension calcPreferredSize()`	Calculates the preferred size based on component content.
`public void addItem(T item)`	Allows adding an element to a list if the underlying model supports this, notice that it is an optional operation and if the model does not support it (default list model does) then this operation may failed.
`public int getFixedSelection()`	Indicates whether selection is fixable to place in which case all the elements in the list move and selection stays in place.
`public void setFixedSelection(int fixedSelection)`	Indicates whether selection is fixable to place in which case all the elements in the list move and selection stays in place.
`public boolean animate()`	Allows the animation to reduce “repaint” calls when it returns false.
`protected boolean isTactileTouch(int x, int y)`	Elaborate components might not provide tactile feedback for all their areas (e.g. Lists) this method defaults to returning the value of isTactileTouch
`public void setScrollToSelected(boolean scrollToSelected)`	This flag indicates to the List if the List should scroll to the selected element when it’s been initialized.
`protected int getGridPosY()`	This method should be implemented correctly by subclasses to make snap to grid functionality work as expected.
`protected int getGridPosX()`	This method should be implemented correctly by subclasses to make snap to grid functionality work as expected.
`protected` `String paramString()`	Returns a string representing the state of this component.
`public` `String getHint()`	Returns the hint text
`public void setHint(String hint)`	Sets the TextArea hint text, the hint text is displayed on the TextArea When there is no text in the TextArea
`public` `Image getHintIcon()`	Returns the hint icon
`public void setHintIcon(Image icon)`	Sets the TextArea hint icon, the hint is displayed on the TextArea When there is no text in the TextArea
`public void setHint(String hint, Image icon)`	Sets the TextArea hint text and Icon, the hint text and icon are displayed on the TextArea when there is no text in the TextArea

Inherited fields

Inherited methods

From Component

setSameSize, isSetCursorSupported, parsePreferredSize, getDefaultDragTransparency, setDefaultDragTransparency, getEditingDelegate, setEditingDelegate, getCursor, setCursor, showNativeOverlay, hideNativeOverlay, updateNativeOverlay, getNativeOverlay, getAllStyles, getSameWidth, setSameWidth, getSameHeight, setSameHeight, getUIManager, getX, setX, getOuterX, getInnerX, getY, setY, getOuterY, getInnerY, isVisible, setVisible, getClientProperty, stripMarginAndPadding, clearClientProperties, putClientProperty, getDirtyRegion, setDirtyRegion, isOpaque, setOpaque, getWidth, setWidth, getOuterWidth, getInnerWidth, getHeight, setHeight, getOuterHeight, getInnerHeight, isDragRegion, getBaseline, getBaselineResizeBehavior, getPreferredSizeStr, setPreferredSizeStr, getPreferredSize, setPreferredSize, getScrollDimension, calcScrollSize, setScrollSize, getPreferredW, setPreferredW, getPreferredH, setPreferredH, getOuterPreferredH, getInnerPreferredH, getOuterPreferredW, getInnerPreferredW, setSize, getUIID, setUIID, setUIIDFinal, setUIID, getInlineAllStyles, setInlineAllStyles, getInlineSelectedStyles, setInlineSelectedStyles, getInlineUnselectedStyles, setInlineUnselectedStyles, getInlineDisabledStyles, setInlineDisabledStyles, getInlinePressedStyles, setInlinePressedStyles, remove, getParent, getOwner, setOwner, isOwnedBy, containsOrOwns, addFocusListener, removeFocusListener, addScrollListener, removeScrollListener, getSelectCommandText, setSelectCommandText, getLabelForComponent, setLabelForComponent, focusGained, focusLost, paintBackgrounds, paintShadows, getAbsoluteX, getAbsoluteY, isInClippingRegion, paintIntersectingComponentsAbove, paintScrollbars, paintScrollbarX, getScrollOpacity, paintScrollbarY, paintComponent, paintComponent, getBorder, getScrollable, paintBackground, isScrollable, getScrollX, setScrollX, getScrollY, setScrollY, onScrollX, onScrollY, getDraggedx, getDraggedy, getBottomGap, contains, visibleBoundsContains, hasFixedPreferredSize, getBounds, getBounds, getVisibleBounds, isFocusable, setFocusable, onSetFocusable, resetFocusable, getTabIndex, setTabIndex, getPreferredTabIndex, setPreferredTabIndex, isTraversable, setTraversable, handlesInput, consumesRawTextInput, hasFocus, setFocus, getComponentForm, getTopLevelContainer, repaint, repaint, longKeyPress, keyRepeated, registerForAnimation, deregisterFromAnimation, getAnimationManager, getScrollAnimationSpeed, setScrollAnimationSpeed, isBlockLead, setBlockLead, isIgnorePointerEvents, setIgnorePointerEvents, isRippleEffect, setRippleEffect, getInlineStylesTheme, setInlineStylesTheme, shouldRenderComponentSelection, isHideInLandscape, setHideInLandscape, createStyleAnimation, isSmoothScrolling, setSmoothScrolling, stopScrollMomentum, pointerHoverPressed, pinch, pinchReleased, pinch, rotation, isPinchBlocksDragAndDrop, setPinchBlocksDragAndDrop, pointerDragged, getDragImage, getDragTransparency, setDragTransparency, toImage, dragInitiated, drawDraggedImage, draggingOver, dragEnter, dragExit, drop, addPullToRefresh, setPullToRefresh, respondsToPointerEvents, isStickyDrag, pointerPressed, isDragAndDropOperation, pointerReleased, setVerticalScrollBounds, setHorizontalScrollBounds, isVScrollThumbGrabbed, isHScrollThumbGrabbed, isVScrollThumbHover, isHScrollThumbHover, isTensileDragEnabled, setTensileDragEnabled, getTextSelectionSupport, addDropListener, removeDropListener, addDragOverListener, removeDragOverListener, isNativeDragSource, setNativeDragSource, getNativeDragOperation, setNativeDragOperation, createNativeDragOperation, isNativeDropTarget, setNativeDropTarget, getAcceptedDropMimeTypes, setAcceptedDropMimeTypes, getAcceptedDropActions, setAcceptedDropActions, canAcceptNativeDrop, nativeDragEnter, nativeDragOver, nativeDragExit, nativeDrop, addNativeDropListener, removeNativeDropListener, addNativeDragOverListener, removeNativeDragOverListener, dragFinished, addDragFinishedListener, addStateChangeListener, removeStateChangeListener, addPointerPressedListener, addLongPressListener, addContextMenuListener, removeContextMenuListener, addMouseWheelListener, removeMouseWheelListener, addStylusListener, removeStylusListener, mouseWheel, paintRippleOverlay, removePointerPressedListener, removeLongPressListener, removeDragFinishedListener, addPointerReleasedListener, removePointerReleasedListener, addPointerDraggedListener, removePointerDraggedListener, getDragSpeed, getStyle, getPressedStyle, setPressedStyle, initUnselectedStyle, initPressedStyle, initDisabledStyle, initSelectedStyle, getUnselectedStyle, setUnselectedStyle, getSelectedStyle, setSelectedStyle, getDisabledStyle, setDisabledStyle, installDefaultPainter, requestFocus, toString, refreshTheme, refreshTheme, isDragActivated, scrollRectToVisible, scrollRectToVisible, paintBorder, paintBorderBackground, isCellRenderer, setCellRenderer, isScrollVisible, setScrollVisible, setIsScrollVisible, startEditingAsync, stopEditing, isEditing, isEditable, deinitialize, initComponent, isInitialized, setInitialized, styleChanged, getNextFocusDown, setNextFocusDown, getNextFocusUp, setNextFocusUp, getNextFocusLeft, setNextFocusLeft, getNextFocusRight, setNextFocusRight, isEnabled, setEnabled, getName, setName, initCustomStyle, deinitializeCustomStyle, isRTL, setRTL, isTactileTouch, setTactileTouch, getPropertyNames, getPropertyTypes, getPropertyTypeNames, getPropertyValue, setPropertyValue, paintLockRelease, paintLock, isSnapToGrid, setSnapToGrid, shouldBlockSideSwipe, shouldBlockSideSwipeLeft, shouldBlockSideSwipeRight, blocksSideSwipe, isFlatten, setFlatten, getTensileLength, setTensileLength, isGrabsPointerEvents, setGrabsPointerEvents, getScrollOpacityChangeSpeed, setScrollOpacityChangeSpeed, growShrink, isAlwaysTensile, setAlwaysTensile, isDraggable, setDraggable, isDropTarget, setDropTarget, isChildOf, isHideInPortrait, setHideInPortrait, cancelRepaints, getBindablePropertyNames, getBindablePropertyTypes, bindProperty, unbindProperty, getBoundPropertyValue, setBoundPropertyValue, getCloudBoundProperty, setCloudBoundProperty, getCloudDestinationProperty, setCloudDestinationProperty, getComponentState, setComponentState, setHidden, isHidden, setHidden, isHidden, announceForAccessibility, getAccessibilityText, setAccessibilityText, getSemantics, getAccessibilityNode, accessibilityChanged, accessibilityChanged, getTooltip, setTooltip

From Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait, clone

Field details

FIXED_NONE

public static final int FIXED_NONE = 0

Indicates the list isn’t fixed and that selection is movable

FIXED_NONE_CYCLIC

public static final int FIXED_NONE_CYCLIC = 1

Indicates that the list is not fixed in place but cycles its elements

FIXED_NONE_ONE_ELEMENT_MARGIN_FROM_EDGE

public static final int FIXED_NONE_ONE_ELEMENT_MARGIN_FROM_EDGE = 2

Indicates the list selection will only reach the edge when there are no more elements in the list.

FIXED_LEAD

public static final int FIXED_LEAD = 10

Indicates the list selection is fixed into place at the top of the list or at the left of the list

FIXED_TRAIL

public static final int FIXED_TRAIL = 11

Indicates the list selection is fixed into place at the bottom of the list or at the right of the list

FIXED_CENTER

public static final int FIXED_CENTER = 12

Indicates the list selection is fixed into place at the center of the list

VERTICAL

public static final int VERTICAL = 0

Indicates the list orientation is VERTICAL

HORIZONTAL

public static final int HORIZONTAL = 1

Indicates the list orientation is HORIZONTAL

Constructor details

List

public List(Vector items)

Creates a new instance of List

Parameters

items Vector: set of items placed into the list model

List

public List(T... items)

Creates a new instance of List

Parameters

items T...: set of items placed into the list model

List

public List()

Creates a new instance of List with an empty default model

List

public List(ListModel model)

Creates a new instance of List with the given model

Parameters

model ListModel: the model instance

Method details

isDefaultIgnoreFocusComponentWhenUnfocused

public static boolean isDefaultIgnoreFocusComponentWhenUnfocused()

Indicates whether the list should not paint the focus component if the list itself has no focus.

Returns

the defaultIgnoreFocusComponentWhenUnfocused

setDefaultIgnoreFocusComponentWhenUnfocused

public static void setDefaultIgnoreFocusComponentWhenUnfocused(boolean aDefaultIgnoreFocusComponentWhenUnfocused)

Indicates whether the list should not paint the focus component if the list itself has no focus.

Parameters

aDefaultIgnoreFocusComponentWhenUnfocused boolean: the defaultIgnoreFocusComponentWhenUnfocused to set

isDefaultFireOnClick

public static boolean isDefaultFireOnClick()

Default value for the fire on click behavior

Returns

the defaultFireOnClick

setDefaultFireOnClick

public static void setDefaultFireOnClick(boolean aDefaultFireOnClick)

Default value for the fire on click behavior

Parameters

aDefaultFireOnClick boolean: the defaultFireOnClick to set

initLaf

protected void initLaf(UIManager uim)

This method initializes the Component defaults constants

laidOut

protected void laidOut()

This is a callback method to inform the Component when it’s been laidout on the parent Container

modelChanged

protected void modelChanged(int status, int index)

Callback to allow subclasses to react to a change in the model

Parameters

status int: the type data change; REMOVED, ADDED or CHANGED
index int: item index in a list model

listSelectionChanged

protected void listSelectionChanged(int oldSelected, int newSelected)

Callback to allow subclasses to react to a selection change in the model

Parameters

oldSelected int: the old selection value
newSelected int: the new selection value

getSideGap

public int getSideGap()

Returns the gap to be left for the side scrollbar on the Y axis. This method is used by layout managers to determine the room they should leave for the scrollbar. (note: side scrollbar rather than left scrollbar is used for a future version that would support bidi).

Returns

the gap to be left for the side scrollbar on the Y axis

isScrollableY

public boolean isScrollableY()

Indicates whether the component should/could scroll on the Y axis

Returns

whether the component is scrollable on the X axis

isScrollableX

public boolean isScrollableX()

Indicates whether the component should/could scroll on the X axis

Returns

whether the component is scrollable on the X axis

getMaxElementHeight

public int getMaxElementHeight()

Maximum number of elements shown in a list, this member is used to calculate the list preferred size. If the number of elements in the model is larger than this then this value is used in the calculations.

Returns

the maximum number of elements

setMaxElementHeight

public void setMaxElementHeight(int maxElementHeight)

Parameters

maxElementHeight int: the maximum number of elements

getMinElementHeight

public int getMinElementHeight()

Minimum number of elements shown in a list, this member is used to calculate the list preferred size. If the number of elements in the model is smaller than this then this value is used in the calculations.

Returns

the minimum number of elements

setMinElementHeight

public void setMinElementHeight(int minElementHeight)

Parameters

minElementHeight int: the minimum number of elements

size

public int size()

Returns the number of elements in the list, shorthand for getModel().getSize()

Returns

the number of elements in the list

getAccessibilityItemBounds

public Rectangle getAccessibilityItemBounds(int index, Rectangle out)

Returns the bounds of a renderer-backed row for the portable virtual accessibility tree. Bounds are relative to this list.

getAccessibilityItemText

public String getAccessibilityItemText(int index)

Returns the accessible name produced by the list renderer for an item.

getAccessibilityVisibleItemIndices

public int[] getAccessibilityVisibleItemIndices()

Returns the model indices that should currently be materialized as virtual accessibility children. The result contains the visible window, a small one-item navigation buffer on each side, and the selected item. It is intentionally bounded by the viewport so building a semantic tree for a large renderer-backed list doesn’t instantiate every row renderer.

getCurrentSelected

public int getCurrentSelected()

Returns the visual selection during a drag operation, otherwise equivalent to model.getSelectedIndex

Returns

visual selection

getSelectedIndex

public int getSelectedIndex()

Returns the current selected offset in the list

Returns

the current selected offset in the list

setSelectedIndex

public void setSelectedIndex(int index)

Sets the current selected offset in the list, by default this implementation will scroll the list to the selection if the selection is outside of the screen

Parameters

index int: the current selected offset in the list

getVisibleBounds

protected Rectangle getVisibleBounds()

Returns the component bounds for scrolling which might differ from the getBounds for large components e.g. list.

Returns

the component bounds

getDragRegionStatus

protected int getDragRegionStatus(int x, int y)

Indicates if the section within the X/Y area is a “drag region” where we expect people to drag or press in which case we can instantly start dragging making perceived performance faster. This is invoked by the implementation code to optimize drag start behavior

Parameters

x int: x location for the touch
y int: y location for the touch

Returns

one of the DRAG_REGION_* values

setSelectedIndex

public void setSelectedIndex(int index, boolean scrollToSelection)

Sets the current selected offset in the list

Parameters

index int: the current selected offset in the list
scrollToSelection boolean: indicates whether scrolling to selection should occur if the selection is outside of view

getSelectedItem

public T getSelectedItem()

Returns the current selected item in the list or null for no selection

Returns

the current selected item in the list

setSelectedItem

public void setSelectedItem(T item)

Sets the current selected item in the list

Parameters

item T: the current selected item in the list

getModel

public ListModel<T> getModel()

Returns the model underlying the list

Returns

the model underlying the list

setModel

public void setModel(ListModel model)

Replaces/sets the model underlying the list

Parameters

model ListModel: the new model underlying the list

setShouldCalcPreferredSize

public void setShouldCalcPreferredSize(boolean shouldCalcPreferredSize)

Indicates the values within the component have changed and preferred size should be recalculated

Parameters

shouldCalcPreferredSize boolean: indicate whether this component need to recalculate his preferred size

isNumericKeyActions

public boolean isNumericKeyActions()

Indicate whether pressing the number keys should trigger an action

Returns

true if pressing the number keys should trigger an action

setNumericKeyActions

public void setNumericKeyActions(boolean numericKeyActions)

Indicate whether pressing the number keys should trigger an action

Parameters

numericKeyActions boolean: true to trigger an action on number keys

isCommandList

public boolean isCommandList()

Indicates that the list should be treated as a list of commands, if the user “clicks” a command from the list its action performed method is invoked.

Returns

true if the list is treated as a command list

setCommandList

public void setCommandList(boolean commandList)

Indicates that the list should be treated as a list of commands, if the user “clicks” a command from the list its action performed method is invoked.

Parameters

commandList boolean: true for the list to be treated as a command list

isIgnoreFocusComponentWhenUnfocused

public boolean isIgnoreFocusComponentWhenUnfocused()

Indicates whether the list should not paint the focus component if the list itself has no focus.

Returns

the ignoreFocusComponentWhenUnfocused

setIgnoreFocusComponentWhenUnfocused

public void setIgnoreFocusComponentWhenUnfocused(boolean ignoreFocusComponentWhenUnfocused)

Indicates whether the list should not paint the focus component if the list itself has no focus.

Parameters

ignoreFocusComponentWhenUnfocused boolean: true to ignore the focus component false otherwise

isMutableRendererBackgrounds

public boolean isMutableRendererBackgrounds()

Indicates that the background of a cell renderer might mutate between one entry and the next, it is recommended that this flag remains false for performance reasons.

Returns

the value of the flag

setMutableRendererBackgrounds

public void setMutableRendererBackgrounds(boolean mutableRendererBackgrounds)

Indicates that the background of a cell renderer might mutate between one entry and the next, it is recommended that this flag remains false for performance reasons.

Parameters

mutableRendererBackgrounds boolean: the new value for the flag

getListSizeCalculationSampleCount

public int getListSizeCalculationSampleCount()

Indicates the number of elements the list should check to determine the element sizes. This is ignored when a rendering prototype is present.

Returns

the listSizeCalculationSampleCount

setListSizeCalculationSampleCount

public void setListSizeCalculationSampleCount(int listSizeCalculationSampleCount)

Indicates the number of elements the list should check to determine the element sizes. This is ignored when a rendering prototype is present.

Parameters

listSizeCalculationSampleCount int: the listSizeCalculationSampleCount to set

isLongPointerPressActionEnabled

public boolean isLongPointerPressActionEnabled()

Enable/disable list action on long pointer press event

Returns

the longPointerPressAction

setLongPointerPressActionEnabled

public void setLongPointerPressActionEnabled(boolean longPointerPressAction)

Enable/disable list action on long pointer press event

Parameters

longPointerPressAction boolean: the longPointerPressAction to set

setListCellRenderer

public void setListCellRenderer(ListCellRenderer renderer)

Deprecated. use setRenderer instead, this method was deprecated to confirm better to JavaBean convention of having the getter/setter with the same name

Sets the renderer which is used to draw list elements

Parameters

renderer ListCellRenderer: cell renderer instance

getRenderer

public final ListCellRenderer getRenderer()

Returns the renderer which is used to draw list elements

Returns

the renderer which is used to draw list elements

setRenderer

public final void setRenderer(ListCellRenderer renderer)

Sets the renderer which is used to draw list elements

Parameters

renderer ListCellRenderer: cell renderer instance

getOrientation

public int getOrientation()

Returns the list orientation

Returns

the list orientation HORIZONTAL or VERTICAL

setOrientation

public void setOrientation(int orientation)

Sets the list orientation HORIZONTAL or VERTICAL

Parameters

orientation int: the list orientation HORIZONTAL or VERTICAL

refreshTheme

public void refreshTheme(boolean merge)

Makes sure the component is up to date with the current theme, ONLY INVOKE THIS METHOD IF YOU CHANGED THE THEME!

Parameters

merge boolean: indicates if the current styles should be merged with the new styles

scrollRectToVisible

public void scrollRectToVisible(Rectangle rect)

Makes sure the selected index is visible if it is not in the current view rect the list will scroll so it fits within

Parameters

rect Rectangle: the rectangle area to scroll to

setHandlesInput

public void setHandlesInput(boolean b)

Prevents key events from being grabbed for focus traversal. E.g. a list component might use the arrow keys for internal navigation so it will switch this flag to true in order to prevent the focus manager from moving to the next component.

Parameters

b boolean: indicates whether key events can be grabbed for focus traversal

fireClicked

protected void fireClicked()

When working in 3 softbutton mode “fire” key (center softbutton) is sent to this method in order to allow 3 button devices to work properly. When overriding this method you should also override isSelectableInteraction to indicate that a command is placed appropriately on top of the fire key for 3 soft button phones.

isSelectableInteraction

protected boolean isSelectableInteraction()

This method allows a component to indicate that it is interested in an “implicit” select command to appear in the “fire” button when 3 softbuttons are defined in a device.

Returns

true if this is a selectable interaction

keyReleased

public void keyReleased(int keyCode)

If this Component is focused, the key released event will call this method

Parameters

keyCode int: the key code value to indicate a physical key.

keyPressed

public void keyPressed(int keyCode)

If this Component is focused, the key pressed event will call this method

Parameters

keyCode int: the key code value to indicate a physical key.

paint

public void paint(Graphics g)

This method paints the Component on the screen, it should be overriden by subclasses to perform custom drawing or invoke the UI API’s to let the PLAF perform the rendering.

Parameters

g Graphics: the component graphics

shouldRenderSelection

protected boolean shouldRenderSelection()

Allows subclasses to override the selection rendering for the component, specifically the spinner in some themes

Returns

true to render the selection, false otherwise.

addSelectionListener

public void addSelectionListener(SelectionListener l)

Invoked to indicate interest in future selection events

Parameters

l SelectionListener: the selection listener to be added

removeSelectionListener

public void removeSelectionListener(SelectionListener l)

Invoked to indicate no further interest in future selection events

Parameters

l SelectionListener: the selection listener to be removed

addActionListener

public void addActionListener(ActionListener l)

Allows binding a listener to user selection actions

Parameters

l ActionListener: the action listener to be added

getActionListeners

public Vector getActionListeners()

Deprecated. use getListeners instead

This method allows extracting the action listeners from the current list

Returns

vector containing the action listeners on the list

getListeners

public Collection getListeners()

This method allows extracting the action listeners from the current list

Returns

Collection containing the action listeners on the list

removeActionListener

public void removeActionListener(ActionListener l)

Allows binding a listener to user selection actions

Parameters

l ActionListener: the action listener to be removed

fireActionEvent

protected void fireActionEvent()

Fires an action event for the current event source.

fireActionEvent

protected void fireActionEvent(ActionEvent a)

Triggers the event to the listeners

Parameters

a ActionEvent: the event to fire

setInputOnFocus

public void setInputOnFocus(boolean inputOnFocus)

A list can start handling input implicitly upon gaining focus, this can make for a more intuitive UI when no other focus elements exist or when their use case is infrequent. However, it might be odd in some cases where the list “steals” focus.

Parameters

inputOnFocus boolean: true is a list can start handling input implicitly upon gaining focus

setPaintFocusBehindList

public void setPaintFocusBehindList(boolean paintFocusBehindList)

This method determines if the animated focus is drawn on top of the List or behind the List when moving.

getItemGap

public int getItemGap()

Returns the gap between items

Returns

the gap between items

setItemGap

public void setItemGap(int itemGap)

Set the gap between items

Parameters

itemGap int: the gap between items

getRenderingPrototype

public T getRenderingPrototype()

See set rendering prototype

Returns

the value of the rendering prototype

setRenderingPrototype

public void setRenderingPrototype(T renderingPrototype)

The rendering prototype is optionally used in calculating the size of the List and is recommended for performance reasons. You should invoke it with an object representing a theoretical value in the list which will be used to calculate the size required for each element in the list.

This allows list size calculations to work across look and feels and allows developers to predetermine size for list elements.

e.g. For a list of Strings which you would like to always be 5 characters wide you can use a prototype “XXXXX” which would use the preferred size of the XXXXX String to determine the size of the list element. E.g. for a list of dates you can use new Date(30, 12, 00) etc..

The example below was designed for com.codename1.ui.list.MultiList but should work for any list. Its goal is to render 2 lines of text with 20 characters and a 5mm square icon:

Map proto = new HashMap<>();
map.put("Line1", "WWWWWWWWWWWWWWWWWWWW");
map.put("Line2", "WWWWWWWWWWWWWWWWWWWW");
int mm5 = Display.getInstance().convertToPixels(5, true);
map.put("icon", Image.create(mm5, mm5));
myMultiList.setRenderingPrototype(map);

Parameters

renderingPrototype T: a value that can be passed to the renderer to indicate the preferred size of a list component.

longPointerPress

public void longPointerPress(int x, int y)

If this Component is focused this method is invoked when the user presses and holds the pointer on the Component

pointerPressed

public void pointerPressed(int x, int y)

If this Component is focused, the pointer pressed event will call this method

Parameters

x int: the pointer x coordinate
y int: the pointer y coordinate

pointerHover

public void pointerHover(int[] x, int[] y)

Invoked for devices where the pointer can hover without actually clicking the display. This is true for PC mouse pointer as well as some devices such as the BB storm.

Parameters

x int[]: the pointer x coordinate
y int[]: the pointer y coordinate

pointerDragged

public void pointerDragged(int x, int y)

If this Component is focused, the pointer dragged event will call this method

Parameters

x int: the pointer x coordinate
y int: the pointer y coordinate

getSelectedRect

public Rectangle getSelectedRect()

Returns the component bounds with absolute screen coordinates, for components that include an internal selection behavior and are not containers (currently only List) this method allows returning the position of the selection itself which is useful for things such as the popup dialog and similar UI’s that need to reference the position of the selection externally

Returns

the bounds of the component with absolute screen coordinates

setFireOnClick

public void setFireOnClick(boolean fireOnClick)

This method determines if the List fires the action event when the pointer was clicked on one of the items, or only if the item was the selected item By default the value is true, this setting is only relevant for none fixed Lists

pointerHoverReleased

public void pointerHoverReleased(int[] x, int[] y)

Invoked for devices where the pointer can hover without actually clicking the display. This is true for PC mouse pointer as well as some devices such as the BB storm.

Parameters

x int[]: the pointer x coordinate
y int[]: the pointer y coordinate

pointerReleased

public void pointerReleased(int x, int y)

If this Component is focused, the pointer released event will call this method

Parameters

x int: the pointer x coordinate
y int: the pointer y coordinate

calcPreferredSize

protected Dimension calcPreferredSize()

Calculates the preferred size based on component content. This method is invoked lazily by getPreferred size.

Returns

the calculated preferred size based on component content

addItem

public void addItem(T item)

Allows adding an element to a list if the underlying model supports this, notice that it is an optional operation and if the model does not support it (default list model does) then this operation may failed.

Parameters

item T: the item to be added to a list model

getFixedSelection

public int getFixedSelection()

Indicates whether selection is fixable to place in which case all the elements in the list move and selection stays in place.

Returns

one of: FIXED_NONE, FIXED_TRAIL, FIXED_LEAD, FIXED_CENTER, FIXED_NONE_CYCLIC

setFixedSelection

public void setFixedSelection(int fixedSelection)

Indicates whether selection is fixable to place in which case all the elements in the list move and selection stays in place.

Parameters

fixedSelection int: one of: FIXED_NONE, FIXED_TRAIL, FIXED_LEAD, FIXED_CENTER, FIXED_NONE_CYCLIC

animate

public boolean animate()

Allows the animation to reduce “repaint” calls when it returns false. It is called once for every frame. Frames are defined by the com.codename1.ui.Display class.

Returns

true if a repaint is desired or false if no repaint is necessary

isTactileTouch

protected boolean isTactileTouch(int x, int y)

Elaborate components might not provide tactile feedback for all their areas (e.g. Lists) this method defaults to returning the value of isTactileTouch

Parameters

x int: the x position
y int: the y position

Returns

True if the device should vibrate

setScrollToSelected

public void setScrollToSelected(boolean scrollToSelected)

This flag indicates to the List if the List should scroll to the selected element when it’s been initialized.

Parameters

scrollToSelected boolean: if true the List scrolls to the selected element when It’s been initialized.

getGridPosY

protected int getGridPosY()

This method should be implemented correctly by subclasses to make snap to grid functionality work as expected. Returns the ideal grid Y position closest to the current Y position.

Returns

a valid Y position in the grid

getGridPosX

protected int getGridPosX()

This method should be implemented correctly by subclasses to make snap to grid functionality work as expected. Returns the ideal grid X position closest to the current X position.

Returns

a valid Y position in the grid

paramString

protected String paramString()

Returns a string representing the state of this component. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Returns

a string representation of this component’s state

getHint

public String getHint()

Returns the hint text

Returns

the hint text or null

setHint

public void setHint(String hint)

Sets the TextArea hint text, the hint text is displayed on the TextArea When there is no text in the TextArea

Parameters

hint String: the hint text to display

getHintIcon

public Image getHintIcon()

Returns the hint icon

Returns

the hint icon

setHintIcon

public void setHintIcon(Image icon)

Sets the TextArea hint icon, the hint is displayed on the TextArea When there is no text in the TextArea

Parameters

icon Image: the icon

setHint

public void setHint(String hint, Image icon)

Sets the TextArea hint text and Icon, the hint text and icon are displayed on the TextArea when there is no text in the TextArea

Parameters

hint String: the hint text to display
icon Image: the hint icon to display