choicegroup.java

用于移动设备上的java虚拟机源代码

/*
 * @(#)ChoiceGroup.java	1.211 02/10/15 @(#)
 *
 * Copyright (c) 1999-2002 Sun Microsystems, Inc.  All rights reserved.
 * PROPRIETARY/CONFIDENTIAL
 * Use is subject to license terms.
 */

package javax.microedition.lcdui;
import com.sun.midp.lcdui.Text;
import com.sun.midp.lcdui.*;

/**
 * A <code>ChoiceGroup</code> is a group of selectable elements intended to be
 * placed within a
 * {@link Form}. The group may be created with a mode that requires a
 * single choice to be made or that allows multiple choices. The
 * implementation is responsible for providing the graphical representation of
 * these modes and must provide visually different graphics for different
 * modes. For example, it might use &quot;radio buttons&quot; for the
 * single choice
 * mode and &quot;check boxes&quot; for the multiple choice mode.
 *
 * <p> <strong>Note:</strong> most of the essential methods have been
 * specified in the {@link Choice Choice} interface.</p>
 * @since MIDP 1.0
 */

public class ChoiceGroup extends Item implements Choice {
    /**
     * If a List is using this ChoiceGroup, it will set isList to true
     */
    boolean isList;

    /**
     * The type of this ChoiceGroup
     */
    private int choiceType;

    /**
     * The string fit policy for this ChoiceGroup
     * '0' by default, which is Choice.TEXT_WRAP_DEFAULT
     */
    private int fitPolicy;
    /*
     * NOTE:  If this is a POPUP choice group, regardless of
     * the set fit policy the system will behave as though
     * fitPolicy == Choice.TEXT_WRAP_OFF.  Popup choice elements
     * will never wrap, and may be truncated.
     */

    /**
     * The number of elements in this ChoiceGroup
     */
    private int numOfEls;

    /**
     * The currently selected index of this ChoiceGroup (-1 by default)
     */
    private int selectedIndex = -1;

    /**
     * The currently highlighted index of this ChoiceGroup (-1 by default)
     */
    private int hilightedIndex = -1;

    /**
     * The array of selected elements of this ChoiceGroup (in the case
     * of a multi-select type)
     */
    private boolean selEls[];

    /**
     * The array containing the String parts of each element
     */
    private String[] stringEls;

    /**
     * The array containing the Image parts of each element (null unless
     * there are Image parts)
     */
    private Image[] imageEls;

    /**
     * The array containing mutable Image parts of each element (null unless
     * there are mutable Image parts)
     */
    private Image[] mutableImageEls;

    /**
     * The array containing the Font of each element (null if no setFont()
     * method was ever called). If fontEls is non-null, only the elements
     * which were set by setFont() are non-null.
     */
    private Font[] fontEls;

    /**
     * The array containing the individual heights of each element, based
     * on the preferred layout width
     */
    private int[] elHeights;

    /**
     * The cachedWidth is the width used to calculate the height of each
     * element. If a different width is passed into paint(), we need
     * to recalculate the heights of the elements.
     */
    private int cachedWidth;

    /**
     * By default, a ChoiceGroup is 80 pixels wide
     */
    private static final int DEFAULT_WIDTH = 80;

    /**
     * The state of the popup ChoiceGroup (false by default)
     */
    private boolean popUpOpen;

    /**
     * A flag indicating if traversal has occurred into this
     * CG on a prior callTraverse. Its reset to false again
     * in callTraverseOut().
     */
    private boolean traversedIn;

    /**
     * The DisplayManager object handling the display events.
     * Used to suspend/resume display updates when an open
     * popup choice group is on screen.
     */
    private DisplayManager displayManager;

    /**
     * Max width of requested popup menu
     */
    private int maxPopupWidth = DEFAULT_WIDTH;

    /**
     * Creates a new, empty <code>ChoiceGroup</code>, specifying its
     * title and its type.
     * The type must be one of <code>EXCLUSIVE</code>,
     * <code>MULTIPLE</code>, or <code>POPUP</code>. The
     * <code>IMPLICIT</code>
     * choice type is not allowed within a <code>ChoiceGroup</code>.
     *
     * @param label the item's label (see {@link Item Item})
     * @param choiceType <code>EXCLUSIVE</code>, <code>MULTIPLE</code>, 
     * or <code>POPUP</code>
     * @throws IllegalArgumentException if <code>choiceType</code> is not one of
     * <code>EXCLUSIVE</code>, <code>MULTIPLE</code>, or <code>POPUP</code>
     * @see Choice#EXCLUSIVE
     * @see Choice#MULTIPLE
     * @see Choice#IMPLICIT
     * @see Choice#POPUP
     */
    public ChoiceGroup(String label, int choiceType) {
        this(label, choiceType, new String[] {}, null);
    }
    
