/*
 * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */
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.*;


/**
 * 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:
 *
 * <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"
 * style="float:center; margin: 7px 10px;">
 * <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
 */
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)
 */
 Vector<String> pItems;

 /**
 * 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();
 pItems = new Vector<>();
 }

 /**
 * 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) {
 return pItems.elementAt(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 position 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
 */
 public synchronized ItemListener[] getItemListeners() {
 return getListeners(ItemListener.class);
 }

 /**
 * Returns an array of all the objects currently registered
 * as <code><em>Foo</em>Listener</code>s
 * upon this <code>Choice</code>.
 * <code><em>Foo</em>Listener</code>s are registered using the
 * <code>add<em>Foo</em>Listener</code> method.
 *
 * <p>
 * You can specify the <code>listenerType</code> argument
 * with a class literal, such as
 * <code><em>Foo</em>Listener.class</code>.
 * For example, you can query a
 * <code>Choice</code> <code>c</code>
 * for its item listeners with the following code:
 *
 * <pre>ItemListener[] ils = (ItemListener[])(c.getListeners(ItemListener.class));</pre>
 *
 * If no such listeners exist, this method returns an empty array.
 *
 * @param listenerType the type of listeners requested; this parameter
 * should specify an interface that descends from
 * <code>java.util.EventListener</code>
 * @return an array of all objects registered as
 * <code><em>Foo</em>Listener</code>s on this choice,
 * or an empty array if no such
 * listeners have been added
 * @exception ClassCastException if <code>listenerType</code>
 * doesn't specify a class or interface that implements
 * <code>java.util.EventListener</code>
 *
 * @see #getItemListeners
 * @since 1.3
 */
 public <T extends EventListener> T[] getListeners(Class<T> listenerType) {
 EventListener l = null;
 if (listenerType == ItemListener.class) {
 l = itemListener;
 } else {
 return super.getListeners(listenerType);
 }
 return AWTEventMulticaster.getListeners(l, listenerType);
 }

 // REMIND: remove when filtering is done at lower level
 boolean eventEnabled(AWTEvent e) {
 if (e.id == ItemEvent.ITEM_STATE_CHANGED) {
 if ((eventMask & AWTEvent.ITEM_EVENT_MASK) != 0 ||
 itemListener != null) {
 return true;
 }
 return false;
 }
 return super.eventEnabled(e);
 }

 /**
 * Processes events on this choice. If the event is an
 * instance of <code>ItemEvent</code>, it invokes the
 * <code>processItemEvent</code> method. Otherwise, it calls its
 * superclass's <code>processEvent</code> method.
 * <p>Note that if the event parameter is <code>null</code>
 * the behavior is unspecified and may result in an
 * exception.
 *
 * @param e the event
 * @see java.awt.event.ItemEvent
 * @see #processItemEvent
 * @since JDK1.1
 */
 protected void processEvent(AWTEvent e) {
 if (e instanceof ItemEvent) {
 processItemEvent((ItemEvent)e);
 return;
 }
 super.processEvent(e);
 }

 /**
 * Processes item events occurring on this <code>Choice</code>
 * menu by dispatching them to any registered
 * <code>ItemListener</code> objects.
 * <p>
 * This method is not called unless item events are
 * enabled for this component. Item events are enabled
 * when one of the following occurs:
 * <ul>
 * <li>An <code>ItemListener</code> object is registered
 * via <code>addItemListener</code>.
 * <li>Item events are enabled via <code>enableEvents</code>.
 * </ul>
 * <p>Note that if the event parameter is <code>null</code>
 * the behavior is unspecified and may result in an
 * exception.
 *
 * @param e the item event
 * @see java.awt.event.ItemEvent
 * @see java.awt.event.ItemListener
 * @see #addItemListener(ItemListener)
 * @see java.awt.Component#enableEvents
 * @since JDK1.1
 */
 protected void processItemEvent(ItemEvent e) {
 ItemListener listener = itemListener;
 if (listener != null) {
 listener.itemStateChanged(e);
 }
 }

 /**
 * Returns a string representing the state of this <code>Choice</code>
 * menu. This method is intended to be used only for debugging purposes,
 * and the content and format of the returned string may vary between
 * implementations. The returned string may be empty but may not be
 * <code>null</code>.
 *
 * @return the parameter string of this <code>Choice</code> menu
 */
 protected String paramString() {
 return super.paramString() + ",current=" + getSelectedItem();
 }


 /* Serialization support.
 */

 /*
 * Choice Serial Data Version.
 * @serial
 */
 private int choiceSerializedDataVersion = 1;

 /**
 * Writes default serializable fields to stream. Writes
 * a list of serializable <code>ItemListeners</code>
 * as optional data. The non-serializable
 * <code>ItemListeners</code> are detected and
 * no attempt is made to serialize them.
 *
 * @param s the <code>ObjectOutputStream</code> to write
 * @serialData <code>null</code> terminated sequence of 0
 * or more pairs; the pair consists of a <code>String</code>
 * and an <code>Object</code>; the <code>String</code> indicates
 * the type of object and is one of the following:
 * <code>itemListenerK</code> indicating an
 * <code>ItemListener</code> object
 *
 * @see AWTEventMulticaster#save(ObjectOutputStream, String, EventListener)
 * @see java.awt.Component#itemListenerK
 * @see #readObject(ObjectInputStream)
 */
 private void writeObject(ObjectOutputStream s)
 throws java.io.IOException
 {
 s.defaultWriteObject();

 AWTEventMulticaster.save(s, itemListenerK, itemListener);
 s.writeObject(null);
 }

 /**
 * Reads the <code>ObjectInputStream</code> and if it
 * isn't <code>null</code> adds a listener to receive
 * item events fired by the <code>Choice</code> item.
 * Unrecognized keys or values will be ignored.
 *
 * @param s the <code>ObjectInputStream</code> to read
 * @exception HeadlessException if
 * <code>GraphicsEnvironment.isHeadless</code> returns
 * <code>true</code>
 * @serial
 * @see #removeItemListener(ItemListener)
 * @see #addItemListener(ItemListener)
 * @see java.awt.GraphicsEnvironment#isHeadless
 * @see #writeObject(ObjectOutputStream)
 */
 private void readObject(ObjectInputStream s)
 throws ClassNotFoundException, IOException, HeadlessException
 {
 GraphicsEnvironment.checkHeadless();
 s.defaultReadObject();

 Object keyOrNull;
 while(null != (keyOrNull = s.readObject())) {
 String key = ((String)keyOrNull).intern();

 if (itemListenerK == key)
 addItemListener((ItemListener)(s.readObject()));

 else // skip value for unrecognized key
 s.readObject();
 }
 }

 /**
 * Initialize JNI field and method IDs
 */
 private static native void initIDs();

