list.java

有关j2me的很好的例子可以研究一下

/*
 * @(#)List.java	1.52 01/08/21
 * Copyright (c) 1999-2001 Sun Microsystems, Inc. All Rights Reserved.
 *
 * This software is the confidential and proprietary information of Sun
 * Microsystems, Inc. ("Confidential Information").  You shall not
 * disclose such Confidential Information and shall use it only in
 * accordance with the terms of the license agreement you entered into
 * with Sun.
 *
 * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
 * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
 * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
 * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
 * THIS SOFTWARE OR ITS DERIVATIVES.
 */

package javax.microedition.lcdui;

/**
 * <p>The List class is a Screen containing list of choices.
 * Most of the behavior is common with class
 * {@link ChoiceGroup ChoiceGroup} and the common API
 * is defined in interface {@link Choice Choice}.
 * When a List is present on the display the user can interact with it
 * indefinitely (for instance, traversing from element to element
 * and possibly
 * scrolling). These traversing and scrolling operations do not cause
 * application-visible events. The system notifies
 * the application when some
 * {@link Command Command} is fired.
 * The notification of the application is done with
 * {@link CommandListener#commandAction(Command, Displayable)
 * commandAction }. </p>
 *
 * <P>List, like any Choice, utilizes a dedicated "select" or "go" functionality
 * of the devices. Typically, the select functionality is distinct from the
 * soft-buttons, but some devices may use soft-buttons for the select.
 * In any case, the application does not have a mean to set a label for a
 * select key.<P>
 *
 * <P>In respect to select functionality here are three types of Lists:</P>
 * <UL>
 * <LI>IMPLICIT where select causes immediate notification of the application
 * if there is a {@link CommandListener CommandListener} registered.
 * The element that has the focus will be selected before any CommandListener
 * for this List is called.
 * An implicit {@link #SELECT_COMMAND SELECT_COMMAND} is a parameter
 * for the notification.</LI>
 * <LI>EXCLUSIVE where select operation changes the selected element
 * in the list.
 * Application is not notified.</LI>
 * <LI>MULTIPLE where select operation toggles the selected state
 * of the focused Element. Application is not notified.</LI>
 * </UL>
 *
 * <P>IMPLICIT List can be used to construct menus by placing logical commands
 * to elements. In this case no application defined {@link Command Commands}
 * have to be attached. Application just has to register a CommandListener
 * that is called when user "selects".</P>
 *
 * <P>Another use might be implementation of a Screen with a default
 * operation that takes place when "select" is pressed.
 * For example, the List may contain email headers, and three operations:
 * read, reply, and delete. Read is consider to be the default operation.</P>
 * 
 * <PRE><CODE>
 * void initialize() {
 *     myScreen = new List("EMAIL", List.IMPLICIT);
 *     readCommand = new Command("read", Command.SCREEN, 1);
 *     replyCommand = new Command("reply", Command.SCREEN, 1);
 *     deleteCommand = new Command("delete", Command.SCREEN, 1);
 *     myScreen.addCommand(readCommand);
 *     myScreen.addCommand(replyCommand);
 *     myScreen.addCommand(deleteCommand);
 *     myScreen.setCommandListener(this);
 * }
 * </CODE></PRE>
 * 
 * <P>Because the list is of type IMPLICIT, the select operation also calls the
 * method {@link CommandListener#commandAction(Command, Displayable)
 * commandAction}
 * with parameter {@link #SELECT_COMMAND SELECT_COMMAND}. The implementation of
 * commandAction() can now do the obvious thing and start the read operation:
 * </P>
 * 
 * <PRE><CODE>
 * public void commandAction (Command c, Displayable d) {
 *     if (d == myScreen) {
 *         if (c == readCommand || c == List.SELECT_COMMAND) {
 *             // show the mail to the user
 *         }
 *         // ...
 *     }
 * }
 * </CODE></PRE>
 * 
 * <P>It should be noted that this kind of default operation must be used
 * carefully and the usability of the resulting user interface must always kept
 * in mind.</P>
 *
 * <P>The application can also set the currently
 * selected element(s) prior to displaying the List. </p>
 *
 * <p><b>Note:</b> Many of the essential methods have been documented in
 * {@link Choice interface Choice}. </p>
 */
public class List extends Screen implements Choice {

    // SYNC NOTE: The List constructor establishes 'cg' as non-null
    // and which remains constant for the lifetime of this object.
    // All public api calls are delegated to the 'cg' object and
    // therefore no synchronization is necessary.
    /**
     * An internal choicegroup to handle the selections
     */
    private ChoiceGroup cg;
    
