choice.java

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

/*
 * @(#)Choice.java	1.14 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>Choice defines an API for a user interface components implementing
 * selection from predefined number of choices. Such UI components are
 * {@link List List} and {@link ChoiceGroup ChoiceGroup}.
 * The contents of the Choice are represented
 * with strings and optional images.</P>
 *
 * <P>Each element of a Choice is composed of a text string and an
 * optional image. The application may provide <code>null</code> for the
 * image if the element does not have an image part. If the application
 * provides an image, the implementation may choose to ignore the image if it
 * exceeds the capacity of the device to display it. If the implementation
 * displays the image, it will be displayed adjacent to the text string and
 * the pair will be treated as a unit. </p>
 *
 * <P>Images within any particular Choice object should all be of the same
 * size, because the implementation is allowed to allocate the same amount of
 * vertical space for every element.</P>
 *
 * <P>If an element is too long to be displayed, the implementation will
 * provide the user
 * with means to see the whole element. If this is done by wrapping an element
 * to multiple lines, the second and subsequent lines show a clear indication to
 * the user that they are part of the same element and are not a new
 * element.</P>
 *
 * <P>After a Choice object has been created, elements may be inserted, 
 * appended, and deleted, and each element's string part and image part may be 
 * get and set.  Elements within a Choice object are referred to by their 
 * indexes, which are consecutive integers in the range from zero to size()-1, 
 * with zero referring to the first element and size()-1 to the last element.
 * </P>
 * 
 * <P>There are three types of Choices: implicit-choice (valid only for
 * {@link List List}), exclusive-choice,
 * and multiple-choice. </p>
 *
 * <P>The exclusive-choice presents a series of elements and interacts with the
 * user. That is, when the user selects an element,
 * that element is shown to be selected using a distinct visual
 * representation. Exactly one element must be selected at any given time.
 * If at any time a situation would result where there are elements in the
 * exclusive-choice but none is selected, the implementation will choose an
 * element and select it. This situation can arise when an element is added
 * to an empty Choice, when the selected element is deleted from the
 * Choice, or when a Choice is created and populated with elements
 * by a constructor.  In these cases, the choice of which element is
 * selected is left to the implementation.  Applications for which the selected 
 * element is significant should set the selection explicitly.
 * There is no way for the user to unselect an element within an
 * Exclusive Choice.</p>
 *
 * <P>The implicit choice is an exclusive choice where the focused
 * element is implicitly selected when a command is initiated.</P>
 *
 * <P>A multiple-choice presents a series of elements and allows the user to
 * select any number of elements in any combination. As with
 * exclusive-choice, the multiple-choice interacts with the user in
 * object-operation mode. The visual appearance of a multiple-choice will
 * likely have a visual representation distinct from the exclusive-choice
 * that shows the selected state of each element as well as indicating to the
 * user that multiple elements may be selected. </P>
 *
 * <P>The selected state of an element is a property of the element. This state
 * stays with that element if other elements are inserted or deleted, causing
 * elements to be shifted around.  For example, suppose element <em>n</em> is
 * selected, and a new element is inserted at index zero.  The selected element
 * would now have index <em>n+1</em>.  A similar rule applies to deletion.  
 * Assuming <em>n</em> is greater than zero, deleting element zero would leave 
 * element <em>n-1</em> selected.  Setting the contents of an element leaves 
 * its selected state unchanged.  When a new element is inserted or appended, 
 * it is always unselected (except in the special case of adding an element to 
 * an empty Exclusive Choice as mentioned above).</P>
 *
 * <P>When a Choice 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 either when some application-defined
 * {@link Command Command} is fired, or when selection state of
 * {@link ChoiceGroup} is changed.
 * When command is fired
 * a high-level event is delivered to the listener of the Screen.
 * The event delivery is done with
 * {@link CommandListener#commandAction(Command, Displayable)
 * commandAction }.
 * In the case of {@link ChoiceGroup ChoiceGroup} the
 * {@link ItemStateListener#itemStateChanged(Item)
 * ItemStateListener} is called
 * when the user changes the selection state of the ChoiceGroup.
 * At this time the application can query the Choice for
 * information about the currently selected element(s).</P>
 *
 */
public interface Choice {

    /**
     * EXCLUSIVE is a choice having exactly one element selected at time.
     *
     * <P>Value 1 is assigned to EXCLUSIVE.</P>
     */
    public static final int EXCLUSIVE = 1;

    /**
     * MULTIPLE is a choice that can have arbitrary number of 
     * elements selected at a time.
     *
     * <P>Value 2 is assigned to MULTIPLE.</P>
     */
    public static final int MULTIPLE  = 2;

    /**
     * IMPLICIT is a choice in which the currently focused item
     * is selected when a {@link Command Command} is initiated.
     * (Note: IMPLICIT is not accepted by
     * {@link javax.microedition.lcdui.ChoiceGroup ChoiceGroup})
     *
     * <P>Value 3 is assigned to IMPLICIT.</P>
     */
    public static final int IMPLICIT = 3;

    /**
     * <p>Gets the number of elements present.</p>
     * @return the number of elements in the Choice
     */
    public int size();

    /**
     * <p>Gets the String part of the element referenced by elementNum.
     * The elementNum parameter must be within the range
     * [0..size()-1], inclusive. </p>
     *
     * @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);

    /**
     * <p>Gets the Image part of the element referenced by elementNum.
     * The elementNum parameter must be within the range
     * [0..size()-1], inclusive. </p>
     *
     * @param elementNum the index 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);

    /**
     * <p>Appends an element to the Choice. The added element will be the last
     * element of the Choice. The size of the Choice grows by one. </p>
     *
     * @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