choice.java

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

     * @throws NullPointerException if stringPart is null
     */
    public int append(String stringPart, Image imagePart);

    /**
     * <p>Inserts an element into the Choice just prior to the
     *  element specified.
     * The size of the Choice grows by one.
     * The elementNum parameter must be within the range
     * [0..size()], inclusive.  The index of the last element is size()-1, and 
     * so there is actually no element whose index is size(). If this value
     * is used for elementNum, the new element is inserted immediately after
     * the last element. In this case, the effect is identical to
     * {@link #append(String, Image) append()}.
     * </p>
     * 
     * @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 IllegalArgumentException if the image is mutable
     * @throws NullPointerException if stringPart is null
     */
    public void insert(int elementNum, String stringPart, Image imagePart);

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

    /**
     * <p>Sets the element referenced by elementNum to the specified element,
     * replacing the previous contents of the element.
     * The elementNum parameter must be within the range
     * [0..size()-1], inclusive. </p>
     * 
     * @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 IllegalArgumentException if the image is mutable
     * @throws NullPointerException if stringPart is null
     */
    public void set(int elementNum, String stringPart, Image imagePart);

    /**
     * <p>Gets a boolean value indicating whether this element is selected.
     * The elementNum parameter must be within the range
     * [0..size()-1], inclusive. </p>
     *
     * @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);

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

    /**
     * <p>Queries the state of a Choice and returns the state
     * of all elements in the
     * boolean array selectedArray_return. NOTE: this is a result parameter.
     * It must be at least as long as the size
     * of the Choice as returned by size().
     * If the array is longer, the extra
     * elements are set to false.</p>
     * 
     * <p>This call is valid for all types of Choices. For MULTIPLE, any
     * number of elements may be selected and set to true in the result
     * array. For EXCLUSIVE and IMPLICIT
     * exactly one element will be selected (unless there are
     * zero elements in the Choice). </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
     */
    public int getSelectedFlags(boolean[] selectedArray_return);

    /**
     * <P>For MULTIPLE, this simply sets an individual element's selected
     * state. </P>
     *
     * <P>For EXCLUSIVE,
     * 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 IMPLICIT,
     * 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 setSelectedIndex does not cause implicit activation of
     * any Command.
     * </P>
     *
     * <p>For all list types, the elementNum parameter must be within the range
     * [0..size()-1], inclusive. </p>
     * 
     * @param elementNum the index of the element, starting from zero
     * @param selected the state of the element, where <code>true</code> means
     * selected and <code>false</code> means not selected
     * @throws IndexOutOfBoundsException if elementNum is invalid
     *
     * @see #getSelectedIndex
     */
    public void setSelectedIndex(int elementNum, boolean selected);

    /**
     * <p>Attempts to set the selected state of every element in the
     * Choice. The array
     * must be at least as long as the size of the Choice. If the array is
     * longer, the additional values are ignored. </p>
     *
     * <p>For Choice objects of type MULTIPLE, this sets the selected 
     * state of every
     * element in the Choice. An arbitrary number of elements may be selected.
     * </p>
     *
     * <p>For Choice objects of type EXCLUSIVE and IMPLICIT, exactly one array
     * element must have the value true. If no element is true,
     * the first element
     * in the Choice will be selected. If two or more elements are true, the
     * implementation will choose the first true 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
     */
    public void setSelectedFlags(boolean[] selectedArray);
}