/*

 * Copyright (c) 1995, 2008, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package java.awt;

import java.util.*;

import java.awt.peer.ChoicePeer;

import java.awt.event.*;

import java.util.EventListener;

import java.io.ObjectOutputStream;

import java.io.ObjectInputStream;

import java.io.IOException;

import javax.accessibility.*;

import javax.tools.annotation.GenerateNativeHeader;

/**

 * The <code>Choice</code> class presents a pop-up menu of choices.

 * The current choice is displayed as the title of the menu.

 * <p>

 * The following code example produces a pop-up menu:

 * <p>

 * <hr><blockquote><pre>

 * Choice ColorChooser = new Choice();

 * ColorChooser.add("Green");

 * ColorChooser.add("Red");

 * ColorChooser.add("Blue");

 * </pre></blockquote><hr>

 * <p>

 * After this choice menu has been added to a panel,

 * it appears as follows in its normal state:

 * <p>

 * <img src="doc-files/Choice-1.gif" alt="The following text describes the graphic"

 * ALIGN=center HSPACE=10 VSPACE=7>

 * <p>

 * In the picture, <code>"Green"</code> is the current choice.

 * Pushing the mouse button down on the object causes a menu to

 * appear with the current choice highlighted.

 * <p>

 * Some native platforms do not support arbitrary resizing of

 * <code>Choice</code> components and the behavior of

 * <code>setSize()/getSize()</code> is bound by

 * such limitations.

 * Native GUI <code>Choice</code> components' size are often bound by such

 * attributes as font size and length of items contained within

 * the <code>Choice</code>.

 * <p>

 * @author      Sami Shaio

 * @author      Arthur van Hoff

 * @since       JDK1.0

 */

/* No native methods here, but the constants are needed in the supporting JNI code */

@GenerateNativeHeader

public class Choice extends Component implements ItemSelectable, Accessible {

    /**

     * The items for the <code>Choice</code>.

     * This can be a <code>null</code> value.

     * @serial

     * @see #add(String)

     * @see #addItem(String)

     * @see #getItem(int)

     * @see #getItemCount()

     * @see #insert(String, int)

     * @see #remove(String)

     */

    /**

     * The index of the current choice for this <code>Choice</code>

     * or -1 if nothing is selected.

     * @serial

     * @see #getSelectedItem()

     * @see #select(int)

     */

    int selectedIndex = -1;

    transient ItemListener itemListener;

    private static final String base = "choice";

    private static int nameCounter = 0;

    /*

     * JDK 1.1 serialVersionUID

     */

    private static final long serialVersionUID = -4075310674757313071L;

    static {

        /* ensure that the necessary native libraries are loaded */

        Toolkit.loadLibraries();

        /* initialize JNI field and method ids */

        if (!GraphicsEnvironment.isHeadless()) {

            initIDs();

        }

    }

    /**

     * Creates a new choice menu. The menu initially has no items in it.

     * <p>

     * By default, the first item added to the choice menu becomes the

     * selected item, until a different selection is made by the user

     * by calling one of the <code>select</code> methods.

     * @exception HeadlessException if GraphicsEnvironment.isHeadless()

     * returns true

     * @see       java.awt.GraphicsEnvironment#isHeadless

     * @see       #select(int)

     * @see       #select(java.lang.String)

     */

    public Choice() throws HeadlessException {

        GraphicsEnvironment.checkHeadless();

    }

    /**

     * Constructs a name for this component.  Called by

     * <code>getName</code> when the name is <code>null</code>.

     */

    String constructComponentName() {

        synchronized (Choice.class) {

            return base + nameCounter++;

        }

    }

    /**

     * Creates the <code>Choice</code>'s peer.  This peer allows us

     * to change the look

     * of the <code>Choice</code> without changing its functionality.

     * @see     java.awt.Toolkit#createChoice(java.awt.Choice)

     * @see     java.awt.Component#getToolkit()

     */

    public void addNotify() {

        synchronized (getTreeLock()) {

            if (peer == null)

                peer = getToolkit().createChoice(this);

            super.addNotify();

        }

    }

    /**

     * Returns the number of items in this <code>Choice</code> menu.

     * @return the number of items in this <code>Choice</code> menu

     * @see     #getItem

     * @since   JDK1.1

     */

    public int getItemCount() {

        return countItems();

    }

    /**

     * @deprecated As of JDK version 1.1,

     * replaced by <code>getItemCount()</code>.

     */

    @Deprecated

    public int countItems() {

        return pItems.size();

    }

    /**

     * Gets the string at the specified index in this

     * <code>Choice</code> menu.

     * @param      index the index at which to begin

     * @see        #getItemCount

     */

    public String getItem(int index) {

        return getItemImpl(index);

    }

    /*

     * This is called by the native code, so client code can't

     * be called on the toolkit thread.

     */

