choice.java

j2me is based on j2mepolish, client & server for mobile application. menu sample

//#condition polish.usePolishGui
// generated by de.enough.doc2java.Doc2Java (www.enough.de) on Sat Dec 06 15:06:43 CET 2003
/*
 * Copyright (c) 2004-2005 Robert Virkus / Enough Software
 *
 * This file is part of J2ME Polish.
 *
 * J2ME Polish is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * 
 * J2ME Polish is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with J2ME Polish; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 * 
 * Commercial licenses are also available, please
 * refer to the accompanying LICENSE.txt or visit
 * http://www.j2mepolish.org for details.
 */
package de.enough.polish.ui;

import javax.microedition.lcdui.Font;
import javax.microedition.lcdui.Image;

/**
 * Choice defines an API for a user interface components implementing
 * selection from predefined number of choices. Such UI components are
 * <A HREF="../../../javax/microedition/lcdui/List.html"><CODE>List</CODE></A> and <A HREF="../../../javax/microedition/lcdui/ChoiceGroup.html"><CODE>ChoiceGroup</CODE></A>.
 * The contents of the <code>Choice</code> are represented
 * with strings and images.
 * 
 * <P>Each element of a <code>Choice</code> is composed of a text string part,
 * an <A HREF="../../../javax/microedition/lcdui/Image.html"><CODE>Image</CODE></A> part, 
 * and a font attribute that are all treated as a
 * unit.  The font attribute applies to the text part and can be controlled by
 * the application.  The application may provide
 * <code>null</code> for the image if the element is not to have an image
 * part.  The implementation must display the image at the beginning of the
 * text string.  If the <code>Choice</code> also has a selection
 * indicator (such as a radio
 * button or a checkbox) placed at the beginning of the text string, the
 * element's image should be placed between the selection indicator and the
 * beginning of the text string.</P>
 * 
 * <P>When a new element is inserted or appended, the implementation provides
 * a default font for the font attribute.  This default font is the same font
 * that is used if the application calls <code>setFont(i, null)</code>.  All
 * <code>ChoiceGroup</code> instances must have the same default font, and all
 * <code>List</code> instances must have the same default font.  However, the
 * default font used for <code>Choice</code> objects may differ from the font
 * returned by <A HREF="../../../javax/microedition/lcdui/Font.html#getDefaultFont()"><CODE>Font.getDefaultFont</CODE></A>.</P>
 * 
 * <P>The <code>Image</code> part of a <code>Choice</code> element may
 * be mutable or immutable.  If the
 * <code>Image</code> is mutable, the effect is as if snapshot of its
 * contents is taken at
 * the time the <code>Choice</code> is constructed with this
 * <code>Image</code> or when the <code>Choice</code>
 * element is created or modified with the <A HREF="../../../javax/microedition/lcdui/Choice.html#append(java.lang.String, javax.microedition.lcdui.Image)"><CODE>append</CODE></A>,
 * <A HREF="../../../javax/microedition/lcdui/Choice.html#insert(int, java.lang.String, javax.microedition.lcdui.Image)"><CODE>insert</CODE></A>, or <A HREF="../../../javax/microedition/lcdui/Choice.html#set(int, java.lang.String, javax.microedition.lcdui.Image)"><CODE>set</CODE></A> methods.
 * The snapshot is used whenever the contents of the
 * <code>Choice</code> element are to be displayed.  Even if the
 * application subsequently
 * draws into the <code>Image</code>, the snapshot is not modified
 * until the next call to
 * one of the above methods.  The snapshot is <em>not</em> updated when the
 * <code>Choice</code> becomes visible on the display.  (This is because the
 * application does not have control over exactly when
 * <code>Displayables</code> and <code>Items</code>
 * appear and disappear from the display.)</P>
 * 
 * <P>The following code illustrates a technique to refresh the image part of
 * element <code>k</code> of a <code>Choice</code> <code>ch</code>: </P>
 * <TABLE BORDER="2">
 * <TR>
 * <TD ROWSPAN="1" COLSPAN="1">
 * <pre><code>
 * ch.set(k, ch.getString(k), ch.getImage(k));    </code></pre>
 * </TD>
 * </TR>
 * </TABLE>
 * 
 * <P>If the application provides an image, the implementation may choose to
 * truncate it if it exceeds the capacity of the device to display it.
 * <code>Images</code>
 * within any particular <code>Choice</code> object should all be of
 * the same size, because
 * the implementation is allowed to allocate the same amount of space for
 * every element.  The application can query the implementation's image size
 * recommendation by calling <A HREF="../../../javax/microedition/lcdui/Display.html#getBestImageWidth(int)"><CODE>Display.getBestImageWidth(int)</CODE></A> and <A HREF="../../../javax/microedition/lcdui/Display.html#getBestImageHeight(int)"><CODE>Display.getBestImageHeight(int)</CODE></A>.</P>
 * 
 * <P>If an element is very long or contains a
 * <A HREF="Form.html#linebreak">line break</A>,
 * the implementation may display only a
 * portion of it.  If this occurs, the implementation should provide
 * the user with a means to see as much as possible of the element.
 * If this is done by wrapping an element
 * to multiple lines, the second and subsequent lines should show a clear
 * indication to
 * the user that they are part of the same element and are not a
 * new element.</P>
 * 
 * <P>The application can express a preference for the policy used by the
 * implementation for display of long elements including those that
 * contain line break characters.  The characters after the first line break
 * may only be visible if the policy permits it. The <A HREF="../../../javax/microedition/lcdui/Choice.html#setFitPolicy(int)"><CODE>setFitPolicy(int)</CODE></A> and
 * <A HREF="../../../javax/microedition/lcdui/Choice.html#getFitPolicy()"><CODE>getFitPolicy()</CODE></A> methods control this preference.  The valid settings
 * are
 * <A HREF="../../../javax/microedition/lcdui/Choice.html#TEXT_WRAP_DEFAULT"><CODE>TEXT_WRAP_DEFAULT</CODE></A>, <A HREF="../../../javax/microedition/lcdui/Choice.html#TEXT_WRAP_ON"><CODE>TEXT_WRAP_ON</CODE></A>, and
 * <A HREF="../../../javax/microedition/lcdui/Choice.html#TEXT_WRAP_OFF"><CODE>TEXT_WRAP_OFF</CODE></A>.
 * Unless specified otherwise by <code>Choice</code> implementation
 * classes, the initial
 * value of the element fit policy is <code>TEXT_WRAP_DEFAULT</code>.</P>
 * 
 * <P>After a <code>Choice</code> 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 <code>Choice</code> object are
 * referred to by their
 * indexes, which are consecutive integers in the range from zero to
 * <code>size()-1</code>,
 * with zero referring to the first element and <code>size()-1</code>
 * to the last element.
 * </P>
 * 
 * <P>There are four types of <code>Choices</code>: implicit-choice
 * (valid only for
 * <A HREF="../../../javax/microedition/lcdui/List.html"><CODE>List</CODE></A>), exclusive-choice,
 * multiple-choice, and pop-up (valid only for
 * <A HREF="../../../javax/microedition/lcdui/ChoiceGroup.html"><CODE>ChoiceGroup</CODE></A>). </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. If there are elements present in the <code>Choice</code>,
 * 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 <code>Choice</code>, when the selected element is
 * deleted from the
 * <code>Choice</code>, or when a <code>Choice</code> 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 <code>Choice</code>.</p>
 * 
 * <P>The popup choice is similar to the exclusive choice.  The selection
 * behavior of a popup choice is identical to that of an exclusive choice.
 * However, a popup choice differs from an exclusive choice in presentation
 * and interaction.  In an exclusive choice, all elements should be displayed
 * in-line.  In a popup choice, the selected element should always be
 * displayed, and the other elements should remain hidden until the user
 * performs a specific action to show them.  For example, an exclusive choice
 * could be implemented as a series of radio buttons with one always selected.
 * A popup choice could be implemented as a popup menu, with the selected
 * element being displayed in the menu button.</P>
 * 
 * <P>The implicit choice is an exclusive choice where the focused or
 * highlighted element is implicitly selected when a command is initiated.  As
 * with the exclusive choice, if there are elements present in the
 * <code>Choice</code>, one element is always selected.</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, Popup, or Implicit Choice as mentioned above).</P>
 * 
 * <P>The selected state of a <code>Choice</code> object can be controlled by
 * the application with the <A HREF="../../../javax/microedition/lcdui/Choice.html#setSelectedFlags(boolean[])"><CODE>setSelectedFlags</CODE></A> and
 * <A HREF="../../../javax/microedition/lcdui/Choice.html#setSelectedIndex(int, boolean)"><CODE>setSelectedIndex</CODE></A> methods.  This state is
 * available to the application through the <A HREF="../../../javax/microedition/lcdui/Choice.html#getSelectedFlags(boolean[])"><CODE>getSelectedFlags</CODE></A> and <A HREF="../../../javax/microedition/lcdui/Choice.html#getSelectedIndex()"><CODE>getSelectedIndex</CODE></A> methods.
 * The selected state reported by these methods
 * is generally identical to what has been set by the
 * application, with the following exceptions.  Adding or removing elements
 * may change the selection.  When the <code>Choice</code> is present on the
 * display, the implementation's user interface policy and direct user
 * interaction with the object may also affect the selection.  For example,
 * the implementation might update the selection to the current highlight
 * location as the user is moving the highlight, or it might set the selection
 * from the highlight only when the user is about to invoke a command.  As
 * another example, the implementation might move the highlight (and thus the
 * selection) of an implicit <code>List</code> to the first element each time
 * the <code>List</code> becomes current.  When a <code>Choice</code> object
 * is present on the display, applications should query its selected state
 * only within a <A HREF="../../../javax/microedition/lcdui/CommandListener.html"><CODE>CommandListener</CODE></A> or a <A HREF="../../../javax/microedition/lcdui/ItemStateListener.html"><CODE>ItemStateListener</CODE></A> callback.  Querying the state at other
 * times might result in a value different from what has been set by the
 * application (because the user or the implementation's UI policy might have
 * changed it) and it might not reflect the user's intent (because the user
 * might still in the process of making a selection).</P>
 *