Package totalcross.ui

Class ListBox

  • All Implemented Interfaces:
    Scrollable
    Direct Known Subclasses:
    ColorList, DBListBox, ImageList, MultiListBox
    public class ListBox
extends Container
implements Scrollable
    ListBox is a complete implementation of a Listbox. You can use the up/down keys to scroll and enter the first letter of an item to select it.

    Note: the color used in the setBackColor() method will be used in the scrollbar only. The background color of the control will be a lighter version of the given color.

    Here is an example showing how it can be used: 

     import totalcross.ui.*;

 public class MyProgram extends MainWindow
 {
 ListBox lb;

 public void initUI()
 {
   lb = new ListBox();
   add(lb);
   lb.add(new String[]{"Daniel","Jenny","Helge","Sandra"});
   lb.add("Marc");
   // you may set the rect by using PREFERRED only after the items were added.
   lb.setRect(LEFT,TOP,PREFERRED,PREFERRED); // use control's preferred width based on the size of the elements
 }

 public void onEvent(Event event)
 {
    switch (event.type)
    {
       case ControlEvent.PRESSED:
          if (event.target == lb)
             Object element = lb.getSelectedItem(); // in most cases, this is just a String and may be casted to such
    }
 }
 }
    The first item has index 0.

    • Field Detail

      • items

        protected Vector items

      • offset

        protected int offset

      • selectedIndex

        protected int selectedIndex

      • tempSelectedIndex

        protected int tempSelectedIndex

      • itemCount

        protected int itemCount

      • visibleItems

        protected int visibleItems

      • btnX

        protected int btnX

      • btnX0

        protected int btnX0

      • simpleBorder

        protected boolean simpleBorder

      • xOffset

        protected int xOffset

      • back0

        protected int back0

      • back1

        protected int back1

      • customCursorColor

        protected int customCursorColor

      • iconGap

        public int iconGap
        The gap between the icon and the text. Used in IconItem. Defaults to fmH*4/3. If you plan to change this value, do it after calling setFont (if you call it).
        Since:
        TotalCross 1.61

      • drawBorder

        public boolean drawBorder
        Set to false to disable border drawing.

      • EXTRA_HEIGHT_FACTOR

        public static int EXTRA_HEIGHT_FACTOR
        When the ListBox has horizontal buttons and its height divided by the button height is greater than this value (10), the horizontal button heights are increased.
        See Also:
        extraHorizScrollButtonHeight, enableHorizontalScroll()

      • ihtBackColors

        public IntHashtable ihtBackColors
        IntHashtable used to specify different background colors for some items. Example: 
         list.ihtBackColor = new IntHashtable(10);
 ihtBackColors.put(10,0xAABBCC); // will make line number 10 with back color 0xAABBCC.
        Specify a null value if you want to use the default back color (this also makes drawing faster). Note that its up to you to update the hashtable if an item is inserted or removed.
        Since:
        TotalCross 1.0 beta 4

      • ihtForeColors

        public IntHashtable ihtForeColors
        IntHashtable used to specify different foreground colors for some items. Example: 
         list.ihtForeColor = new IntHashtable(10);
 ihtForeColors.put(10,Color.RED); // will make line number 10 with fore color RED.
        Specify a null value if you want to use the default fore color (this also makes drawing faster). Note that its up to you to update the hashtable if an item is inserted or removed.
        Since:
        TotalCross 1.0 beta 4

      • extraHorizScrollButtonHeight

        public int extraHorizScrollButtonHeight
        The extra height of the horizontal scroll buttons. Defaults 2 in 160x160 or a multiple of it in other resolutions.
        See Also:
        EXTRA_HEIGHT_FACTOR, enableHorizontalScroll()

      • flick

        protected Flick flick
        The Flick object listens and performs flick animations on PenUp events when appropriate.

      • visibleLines

        public int visibleLines
        Sets the number of visible lines, used to make PREFERRED height return the given number of lines as the grid height.
        Since:
        TotalCross 1.13

      • useFullWidthOnSelection

        public static boolean useFullWidthOnSelection
        If true, all ListBox will have the selection bar drawn in the full width instead of the selected's text width
        Since:
        SuperWaba 5.5

      • DEFAULT_ITEM_HEIGHT_FACTOR

        public static final double DEFAULT_ITEM_HEIGHT_FACTOR
        See Also:
        Constant Field Values

      • itemHeightFactor

        public static double itemHeightFactor
        In finger touch devices, sets a factor by which the font height will be multiplied to increase the item's height. Defaults to 1.5 when Settings.fingerTouch is true, and 1 when its false. You can change this value before the constructor and restore it after the constructor to change the height of a single ListBox. 
         ListBox.itemHeightFactor = 1;
 ... create listbox
 ListBox.itemHeightFactor = ListBox.DEFAULT_ITEM_HEIGHT_FACTOR;
        Since:
        TotalCross 1.5

      • ihFactor

        protected double ihFactor

      • dataCol

        protected int dataCol
        Used by the DBListBox to store the data column that is displayed.

    • Constructor Detail

      • ListBox

        public ListBox()
        Creates an empty Listbox.

      • ListBox

        public ListBox​(java.lang.Object[] items)
        Creates a Listbox with the given items.

    • Method Detail

      • flickStarted

        public boolean flickStarted()
        Description copied from interface: Scrollable
        Called when the flick animation is started.
        Specified by:
        flickStarted in interface Scrollable

      • flickEnded

        public void flickEnded​(boolean atPenDown)
        Description copied from interface: Scrollable
        Called when the flick animation is ended.
        Specified by:
        flickEnded in interface Scrollable
        Parameters:
        atPenDown - Flag indicating if the animation ended due to a pendown event.

      • canScrollContent

        public boolean canScrollContent​(int direction,
                                java.lang.Object target)
        Description copied from interface: Scrollable
        Checks if there is room to flick this container in the given direction.
        Specified by:
        canScrollContent in interface Scrollable
        Parameters:
        direction - The direction we want to flick given by one of the following constants:
        target - The target of the series of PEN events that triggered this flick attempt.
        Returns:
        true if the container can flick in the indicated direction.

      • scrollContent

        public boolean scrollContent​(int xDelta,
                             int yDelta,
                             boolean fromFlick)
        Description copied from interface: Scrollable
        Performs a relative move.
        Specified by:
        scrollContent in interface Scrollable
        Parameters:
        xDelta - The relative amount of pixels to move in the X axis.
        yDelta - The relative amount of pixels to move in the Y axis.

      • getScrollPosition

        public int getScrollPosition​(int direction)
        Description copied from interface: Scrollable
        Returns the current position given the direction. Used on page scrolls.
        Specified by:
        getScrollPosition in interface Scrollable

      • enableHorizontalScroll

        public void enableHorizontalScroll()
        Adds support for horizontal scroll on this listbox. Two buttons will appear below the vertical scrollbar. The add, replace and remove operations will be a bit slower because the string's width will have to be computed in order to correctly set the max horizontal scroll.
        Since:
        SuperWaba 5.6
        See Also:
        extraHorizScrollButtonHeight

      • add

        public void add​(java.lang.Object[] moreItems)
        Adds an array of Objects to the Listbox

      • add

        @Deprecated