    /**
     * SELECT_COMMAND is a special command that
     * {@link CommandListener#commandAction(Command, Displayable)
     * commandAction}
     * can use to recognize the user did the select operation on a IMPLICIT
     * List. The field values of SELECT_COMMAND are:<BR>
     * - label = "" (an empty string)<BR>
     * - type = SCREEN<BR>
     * - priority = 0<BR>
     * The application should not use these values for recognizing
     * the SELECT_COMMAND.
     * Instead, object identities of the Command and Displayable (List)
     * should be used.
     */
    public final static Command SELECT_COMMAND =
                new Command("", Command.SCREEN, 0);
    
    /**
     * <p>Creates a new, empty List, specifying its title and the type of the
     * list. </p>
     * @param title the screen's title (see {@link Screen Screen})
     * @param listType one of IMPLICIT, EXCLUSIVE, or MULTIPLE
     * @throws IllegalArgumentException if listType is not one of IMPLICIT,
     * EXCLUSIVE, or MULTIPLE.
     * @see Choice
     */
    public List(String title, int listType) {
        this(title, listType, new String[] {}, new Image[] {});
    }

    /**
     * <p>Creates a new List, specifying its title, the type of the List, and
     * an array of Strings and Images to be used as its initial contents. </p>
     *
     * <p>The stringElements array must be non-null and every array element
     * must also be non-null.  The length of the stringElements array
     * determines the number of elements in the List.  The imageElements array
     * may be null to indicate that the List elements have no images.  If the
     * imageElements array is non-null, it must be the same length as the
     * stringElements array.  Individual elements of the imageElements array
     * may be null in order to indicate the absence of an image for the
     * corresponding List element. Any elements present in the
     * imageElements array must refer to immutable images.</p>
     * 
     * @param title the screen's title (see {@link Screen Screen})
     * @param listType one of IMPLICIT, EXCLUSIVE, or MULTIPLE
     * @param stringElements set of strings specifying the string parts of the 
     * List elements
     * @param imageElements set of images specifying the image parts of
     * the List elements
     *
     * @throws NullPointerException if stringElements is null
     * @throws NullPointerException if the stringElements array contains
     * any null elements
     * @throws IllegalArgumentException if the imageElements array is non-null 
     * and has a different length from the stringElements array
     * @throws IllegalArgumentException if listType is not one of IMPLICIT,
     * EXCLUSIVE, or MULTIPLE.
     * @throws IllegalArgumentException if any image in the imageElements
     * array is mutable
     * 
     * @see Choice#EXCLUSIVE
     * @see Choice#MULTIPLE
     * @see Choice#IMPLICIT
     */
    public List(String title, int listType, 
                String[] stringElements, Image[] imageElements) {

        super(title);

        synchronized (Display.LCDUILock) {
            cg = new ChoiceGroup(null, listType, 
                                 stringElements, imageElements, true);
            cg.setOwner(this);
        }
    }

    /**
     * @return the number of elements in the List
     */
    public int size() {
        return cg.size();
    }

    /**
     * @param elementNum the index of the element to be queried
     * @return the string part of the element
     * @throws IndexOutOfBoundsException if elementNum is invalid
     * @see #getImage(int)
     */
    public String getString(int elementNum) {
        return cg.getString(elementNum);
    }

    /**
     * @see #getString(int)
     *
     * @param elementNum the number of the element to be queried
     * @return the image part of the element, or null if there is no image
     * @throws IndexOutOfBoundsException if elementNum is invalid
     * @see #getString(int)
     */
    public Image getImage(int elementNum) {
        return cg.getImage(elementNum);
    }

    /**
     * @param stringPart the string part of the element to be added
     * @param imagePart the image part of the element to be added, or null if
     * there is no image part
     * @return the assigned index of the element
     * @throws IllegalArgumentException if the image is mutable
     * @throws NullPointerException if stringPart is null
     */
    public int append(String stringPart, Image imagePart) {
        return cg.append(stringPart, imagePart);
    }

    /**
     * @param elementNum the index of the element where insertion is to occur
     * @param stringPart the string part of the element to be inserted
     * @param imagePart the image part of the element to be inserted,
     * or null if there is no image part
     * @throws IndexOutOfBoundsException if elementNum is invalid
     * @throws IllegalArgumentException if the image is mutable
     * @throws NullPointerException if stringPart is null
     */
    public void insert(int elementNum, 
                       String stringPart, Image imagePart) {
        cg.insert(elementNum, stringPart, imagePart);
    }