    final String getItemImpl(int index) {

    }

    /**

     * Adds an item to this <code>Choice</code> menu.

     * @param      item    the item to be added

     * @exception  NullPointerException   if the item's value is

     *                  <code>null</code>

     * @since      JDK1.1

     */

    public void add(String item) {

        addItem(item);

    }

    /**

     * Obsolete as of Java 2 platform v1.1.  Please use the

     * <code>add</code> method instead.

     * <p>

     * Adds an item to this <code>Choice</code> menu.

     * @param item the item to be added

     * @exception NullPointerException if the item's value is equal to

     *          <code>null</code>

     */

    public void addItem(String item) {

        synchronized (this) {

            insertNoInvalidate(item, pItems.size());

        }

        // This could change the preferred size of the Component.

        invalidateIfValid();

    }

    /**

     * Inserts an item to this <code>Choice</code>,

     * but does not invalidate the <code>Choice</code>.

     * Client methods must provide their own synchronization before

     * invoking this method.

     * @param item the item to be added

     * @param index the new item position

     * @exception NullPointerException if the item's value is equal to

     *          <code>null</code>

     */

    private void insertNoInvalidate(String item, int index) {

        if (item == null) {

            throw new

                NullPointerException("cannot add null item to Choice");

        }

        pItems.insertElementAt(item, index);

        ChoicePeer peer = (ChoicePeer)this.peer;

        if (peer != null) {

            peer.add(item, index);

        }

        // no selection or selection shifted up

        if (selectedIndex < 0 || selectedIndex >= index) {

            select(0);

        }

    }

    /**

     * Inserts the item into this choice at the specified position.

     * Existing items at an index greater than or equal to

     * <code>index</code> are shifted up by one to accommodate

     * the new item.  If <code>index</code> is greater than or

     * equal to the number of items in this choice,

     * <code>item</code> is added to the end of this choice.

     * <p>

     * If the item is the first one being added to the choice,

     * then the item becomes selected.  Otherwise, if the

     * selected item was one of the items shifted, the first

     * item in the choice becomes the selected item.  If the

     * selected item was no among those shifted, it remains

     * the selected item.

     * @param item the non-<code>null</code> item to be inserted

     * @param index the position at which the item should be inserted

     * @exception IllegalArgumentException if index is less than 0

     */

    public void insert(String item, int index) {

        synchronized (this) {

            if (index < 0) {

                throw new IllegalArgumentException("index less than zero.");

            }

            /* if the index greater than item count, add item to the end */

            index = Math.min(index, pItems.size());

            insertNoInvalidate(item, index);

        }

        // This could change the preferred size of the Component.

        invalidateIfValid();

    }

    /**

     * Removes the first occurrence of <code>item</code>

     * from the <code>Choice</code> menu.  If the item

     * being removed is the currently selected item,

     * then the first item in the choice becomes the

     * selected item.  Otherwise, the currently selected

     * item remains selected (and the selected index is

     * updated accordingly).

     * @param      item  the item to remove from this <code>Choice</code> menu

     * @exception  IllegalArgumentException  if the item doesn't

     *                     exist in the choice menu

     * @since      JDK1.1

     */

    public void remove(String item) {

        synchronized (this) {

            int index = pItems.indexOf(item);

            if (index < 0) {

                throw new IllegalArgumentException("item " + item +

                                                   " not found in choice");

            } else {

                removeNoInvalidate(index);

            }

        }

        // This could change the preferred size of the Component.

        invalidateIfValid();

    }

    /**

     * Removes an item from the choice menu

     * at the specified position.  If the item

     * being removed is the currently selected item,

     * then the first item in the choice becomes the

     * selected item.  Otherwise, the currently selected

     * item remains selected (and the selected index is

     * updated accordingly).

     * @param      position the position of the item

     * @throws IndexOutOfBoundsException if the specified

     *          position is out of bounds

     * @since      JDK1.1

     */

    public void remove(int position) {

        synchronized (this) {

            removeNoInvalidate(position);

        }

        // This could change the preferred size of the Component.

        invalidateIfValid();

    }

    /**

     * Removes an item from the <code>Choice</code> at the

     * specified position, but does not invalidate the <code>Choice</code>.

     * Client methods must provide their

     * own synchronization before invoking this method.

     * @param      position   the position of the item

     */

    private void removeNoInvalidate(int position) {

        pItems.removeElementAt(position);

        ChoicePeer peer = (ChoicePeer)this.peer;

        if (peer != null) {

            peer.remove(position);

        }

        /* Adjust selectedIndex if selected item was removed. */

        if (pItems.size() == 0) {

            selectedIndex = -1;

        } else if (selectedIndex == position) {

            select(0);

        } else if (selectedIndex > position) {

            select(selectedIndex-1);

        }

    }

    /**

     * Removes all items from the choice menu.

     * @see       #remove

     * @since     JDK1.1

     */

