list.java

j2me下的1套UI框架.包含j2me开发中会应用的各种低级组件

package com.jmobilecore.ui.core;

import java.util.Vector;

/**
 * The <code>List</code> component presents the user with a scrolling list of items.
 *
 * @author Greg Gridin
 */
public class List extends Label {

    /**
     * The event listener to receive events from this list.
     * Events occur when a user pressed one of the soft buttons or shortcuts.
     * If listener is null, no exception is thrown and no action is performed.
     */
    public EventListener eventListener;

    /**
     * This screen displays list of values for the current List.
     */
    public ListScreen listScreen;

    /**
     * A vector created to contain items which will become part of the List.
     */
    protected Vector items;

    /**
     * The index of selected item. If the value is <code>-1</code> then no items is selected
     */
    protected int selected = -1;

    /**
     * The title for the list screen
     *
     * @see com.jmobilecore.ui.core.ListScreen
     */
    protected Label title;

    /**
     * The left soft key for the list screen
     *
     * @see com.jmobilecore.ui.core.SoftKey
     * @see com.jmobilecore.ui.core.ListScreen
     */
    protected SoftKey leftKey;

    /**
     * The right soft key for the list screen
     *
     * @see com.jmobilecore.ui.core.SoftKey
     * @see com.jmobilecore.ui.core.ListScreen
     */
    protected SoftKey rightKey;

    /**
     * Creates a new scrolling list.
     */
    public List() {
        this(null);
    }

    /**
     * Creates a new scrolling list with the specified description
     *
     * @see #setText
     * @see #getText
     */
    public List(String label) {
        super(label);
        items = new Vector(8);
        focusable = true;
    }

    public void setListScreen(String titleText, String backKeyText, String selectKeyText) {
        this.title = Label.createTitleLabel(titleText);
        this.leftKey = new SoftKey(backKeyText) {
            public void performAction() {
                ScreenManager.goBack();
                if (eventListener!=null) {
                    eventListener.actionPerformed(EventListener.EVENT_ESCAPE);
                }
            }
        };
        this.rightKey = new SoftKey(selectKeyText) {
            public void performAction() {
                ScreenManager.goBack();
                select(listScreen.getFocusedIndex());
                if (eventListener!=null) {
                    eventListener.actionPerformed(EventListener.EVENT_OK);
                }
                if (parentScreen != null) {
                    parentScreen.repaint();
                }
            }
        };
    }

    public void setListScreen(Label title, SoftKey leftKey, SoftKey rightKey) {
        this.title = title;
        this.leftKey = leftKey;
        this.rightKey = rightKey;
    }

    /**
     * Adds the specified string as <code>ListLabel</code> to the end of scrolling list.
     *
     * @param text the string to be added
     */
    public void add(String text) {

        items.addElement(new ListLabel(text, font, PlatformCanvas.KEY_UNDEFINED));
    }

    /**
     * Adds the specified string as <code>ListLabel</code> to the the scrolling list
     * at the position indicated by the index. The index is zero-based.
     *
     * @param text  the string to be added
     * @param index the position at which to add the item
     */
    public void add(String text, int index) {

        items.insertElementAt(new ListLabel(text, font, PlatformCanvas.KEY_UNDEFINED), index);
    }

    /**
     * Adds the specified item to the end of scrolling list.
     *
     * @param item the item to be added
     */
    public void add(ListComponent item) {

        items.addElement(item);
    }

    /**
     * Adds the specified string as <code>ListLabel</code> to the the scrolling list
     * at the position indicated by the index. The index is zero-based.
     *
     * @param item  the item to be added
     * @param index the position at which to add the item
     */
    public void add(ListComponent item, int index) {

        items.insertElementAt(item, index);
    }

    /**
     * Deselects the item at the specified index.
     *
     * @param index the position of the item to deselect
     */
    public void deselect(int index) {

        selected = -1;
    }

    /**
     * Gets the textual representation of an item associated with the specified index.
     *
     * @param index the position of the item
     * @return an item that is associated with the specified index
     */
    public String getItem(int index) {

        return getComponent(index).getText();
    }

