/* * @(#)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