choice.java

来自「j2me polish学习的经典代码」· Java 代码 · 共 645 行 · 第 1/2 页

	 * 
	 * <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
	 * @param imagePart the image part of the element, or  null if there is no image part
	 * @throws IndexOutOfBoundsException if elementNum is invalid
	 * @throws NullPointerException if stringPart is null
	 */
	public void set(int elementNum, String stringPart, Image imagePart);

	/**
	 * Gets a boolean value indicating whether this element is selected.
	 * 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 selection state of the element
	 * @throws IndexOutOfBoundsException if elementNum is invalid
	 */
	public boolean isSelected(int elementNum);

	/**
	 * Returns the index number of an element in the <code>Choice</code> that is
	 * selected. For
	 * <code>Choice</code> types <code>EXCLUSIVE</code>,
	 * <code>POPUP</code>, and <code>IMPLICIT</code>
	 * there is at most one element selected, so
	 * this method is useful for determining the user's
	 * choice. Returns <code>-1</code> if
	 * the <code>Choice</code> has no elements (and therefore has no
	 * selected elements).
	 * 
	 * <p>For <code>MULTIPLE</code>, this always returns
	 * <code>-1</code> because no single
	 * value can in general represent the state of such a <code>Choice</code>.
	 * To get the complete state of a <code>MULTIPLE</code> <code>Choice</code>,
	 * see <A HREF="../../../javax/microedition/lcdui/Choice.html#getSelectedFlags(boolean[])"><CODE>getSelectedFlags</CODE></A>.</p>
	 * 
	 * @return index of selected element, or -1 if none
	 * @see #setSelectedIndex(int, boolean)
	 */
	public int getSelectedIndex();

	/**
	 * Queries the state of a <code>Choice</code> and returns the
	 * state of all elements
	 * in the
	 * boolean array
	 * <code>selectedArray_return</code>. <strong>Note:</strong> this
	 * is a result parameter.
	 * It must be at least as long as the size
	 * of the <code>Choice</code> as returned by <code>size()</code>.
	 * If the array is longer, the extra
	 * elements are set to <code>false</code>.
	 * 
	 * <p>This call is valid for all types of
	 * <code>Choices</code>. For <code>MULTIPLE</code>, any
	 * number of elements may be selected and set to <code>true</code>
	 * in the result
	 * array. For <code>EXCLUSIVE</code>, <code>POPUP</code>, and
	 * <code>IMPLICIT</code>
	 * exactly one element will be selected (unless there are
	 * zero elements in the <code>Choice</code>). </p>
	 * 
	 * @param selectedArray_return - array to contain the results
	 * @return the number of selected elements in the Choice
	 * @throws IllegalArgumentException - if selectedArray_return is shorter than the size of the Choice.
	 * @throws NullPointerException - if selectedArray_return is null
	 * @see #setSelectedFlags(boolean[])
	 */
	public int getSelectedFlags(boolean[] selectedArray_return);

	/**
	 * For <code>MULTIPLE</code>, this simply sets an individual
	 * element's selected
	 * state.
	 * 
	 * <P>For <code>EXCLUSIVE</code> and <code>POPUP</code>,
	 * this can be used only to select any
	 * element, that is, the <code> selected </code> parameter must be <code>
	 * true </code>. When an element is selected, the previously
	 * selected element
	 * is deselected. If <code> selected </code> is <code> false </code>, this
	 * call is ignored. If element was already selected, the call has
	 * no effect.</P>
	 * 
	 * <P>For <code>IMPLICIT</code>,
	 * this can be used only to select any
	 * element, that is, the <code> selected </code> parameter must be <code>
	 * true </code>. When an element is selected, the previously
	 * selected element
	 * is deselected. If <code> selected </code> is <code> false </code>, this
	 * call is ignored. If element was already selected, the call has
	 * no effect.</P>
	 * 
	 * <P>The call to <code>setSelectedIndex</code> does not cause
	 * implicit activation of
	 * any <code>Command</code>.
	 * </P>
	 * 
	 * <p>For all list types, the <code>elementNum</code> parameter
	 * must be within the range
	 * <code>[0..size()-1]</code>, inclusive. </p>
	 * 
	 * @param elementNum - the index of the element, starting from zero
	 * @param selected - the state of the element, where true means selected and false means not selected
	 * @throws IndexOutOfBoundsException - if elementNum is invalid
	 * @see #getSelectedIndex()
	 */
	public void setSelectedIndex(int elementNum, boolean selected);

	/**
	 * Attempts to set the selected state of every element in the
	 * <code>Choice</code>.
	 * The array
	 * must be at least as long as the size of the
	 * <code>Choice</code>. If the array is
	 * longer, the additional values are ignored.
	 * 
	 * <p>For <code>Choice</code> objects of type
	 * <code>MULTIPLE</code>, this sets the selected
	 * state of every
	 * element in the <code>Choice</code>. An arbitrary number of
	 * elements may be selected.
	 * </p>
	 * 
	 * <p>For <code>Choice</code> objects of type
	 * <code>EXCLUSIVE</code>, <code>POPUP</code>,
	 * and <code>IMPLICIT</code>, exactly one array
	 * element must have the value <code>true</code>. If no element is
	 * <code>true</code>, the
	 * first element
	 * in the <code>Choice</code> will be selected. If two or more
	 * elements are <code>true</code>, the
	 * implementation will choose the first <code>true</code> element
	 * and select it. </p>
	 * 
	 * @param selectedArray - an array in which the method collect the selection status
	 * @throws IllegalArgumentException - if selectedArray is shorter than the size of the Choice
	 * @throws NullPointerException - if selectedArray is null
	 * @see #getSelectedFlags(boolean[])
	 */
	public void setSelectedFlags(boolean[] selectedArray);

	/**
	 * Sets the application's preferred policy for fitting
	 * <code>Choice</code> element
	 * contents to the available screen space. The set policy applies for all
	 * elements of the <code>Choice</code> object.  Valid values 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>. Fit policy is a hint, and the
	 * implementation may disregard the application's preferred policy.
	 * 
	 * @param fitPolicy - preferred content fit policy for choice elements
	 * @throws IllegalArgumentException - if fitPolicy is invalid
	 * @see #getFitPolicy()
	 * @since  MIDP 2.0
	 */
	public void setFitPolicy(int fitPolicy);

	/**
	 * Gets the application's preferred policy for fitting
	 * <code>Choice</code> element
	 * contents to the available screen space.  The value returned is the
	 * policy that had been set by the application, even if that value had
	 * been disregarded by the implementation.
	 * 
	 * @return one of TEXT_WRAP_DEFAULT, TEXT_WRAP_ON, or TEXT_WRAP_OFF
	 * @see #setFitPolicy(int)
	 * @since  MIDP 2.0
	 */
	public int getFitPolicy();

	/**
	 * Sets the application's preferred font for
	 * rendering the specified element of this <code>Choice</code>.
	 * An element's font is a hint, and the implementation may disregard
	 * the application's preferred font.
	 * 
	 * <p> The <code>elementNum</code> parameter must be within the range
	 * <code>[0..size()-1]</code>, inclusive.</p>
	 * 
	 * <p> The <code>font</code> parameter must be a valid <code>Font</code>
	 * object or <code>null</code>. If the <code>font</code> parameter is
	 * <code>null</code>, the implementation must use its default font
	 * to render the element.</p>
	 * 
	 * @param elementNum - the index of the element, starting from zero
	 * @param font - the preferred font to use to render the element
	 * @throws IndexOutOfBoundsException - if elementNum is invalid
	 * @see #getFont(int)
	 * @since  MIDP 2.0
	 */
	public void setFont(int elementNum, Font font);

	/**
	 * Gets the application's preferred font for
	 * rendering the specified element of this <code>Choice</code>. The
	 * value returned is the font that had been set by the application,
	 * even if that value had been disregarded by the implementation.
	 * If no font had been set by the application, or if the application
	 * explicitly set the font to <code>null</code>, the value is the default
	 * font chosen by the implementation.
	 * 
	 * <p> The <code>elementNum</code> parameter must be within the range
	 * <code>[0..size()-1]</code>, inclusive.</p>
	 * 
	 * @param elementNum - the index of the element, starting from zero
	 * @return the preferred font to use to render the element
	 * @throws IndexOutOfBoundsException - if elementNum is invalid
	 * @see #setFont(int, javax.microedition.lcdui.Font)
	 * @since  MIDP 2.0
	 */
	public Font getFont(int elementNum);

}