    /**
     * Gets the item associated with the specified index.
     *
     * @param index the position of the item
     * @return an item that is associated with the specified index
     */
    public ListComponent getComponent(int index) {

        return (ListComponent) items.elementAt(index);
    }

    /**
     * Gets the number of items in the list.
     *
     * @return the number of items in the list
     */
    public int getItemCount() {

        return items.size();
    }

    /**
     * Gets the index of the selected item on the list,
     *
     * @return the index of the selected item
     * @see #select
     * @see #deselect
     * @see #isIndexSelected
     */
    public int getSelectedIndex() {
        return selected;
    }

    /**
     * Gets the selected item on this scrolling list.
     *
     * @return the selected item on the list,
     *         or <code>null</code> if no item is selected
     * @see #select
     * @see #deselect
     * @see #isIndexSelected
     */
    public String getSelectedItem() {
        int sel = getSelectedIndex();
        if (sel < 0 || sel >= items.size()) {
            return null;
        }
        return getItem(sel);
    }

    /**
     * Gets the selected item on this scrolling list.
     *
     * @return the selected item on the list,
     *         or <code>null</code> if no item is selected
     * @see #select
     * @see #deselect
     * @see #isIndexSelected
     */
    public ListComponent getSelectedComponent() {
        int sel = getSelectedIndex();
        if (sel < 0 || sel >= items.size()) {
            return null;
        }
        return getComponent(sel);
    }

    /**
     * Determines if the specified item in this scrolling list is selected.
     *
     * @param index the item to be checked
     * @return <code>true</code> if the specified item has been
     *         selected; <code>false</code> otherwise
     * @see #select
     * @see #deselect
     */
    public boolean isIndexSelected(int index) {
        return getSelectedIndex() == index;
    }

    /**
     * Remove the item at the specified position from this scrolling list.
     *
     * @param index the index of the item to delete
     */
    public void remove(int index) {
        items.removeElementAt(index);
    }

    /**
     * Removes the first occurrence of an item from the list.
     *
     * @param item the item to remove from the list
     */
    public void remove(ListComponent item) {
        items.removeElement(item);
    }

    /**
     * Removes all items from this list.
     */
    public void removeAll() {
        items.removeAllElements();
    }

    /**
     * Replaces the item at the specified index in the scrolling list
     * with the new string.
     *
     * @param newValue a new string to replace an existing item
     * @param index    the position of the item to replace
     */
    public void replaceItem(String newValue, int index) {
        items.setElementAt(newValue, index);
    }

    /**
     * Selects the item at the specified index in the scrolling list.
     *
     * @param index the position of the item to select
     * @see #getSelectedItem
     * @see #deselect
     * @see #isIndexSelected
     */
    public void select(int index) {
        if (index < 0 || index >= items.size()) return;
        selected = index;
    }

    /**
     * Responds to key presses when the list has focus.
     * When <code>PlatformCanvas.KEY_ENTER</code> button is pressed creates new screen
     * that displays the list of list values
     *
     * @param keyCode The pressed key.
     */
    protected boolean keyPressed(int keyCode) {

        if (keyCode == PlatformCanvas.KEY_ENTER) {
            if (listScreen==null) listScreen = createListScreen();
            listScreen.changeFocus((selected==-1)?0:selected);
            ScreenManager.goForward(listScreen);
            return true;
        }
        return false;
    }

    /**
     * Creates new screen cantaining the list of list values.
     * Sets to focus state the currently selected item
     */
    public ListScreen createListScreen() {

        ListScreen listScreen = new ListScreen(title, leftKey, rightKey);
        final int size = this.getItemCount();
        for (int i = 0; i < size; i++) {
            listScreen.add((Component) this.getComponent(i));
        }
        if (selected < 0 || selected >= items.size())
            listScreen.changeFocus(0);
        else
            listScreen.changeFocus(selected);
        return listScreen;
    }

    /**
     * Default destructor. Helps VM to perform garbage collection
     */
    public void destructor() {
        removeAll();
        eventListener = null;
        items = null;
        title.destructor();
        title = null;
        leftKey = rightKey = null;
        listScreen.destructor();
        listScreen = null;
    }

} // class List