    public void removeAll() {

        synchronized (this) {

            if (peer != null) {

                ((ChoicePeer)peer).removeAll();

            }

            pItems.removeAllElements();

            selectedIndex = -1;

        }

        // This could change the preferred size of the Component.

        invalidateIfValid();

    }

    /**

     * Gets a representation of the current choice as a string.

     * @return    a string representation of the currently

     *                     selected item in this choice menu

     * @see       #getSelectedIndex

     */

    public synchronized String getSelectedItem() {

        return (selectedIndex >= 0) ? getItem(selectedIndex) : null;

    }

    /**

     * Returns an array (length 1) containing the currently selected

     * item.  If this choice has no items, returns <code>null</code>.

     * @see ItemSelectable

     */

    public synchronized Object[] getSelectedObjects() {

        if (selectedIndex >= 0) {

            Object[] items = new Object[1];

            items[0] = getItem(selectedIndex);

            return items;

        }

        return null;

    }

    /**

     * Returns the index of the currently selected item.

     * If nothing is selected, returns -1.

     *

     * @return the index of the currently selected item, or -1 if nothing

     *  is currently selected

     * @see #getSelectedItem

     */

    public int getSelectedIndex() {

        return selectedIndex;

    }

    /**

     * Sets the selected item in this <code>Choice</code> menu to be the

     * item at the specified position.

     *

     * <p>Note that this method should be primarily used to

     * initially select an item in this component.

     * Programmatically calling this method will <i>not</i> trigger

     * an <code>ItemEvent</code>.  The only way to trigger an

     * <code>ItemEvent</code> is by user interaction.

     *

     * @param      pos      the positon of the selected item

     * @exception  IllegalArgumentException if the specified

     *                            position is greater than the

     *                            number of items or less than zero

     * @see        #getSelectedItem

     * @see        #getSelectedIndex

     */

    public synchronized void select(int pos) {

        if ((pos >= pItems.size()) || (pos < 0)) {

            throw new IllegalArgumentException("illegal Choice item position: " + pos);

        }

        if (pItems.size() > 0) {

            selectedIndex = pos;

            ChoicePeer peer = (ChoicePeer)this.peer;

            if (peer != null) {

                peer.select(pos);

            }

        }

    }

    /**

     * Sets the selected item in this <code>Choice</code> menu

     * to be the item whose name is equal to the specified string.

     * If more than one item matches (is equal to) the specified string,

     * the one with the smallest index is selected.

     *

     * <p>Note that this method should be primarily used to

     * initially select an item in this component.

     * Programmatically calling this method will <i>not</i> trigger

     * an <code>ItemEvent</code>.  The only way to trigger an

     * <code>ItemEvent</code> is by user interaction.

     *

     * @param       str     the specified string

     * @see         #getSelectedItem

     * @see         #getSelectedIndex

     */

    public synchronized void select(String str) {

        int index = pItems.indexOf(str);

        if (index >= 0) {

            select(index);

        }

    }

    /**

     * Adds the specified item listener to receive item events from

     * this <code>Choice</code> menu.  Item events are sent in response

     * to user input, but not in response to calls to <code>select</code>.

     * If l is <code>null</code>, no exception is thrown and no action

     * is performed.

     * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"

     * >AWT Threading Issues</a> for details on AWT's threading model.

     * @param         l    the item listener

     * @see           #removeItemListener

     * @see           #getItemListeners

     * @see           #select

     * @see           java.awt.event.ItemEvent

     * @see           java.awt.event.ItemListener

     * @since         JDK1.1

     */

    public synchronized void addItemListener(ItemListener l) {

        if (l == null) {

           return;

        }

        itemListener = AWTEventMulticaster.add(itemListener, l);

        newEventsOnly = true;

    }

    /**

     * Removes the specified item listener so that it no longer receives

     * item events from this <code>Choice</code> menu.

     * If l is <code>null</code>, no exception is thrown and no

     * action is performed.

     * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"

     * >AWT Threading Issues</a> for details on AWT's threading model.

     * @param         l    the item listener

     * @see           #addItemListener

     * @see           #getItemListeners

     * @see           java.awt.event.ItemEvent

     * @see           java.awt.event.ItemListener

     * @since         JDK1.1

     */

    public synchronized void removeItemListener(ItemListener l) {

        if (l == null) {

            return;

        }

        itemListener = AWTEventMulticaster.remove(itemListener, l);

    }

    /**

     * Returns an array of all the item listeners

     * registered on this choice.

     *

     * @return all of this choice's <code>ItemListener</code>s

     *         or an empty array if no item

     *         listeners are currently registered

     *

     * @see           #addItemListener

     * @see           #removeItemListener

     * @see           java.awt.event.ItemEvent

     * @see           java.awt.event.ItemListener

     * @since 1.4