choice.java

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

 * <p>
 * <strong>Note:</strong> Methods have been added to the <code>Choice</code>
 * interface
 * in version 2.0.  Adding methods to interfaces is normally an incompatible
 * change.  However, <code>Choice</code> does not appear as a <em>type</em> in
 * any field, method parameter, or method return value, and so it is not
 * useful for an application to create a class that implements the
 * <code>Choice</code> interface.  Future versions of this specification may
 * make additional changes to the <code>Choice</code> interface.  In order to
 * remain compatible with future versions of this specification, applications
 * should avoid creating classes that implement the <code>Choice</code>
 * interface.
 * </p>
 * <HR>
 * 
 * 
 * @since MIDP 1.0
 */
public interface Choice
{
	/**
	 * <code>EXCLUSIVE</code> is a choice having exactly one element
	 * selected at time.  All
	 * elements of an <code>EXCLUSIVE</code> type <code>Choice</code>
	 * should be displayed in-line.  That
	 * is, the user should not need to perform any extra action to traverse
	 * among and select from the elements.
	 * 
	 * <P>Value <code>1</code> is assigned to <code>EXCLUSIVE</code>.</P>
	 */
	public static final int EXCLUSIVE = 1;

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

	/**
	 * <code>IMPLICIT</code> is a choice in which the currently focused
	 * element is selected when a <A HREF="../../../javax/microedition/lcdui/Command.html"><CODE>Command</CODE></A> is initiated.
	 * 
	 * <P>The <code>IMPLICIT</code> type is not valid for <A HREF="../../../javax/microedition/lcdui/ChoiceGroup.html"><CODE>ChoiceGroup</CODE></A> objects.</P>
	 * 
	 * <P>Value <code>3</code> is assigned to <code>IMPLICIT</code>.</P>
	 */
	public static final int IMPLICIT = 3;

	/**
	 * <code>POPUP</code> is a choice having exactly one element
	 * selected at a time.  The
	 * selected element is always shown.  The other elements should be hidden
	 * until the user performs a particular action to show them.  When the
	 * user performs this action, all elements become accessible.  For
	 * example, an implementation could use a popup menu to display the
	 * elements of a <code>ChoiceGroup</code> of type <code>POPUP</code>.
	 * 
	 * <P>The <code>POPUP</code> type is not valid for <A HREF="../../../javax/microedition/lcdui/List.html"><CODE>List</CODE></A> objects.</P>
	 * 
	 * <P>Value <code>4</code> is assigned to <code>POPUP</code>.</P>
	 * 
	 * @since MIDP 2.0
	 */
	public static final int POPUP = 4;

	/**
	 * Constant for indicating that the application has no preference as to
	 * wrapping or truncation of text element contents and that the
	 * implementation should use its default behavior.
	 * 
	 * <p>Field has the value <code>0</code>.</p>
	 * <DT><B>See Also: </B>
	 * <A HREF="../../../javax/microedition/lcdui/Choice.html#setFitPolicy(int)"><CODE>setFitPolicy(int)</CODE></A>
	 * 
	 * @since MIDP 2.0
	 */
	public static final int TEXT_WRAP_DEFAULT = 0;

	/**
	 * Constant for hinting that text element contents should be wrapped to to
	 * multiple lines if necessary to fit available content space.  The
	 * Implementation may limit the maximum number of lines that it will
	 * actually present.
	 * 
	 * <p>Field has the value <code>1</code>.</p>
	 * <DT><B>See Also: </B>
	 * <A HREF="../../../javax/microedition/lcdui/Choice.html#setFitPolicy(int)"><CODE>setFitPolicy(int)</CODE></A>
	 * 
	 * @since MIDP 2.0
	 */
	public static final int TEXT_WRAP_ON = 1;

	/**
	 * Constant for hinting that text element contents should be limited to a
	 * single line.  Line ending is forced, for example by cropping, if there
	 * is too much text to fit to the line.  The implementation should provide
	 * some means to present the full element contents.  This may be done, for
	 * example, by using a special pop-up window or by scrolling the text of
	 * the focused element.
	 * 
	 * <p>Implementations should indicate that cropping has occurred, for
	 * example, by placing an ellipsis at the point where the text contents
	 * have been cropped.</p>
	 * 
	 * <p>Field has the value <code>2</code>.</p>
	 * <DT><B>See Also: </B>
	 * <A HREF="../../../javax/microedition/lcdui/Choice.html#setFitPolicy(int)"><CODE>setFitPolicy(int)</CODE></A>
	 * 
	 * 
	 * @since MIDP 2.0
	 */
	public static final int TEXT_WRAP_OFF = 2;

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

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

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

	/**
	 * Appends an element to the <code>Choice</code>. The added
	 * element will be the last
	 * element of the <code>Choice</code>. The size of the
	 * <code>Choice</code> grows by one.
	 * 
	 * @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 NullPointerException - if stringPart is null
	 */
	public int append( String stringPart, Image imagePart);

	/**
	 * Inserts an element into the <code>Choice</code> just prior to
	 * the element specified.
	 * The size of the <code>Choice</code> grows by one.
	 * The <code>elementNum</code> parameter must be within the range
	 * <code>[0..size()]</code>, inclusive.  The index of the last
	 * element is <code>size()-1</code>, and
	 * so there is actually no element whose index is
	 * <code>size()</code>. If this value
	 * is used for <code>elementNum</code>, the new element is
	 * inserted immediately after
	 * the last element. In this case, the effect is identical to
	 * <A HREF="../../../javax/microedition/lcdui/Choice.html#append(java.lang.String, javax.microedition.lcdui.Image)"><CODE>append()</CODE></A>.
	 * 
	 * @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 NullPointerException - if stringPart is null
	 */
	public void insert(int elementNum, String stringPart, Image imagePart);

	/**
	 * Deletes the element referenced by <code>elementNum</code>.
	 * The size of the <code>Choice</code> shrinks by
	 * one. It is legal to delete all elements from a <code>Choice</code>.
	 * The <code>elementNum</code> parameter must be within the range
	 * <code>[0..size()-1]</code>, inclusive.
	 * 
	 * @param elementNum - the index of the element to be deleted
	 * @throws IndexOutOfBoundsException - if elementNum is invalid
	 */
	public void delete(int elementNum);

	/**
	 * Deletes all elements from this <code>Choice</code>, leaving it
	 * with zero elements.
	 * This method does nothing if the <code>Choice</code> is already empty.
	 * 
	 * @since  MIDP 2.0
	 */
	public void deleteAll();

	/**
	 * Sets the <code>String</code> and <code>Image</code> parts of the
	 * element referenced by <code>elementNum</code>,
	 * replacing the previous contents of the element.
	 * The <code>elementNum</code> parameter must be within the range
	 * <code>[0..size()-1]</code>, inclusive.  The font attribute of
	 * the element is left unchanged.
	 * 
	 * @param elementNum the index of the element to be set
	 * @param stringPart the string part of the new element