    /**
     * Creates a new <code>ChoiceGroup</code>, specifying its title,
     * the type of the
     * <code>ChoiceGroup</code>, and an array of <code>Strings</code>
     * and <code>Images</code> to be used as its
     * initial contents. 
     *
     * <p>The type must be one of <code>EXCLUSIVE</code>,
     * <code>MULTIPLE</code>, or <code>POPUP</code>.  The
     * <code>IMPLICIT</code>
     * type is not allowed for <code>ChoiceGroup</code>.</p>
     *
     * <p>The <code>stringElements</code> array must be non-null and
     * every array element
     * must also be non-null.  The length of the
     * <code>stringElements</code> array
     * determines the number of elements in the <code>ChoiceGroup</code>.  The 
     * <code>imageElements</code> array
     * may be <code>null</code> to indicate that the
     * <code>ChoiceGroup</code> elements have no images.
     * If the
     * <code>imageElements</code> array is non-null, it must be the
     * same length as the
     * <code>stringElements</code> array.  Individual elements of the
     * <code>imageElements</code> array
     * may be <code>null</code> in order to indicate the absence of an
     * image for the
     * corresponding <code>ChoiceGroup</code> element.  Non-null elements
     * of the
     * <code>imageElements</code> array may refer to mutable or
     * immutable images.</p>
     * 
     * @param label the item's label (see {@link Item Item})
     * @param choiceType <code>EXCLUSIVE</code>, <code>MULTIPLE</code>,
     * or <code>POPUP</code>
     * @param stringElements set of strings specifying the string parts of the 
     * <code>ChoiceGroup</code> elements
     * @param imageElements set of images specifying the image parts of
     * the <code>ChoiceGroup</code> elements
     *
     * @throws NullPointerException if <code>stringElements</code> 
     * is <code>null</code>
     * @throws NullPointerException if the <code>stringElements</code>
     * array contains
     * any <code>null</code> elements
     * @throws IllegalArgumentException if the <code>imageElements</code>
     * array is non-null 
     * and has a different length from the <code>stringElements</code> array
     * @throws IllegalArgumentException if <code>choiceType</code> is not one of
     * <code>EXCLUSIVE</code>, <code>MULTIPLE</code>, or <code>POPUP</code>
     * 
     * @see Choice#EXCLUSIVE
     * @see Choice#MULTIPLE
     * @see Choice#IMPLICIT
     * @see Choice#POPUP
     */
    public ChoiceGroup(String label, int choiceType, 
                       String[] stringElements, Image[] imageElements) {

        this(label, choiceType, stringElements, imageElements, false);
    }
    
