choice.java

SUN官方的资料

     */
    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 <code>null</code>
     * if there is no image
     * @throws IndexOutOfBoundsException if <code>elementNum</code> 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 <code>null</code> if
     * there is no image part
     * @return the assigned index of the element
     * @throws NullPointerException if <code>stringPart</code>
     * is <code>null</code>
     */
    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
     * {@link #append(String, Image) append()}.
     * 
     * @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 <code>null</code> if there is no image part
     * @throws IndexOutOfBoundsException if <code>elementNum</code> is invalid
     * @throws NullPointerException if <code>stringPart</code>
     * is <code>null</code>
     */
    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 <code>elementNum</code> 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 
     * <code>null</code> if there is
     * no image part
     *
     * @throws IndexOutOfBoundsException if <code>elementNum</code> is invalid
     * @throws NullPointerException if <code>stringPart</code> 
     * is <code>null</code>
     */
    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 <code>elementNum</code> 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 {@link #getSelectedFlags(boolean[]) getSelectedFlags}.</p>
     *
     * @return index of selected element, or <code>-1</code> if none
     * @see #setSelectedIndex
     */
    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 <code>Choice</code>
     *
     * @throws IllegalArgumentException if <code>selectedArray_return</code>
     * is shorter than the size of the <code>Choice</code>.
     * @throws NullPointerException if <code>selectedArray_return</code> is
     * <code>null</code>
     * @see #setSelectedFlags
     */
    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 <code>true</code> means
     * selected and <code>false</code> means not selected
     * @throws IndexOutOfBoundsException if <code>elementNum</code> 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 <code>selectedArray</code> is 
     * shorter than the size of the <code>Choice</code>
     * @throws NullPointerException if <code>selectedArray</code> is 
     * <code>null</code>
     * @see #getSelectedFlags
     */
    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
     * {@link #TEXT_WRAP_DEFAULT}, {@link #TEXT_WRAP_ON},
     * and {@link #TEXT_WRAP_OFF}. 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 <code>fitPolicy</code> 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 {@link #TEXT_WRAP_DEFAULT}, {@link #TEXT_WRAP_ON}, or
     * {@link #TEXT_WRAP_OFF}
     * @see #setFitPolicy
     * @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 <code>elementNum</code> is invalid
     * @see #getFont
     * @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 <code>elementNum</code> is invalid
     * @see #setFont
     * @since MIDP 2.0
     */
    public Font getFont(int elementNum);

}