public void add​(java.lang.Object[] moreItems,
                int startAt,
                int size)
        Deprecated.
        Use add(Object[]) instead
        Adds a range of an array of Objects to the Listbox

      • add

        public void add​(java.lang.Object item)
        Adds an Object to the Listbox

      • addWrapping

        public int addWrapping​(java.lang.String text)
        Adds the given text to this ListBox, breaking the text if it goes beyond the ListBox' limits, and also breaking if it contains \n. Returns the number of lines. Note that each part of the text is considered a new item. This method is slower than the other add methods.
        Since:
        TotalCross 1.24

      • insert

        public void insert​(java.lang.Object item,
                   int index)
        Adds an Object to the Listbox at the given index

      • removeAll

        public void removeAll()
        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 Container

      • remove

        public void remove​(int itemIndex)
        Removes the Object at the given index from the Listbox

      • remove

        public void remove​(java.lang.Object item)
        Removes an Object from the Listbox

      • setItemAt

        public void setItemAt​(int i,
                      java.lang.Object s)
        Replace the Object at the given index, starting from 0

      • getItemAt

        public java.lang.Object getItemAt​(int i)
        Get the Object at the given Index. Returns an empty string if the index is outside of range.

      • getSelectedItem

        public java.lang.Object getSelectedItem()
        Returns the selected item of the Listbox or an empty String Object if none is selected

      • getSelectedIndex

        public int getSelectedIndex()
        Returns the position of the selected item of the Listbox or -1 if the listbox has no selected index yet.

      • getItems

        public java.lang.Object[] getItems()
        Returns all items in this ListBox. If the elements are Strings, the array can be casted to String[].

      • getItemsArray

        protected java.lang.Object[] getItemsArray()
        Used internally

      • indexOf

        public int indexOf​(java.lang.Object name)
        Returns the index of the item specified by the name, or -1 if not found.

      • setSelectedItem

        public void setSelectedItem​(java.lang.Object name)
        Selects the given name. If the name is not found, the current selected item is not changed.
        Since:
        SuperWaba 4.01

      • setSelectedIndex

        public void setSelectedIndex​(int i)
        Select the given index and scroll to it if necessary.

      • setSelectedIndex

        public void setSelectedIndex​(int i,
                             boolean sendPressEvent)
        Select the given index and scroll to it if necessary, sending or not the pressed event.

      • selectLast

        public void selectLast()
        Selects the last item added to this listbox, doing a scroll if needed. Calls repaintNow.
        Since:
        SuperWaba 5.6

      • selectLast

        public void selectLast​(boolean sendPressEvent)
        Selects the last item added to this listbox, doing a scroll if needed, and sending or not the event. Calls repaintNow.

      • size

        public int size()
        Returns the number of items

      • add

        public void add​(Control control)
        Do nothing. Adding a control to a ListBox is nonsense.
        Overrides:
        add in class Container

      • remove

        public void remove​(Control control)
        Do nothing. Removing a control from a ListBox is nonsense.
        Overrides:
        remove in class Container

      • getPreferredWidth

        public int getPreferredWidth()
        Returns the preferred width, ie, the size of the largest item plus the size of the scrollbar.
        Overrides:
        getPreferredWidth in class Control

      • getPreferredHeight

        public int getPreferredHeight()
        Returns the number of items multiplied by the font metrics height
        Overrides:
        getPreferredHeight in class Control

      • onBoundsChanged

        protected void onBoundsChanged​(boolean screenChanged)
        This is needed to recalculate the box size for the selected item if the control is resized by the main application
        Overrides:
        onBoundsChanged in class Control
        Parameters:
        screenChanged - If the bounds were changed due to a screen change (rotation, collapse)

      • find

        protected void find​(char c)
        Searches this ListBox for an item with the first letter matching the given char. The search is made case insensitive. Note: if you override this class you must implement this method.

      • onEvent

        public void onEvent​(Event event)
        Handles the events for this control.
        Overrides:
        onEvent in class Control
        Parameters:
        event - the event to process
        See Also:
        Event, KeyEvent, PenEvent

      • leftReached

        protected void leftReached()

      • endSelection

        protected void endSelection()

      • handleSelection

        protected void handleSelection​(int newSelection)

      • setEnabled

        public void setEnabled​(boolean enabled)
        Description copied from class: Container
        Sets if this container and all childrens can or not accept events
        Overrides:
        setEnabled in class Container

      • 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 Container

      • onPaint

        public void onPaint​(Graphics g)
        Description copied from class: Container
        Draws the border (if any). If you override this method, be sure to call super.onPaint(g);, or the border will not be drawn.
        Overrides:
        onPaint in class Container
        Parameters:
        g - the graphics object for drawing
        See Also:
        Graphics

      • drawItems

        protected void drawItems​(Graphics g,
                         int dx,
                         int dy,
                         int greatestVisibleItemIndex)

      • getItemHeight

        protected int getItemHeight​(int i)

      • setTextAreaClip

        protected void setTextAreaClip​(Graphics g,
                               int dx,
                               int dy)

      • drawSelectedItem

        protected void drawSelectedItem​(Graphics g,
                                int from,
                                int to)

      • setCursorColor

        public void setCursorColor​(int color)
        Sets the cursor color for this ListBox. The default is equal to the background slightly darker.

      • drawItem

        protected void drawItem​(Graphics g,
                        int index,
                        int dx,
                        int dy)
        You can extend ListBox and overide this method to draw the items

      • drawSelectedItem

        protected void drawSelectedItem​(Graphics g,
                                int index,
                                int dx,
                                int dy)
        You can extend ListBox and overide this method to draw the items

      • getItemWidth

        protected int getItemWidth​(int index)
        Returns the width of the given item index with the current fontmetrics. Note: if you overide this class you must implement this method.

      • drawCursor

        protected void drawCursor​(Graphics g,
                          int sel,
                          boolean on)
        This method is used to draw the cursor around the desired item

      • getCursorColor

        protected int getCursorColor​(int index)

      • setSimpleBorder

        public void setSimpleBorder​(boolean simpleBorder)
        Sets the border of the listbox to be not 3d if flag is true.

      • qsort

        public void qsort()
        Sorts the elements of this ListBox. The current selection is cleared.

      • qsort

        public void qsort​(boolean caseless)
        Sorts the elements of this ListBox. The current selection is cleared.
        Parameters:
        caseless - Pass true to make a caseless sort, if the items are Strings.

      • clear

        public void clear()
        Clears this control, selecting index clearValueInt.
        Overrides:
        clear in class Container

      • getFocusableControls

        public void getFocusableControls​(Vector v)
        Description copied from class: Container
        Get a list of child controls of this container which are focus candidates
        Overrides:
        getFocusableControls in class Container
        Parameters:
        v - A vector into which to add the focus candidates.

      • 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 Control
        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

      • getText

        public java.lang.String getText()
        Returns the string of the selected item or "" if none is selected.

      • setSelectedItemStartingWith

        public boolean setSelectedItemStartingWith​(java.lang.String text,
                                           boolean caseInsensitive)
        Selects the item that starts with the given text
        Parameters:
        text - The text string to search for
        caseInsensitive - If true, the text and all searched strings are first converted to lowercase.
        Returns:
        If an item was found and selected.
        Since:
        TotalCross 1.13

      • hideScrollBarIfNotNeeded

        public boolean hideScrollBarIfNotNeeded()
        This method hides the scrollbar if its not needed, i.e., if horizontal scroll is disabled and the preferred height is smaller than the actual height. You may have to call reposition if this method returns true. You can call this method after all items were added.
        Returns:
        True if the scrollbar was hidden.
        Since:
        TotalCross 1.15

      • getFlick

        public Flick getFlick()
        Description copied from interface: Scrollable
        Returns the current flick object.
        Specified by:
        getFlick in interface Scrollable

      • wasScrolled

        public boolean wasScrolled()
        Description copied from interface: Scrollable
        Returns true if the control was scrolled since last pen down
        Specified by:
        wasScrolled in interface Scrollable