    /**
     * Special constructor used by List
     *
     * @param label the item's label (see {@link Item Item})
     * @param choiceType EXCLUSIVE or MULTIPLE
     * @param stringElements set of strings specifying the string parts of the
     * ChoiceGroup elements
     * @param imageElements set of images specifying the image parts of
     * the ChoiceGroup elements
     * @param implicitAllowed Flag to allow implicit selection
     *
     * @throws NullPointerException if stringElements is null
     * @throws NullPointerException if the stringElements array contains
     * any null elements
     * @throws IllegalArgumentException if the imageElements array is non-null
     * and has a different length from the stringElements array
     * @throws IllegalArgumentException if choiceType is neither
     * EXCLUSIVE nor MULTIPLE
     * @throws IllegalArgumentException if any image in the imageElements
     * array is mutable
     *
     * @see Choice#EXCLUSIVE
     * @see Choice#MULTIPLE
     * @see Choice#IMPLICIT
     */
    ChoiceGroup(String label, int choiceType, String[] stringElements,
            Image[] imageElements, boolean implicitAllowed) {

        super(label);
        
        if (displayManager == null) {
            displayManager = DisplayManagerFactory.getDisplayManager();
        }

        if (!((choiceType == Choice.MULTIPLE) ||
                (choiceType == Choice.EXCLUSIVE) ||
                ((choiceType == Choice.IMPLICIT) && implicitAllowed) ||
                (choiceType == Choice.POPUP))) {
            throw new IllegalArgumentException();
        }

        // If stringElements is null NullPointerException will be thrown
        // as expected
        for (int x = 0; x < stringElements.length; x++) {
            if (stringElements[x] == null) {
                throw new NullPointerException();
            }
        }

        if (imageElements != null) {
            if (stringElements.length != imageElements.length) {
                throw new IllegalArgumentException();
            }
        }

        synchronized (Display.LCDUILock) {
            this.choiceType = choiceType;
            numOfEls = stringElements.length;

            switch (choiceType) {
                case Choice.MULTIPLE:
                    selEls = new boolean[numOfEls];
                    for (int i = 0; i < numOfEls; i++) {
                        selEls[i] = false;
                    }
                    break;
                case Choice.POPUP:
                case Choice.IMPLICIT:
                case Choice.EXCLUSIVE:
                    if (numOfEls > 0) {
                        selectedIndex = 0;
                    }
                    break;
            }

            stringEls = new String[numOfEls];
            System.arraycopy(stringElements, 0, stringEls, 0, numOfEls);

            if (imageElements != null) {
                imageEls        = new Image[numOfEls];
                mutableImageEls = new Image[numOfEls];

                // Need to check each and every Image to see if it's mutable
                for (int i = 0; i < numOfEls; i++) {
                    if (imageElements[i] != null &&
                        imageElements[i].isMutable()) {
                        // Save original, mutable Image
                        mutableImageEls[i] = imageElements[i];
                        // Create a snapshot for display
                        imageEls[i] = Image.createImage(imageElements[i]);
                    } else {
                        // Save the immutable image for display
                        imageEls[i] = imageElements[i];
                    }
                }
            }
            hilightedIndex = 0;
        } // synchronized
    }

    /**
     * Returns the number of elements in the <code>ChoiceGroup</code>.
     * @return the number of elements in the <code>ChoiceGroup</code>
     */
    public int size() {
        // SYNC NOTE: return of atomic value, no locking necessary
        return numOfEls;
    }

    /**
     * Gets the <code>String</code> part of the element referenced by
     * <code>elementNum</code>.
     * 
     * @param elementNum the index of the element to be queried
     * @return the string part of the element
     * @throws IndexOutOfBoundsException if <code>elementNum</code> is invalid
     * @see #getImage(int)
     */
    public String getString(int elementNum) {
        synchronized (Display.LCDUILock) {
            checkIndex(elementNum);
            return stringEls[elementNum];
        }
    }

    /**
     * Gets the <code>Image</code> part of the element referenced by
     * <code>elementNum</code>.
     *
     * @param elementNum the number 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) {
        synchronized (Display.LCDUILock) {
            checkIndex(elementNum);
            if (imageEls != null) {
                if (mutableImageEls[elementNum] != null) {
                    // This element has a mutable Image
                    return mutableImageEls[elementNum];
                }
                // This element does not have a mutable Image
                return imageEls[elementNum];
            }
            // This element does not have any Image
            return null;
        }
    }

    /**
     * Appends an element to the <code>ChoiceGroup</code>.
     * 
     * @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) {
        int returnVal = -1;

        synchronized (Display.LCDUILock) {
            checkNull(stringPart, imagePart);
            returnVal = insertImpl(numOfEls, stringPart, imagePart);
        }
        return returnVal;
    }

    /**
     * Inserts an element into the <code>ChoiceGroup</code> just prior to
     * the element specified.
     * 
     * @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) {
        
        synchronized (Display.LCDUILock) {
            if (elementNum < 0 || elementNum > numOfEls) {
                throw new IndexOutOfBoundsException();
            }
            checkNull(stringPart, imagePart);
            insertImpl(elementNum, stringPart, imagePart);
        }
    }

    /**
     * Deletes the element referenced by <code>elementNum</code>.
     * 
     * @param elementNum the index of the element to be deleted
     * @throws IndexOutOfBoundsException if <code>elementNum</code> is invalid
     */
    public void delete(int elementNum) {
        synchronized (Display.LCDUILock) {
            checkIndex(elementNum);

            if (elementNum != numOfEls - 1) {

                System.arraycopy(stringEls, elementNum + 1, stringEls,
                                 elementNum, numOfEls - elementNum - 1);

                if (imageEls != null) {
                    // Delete Image snapshot
                    System.arraycopy(imageEls, elementNum + 1, imageEls,
                                     elementNum, numOfEls - elementNum - 1);
                    // Delete mutable Image
                    System.arraycopy(mutableImageEls, elementNum + 1,
                                     mutableImageEls, elementNum,