    /**
     * @param elementNum the index of the element to be deleted
     * @throws IndexOutOfBoundsException if elementNum is invalid
     */
    public void delete(int elementNum) {
        cg.delete(elementNum);
    }

    /**
     * @param elementNum the index of the element to be set
     * @param stringPart the string part of the new element
     * @param imagePart the image part of the element, or null if there is
     * no image part
     *
     * @throws IndexOutOfBoundsException if elementNum is invalid
     * @throws IllegalArgumentException if the image is mutable
     * @throws NullPointerException if stringPart is null
     */
    public void set(int elementNum, String stringPart, Image imagePart) {
        cg.set(elementNum, stringPart, imagePart);
    }

    /**
     * @param elementNum index to element to be queried
     *
     * @return selection state of the element
     *
     * @throws IndexOutOfBoundsException if elementNum is invalid
     */
    public boolean isSelected(int elementNum) {
        return cg.isSelected(elementNum);
    }

    /**
     * @return index of selected element, or -1 if none
     * @see #setSelectedIndex
     */
    public int getSelectedIndex() {
        return cg.getSelectedIndex();
    }

    /**
     * @param selectedArray_return array to contain the results
     *
     * @return the number of selected elements
     *
     * @throws IllegalArgumentException if selectedArray_return is shorter
     * than the size of the List
     * @throws NullPointerException if selectedArray_return is null
     * @see #setSelectedFlags
     */
    public int getSelectedFlags(boolean[] selectedArray_return) {
        return cg.getSelectedFlags(selectedArray_return);
    }

    /**
     * @param elementNum the index of the element, starting from zero
     * @param selected the state of the element, where <code>true</code> means
     * selected and <code>false</code> means not selected
     * @throws IndexOutOfBoundsException if elementNum is invalid
     * @see #getSelectedIndex
     */
    public void setSelectedIndex(int elementNum, boolean selected) {
        cg.setSelectedIndex(elementNum, selected);
    }

    /**
     * @param selectedArray an array in which the method collect
     * the selection status
     * @throws IllegalArgumentException if selectedArray is shorter than the
     * size of the List
     * @throws NullPointerException if selectedArray is null
     * @see #getSelectedFlags
     */
    public void setSelectedFlags(boolean[] selectedArray) {
        cg.setSelectedFlags(selectedArray);
    }


    /**
     * Initializes hilight when list is shown.
     * @param vpY y coordinate of viewport location
     * @param vpH viewport height
     * @return new y coordinate of viewport location in
     *         child (all items) coordinate system
     */
    int initHilight(int vpY, int vpH) {
        return cg.initHilight(vpY, vpH);
    }

    /**
     * Paint the content of this List
     *
     * @param g The Graphics context to paint to
     */
    void paintContent(Graphics g) {
        cg.paint(g);

        // List content is shorter than the clip;
        // fill the remaining area with erase color
        int cgHeight = cg.getHeight();
        int clipY2 = g.getClipY() + g.getClipHeight();
        if (cgHeight < clipY2) {
            g.setColor(Display.ERASE_COLOR);
            g.fillRect(g.getClipX(), cgHeight,
                       g.getClipWidth(), clipY2 - cgHeight);
        }
    }

    /**
     * Layout the content of this List
     *
     * @param w The maximum allowable width
     * @param h The allowable height (not used)
     * @return int The height required to display this List given
     *              the maximum allowable width
     */
    int layoutContent(int w, int h) {
        return cg.setWidth(w);
    }

    /**
     * Traverse this List
     *
     * @param dir
     * @param top
     * @param bottom
     * @return int
     */
    int traverse(int dir, int top, int bottom) {
        if (dir == Canvas.UP || dir == Canvas.DOWN) {
            return cg.traverse(dir, top, bottom, false, false);
        }
        return -1;
    }

    /**
     * Handle a key pressed event
     *
     * @param keyCode The key that was pressed
     */
    void keyPressed(int keyCode) {
        CommandListener cl = null;

        synchronized (Display.LCDUILock) {
            super.keyPressedImpl(keyCode);

            if (Display.getGameAction(keyCode) == Canvas.FIRE) {
                if (cg.select()) {
                    cl = listener;
                }
            }
        } // synchronized

        // SYNC NOTE: The call to the listener must occur outside
        // of the lock
        if (cl != null) {
            try {
                // SYNC NOTE: We lock on calloutLock around any calls
                // into application code
                synchronized (Display.calloutLock) {
                    cl.commandAction(SELECT_COMMAND, this);
                }
            } catch (Throwable thr) {
                Display.handleThrowable(thr);
            }
        }
    }
}