/////////////////
// Accessibility support
////////////////


 /**
 * Gets the <code>AccessibleContext</code> associated with this
 * <code>Choice</code>. For <code>Choice</code> components,
 * the <code>AccessibleContext</code> takes the form of an
 * <code>AccessibleAWTChoice</code>. A new <code>AccessibleAWTChoice</code>
 * instance is created if necessary.
 *
 * @return an <code>AccessibleAWTChoice</code> that serves as the
 * <code>AccessibleContext</code> of this <code>Choice</code>
 * @since 1.3
 */
 public AccessibleContext getAccessibleContext() {
 if (accessibleContext == null) {
 accessibleContext = new AccessibleAWTChoice();
 }
 return accessibleContext;
 }

 /**
 * This class implements accessibility support for the
 * <code>Choice</code> class. It provides an implementation of the
 * Java Accessibility API appropriate to choice user-interface elements.
 * @since 1.3
 */
 protected class AccessibleAWTChoice extends AccessibleAWTComponent
 implements AccessibleAction
 {
 /*
 * JDK 1.3 serialVersionUID
 */
 private static final long serialVersionUID = 7175603582428509322L;

 public AccessibleAWTChoice() {
 super();
 }

 /**
 * Get the AccessibleAction associated with this object. In the
 * implementation of the Java Accessibility API for this class,
 * return this object, which is responsible for implementing the
 * AccessibleAction interface on behalf of itself.
 *
 * @return this object
 * @see AccessibleAction
 */
 public AccessibleAction getAccessibleAction() {
 return this;
 }

 /**
 * Get the role of this object.
 *
 * @return an instance of AccessibleRole describing the role of the
 * object
 * @see AccessibleRole
 */
 public AccessibleRole getAccessibleRole() {
 return AccessibleRole.COMBO_BOX;
 }

 /**
 * Returns the number of accessible actions available in this object
 * If there are more than one, the first one is considered the "default"
 * action of the object.
 *
 * @return the zero-based number of Actions in this object
 */
 public int getAccessibleActionCount() {
 return 0; // To be fully implemented in a future release
 }

 /**
 * Returns a description of the specified action of the object.
 *
 * @param i zero-based index of the actions
 * @return a String description of the action
 * @see #getAccessibleActionCount
 */
 public String getAccessibleActionDescription(int i) {
 return null; // To be fully implemented in a future release
 }

 /**
 * Perform the specified Action on the object
 *
 * @param i zero-based index of actions
 * @return true if the action was performed; otherwise false.
 * @see #getAccessibleActionCount
 */
 public boolean doAccessibleAction(int i) {
 return false; // To be fully implemented in a future release
 }

 } // inner class AccessibleAWTChoice

}