/*

 * Copyright (c) 1995, 2007, 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.Vector;

import java.util.Locale;

import java.util.EventListener;

import java.awt.peer.ListPeer;

import java.awt.event.*;

import java.io.ObjectOutputStream;

import java.io.ObjectInputStream;

import java.io.IOException;

import javax.accessibility.*;

/**

 * The <code>List</code> component presents the user with a

 * scrolling list of text items. The list can be set up so that

 * the user can choose either one item or multiple items.

 * <p>

 * For example, the code . . .

 * <p>

 * <hr><blockquote><pre>

 * List lst = new List(4, false);

 * lst.add("Mercury");

 * lst.add("Venus");

 * lst.add("Earth");

 * lst.add("JavaSoft");

 * lst.add("Mars");

 * lst.add("Jupiter");

 * lst.add("Saturn");

 * lst.add("Uranus");

 * lst.add("Neptune");

 * lst.add("Pluto");

 * cnt.add(lst);

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

 * <p>

 * where <code>cnt</code> is a container, produces the following

 * scrolling list:

 * <p>

 * <img src="doc-files/List-1.gif"

 * alt="Shows a list containing: Venus, Earth, JavaSoft, and Mars. Javasoft is selected." ALIGN=center HSPACE=10 VSPACE=7>

 * <p>

 * If the List allows multiple selections, then clicking on

 * an item that is already selected deselects it. In the preceding

 * example, only one item from the scrolling list can be selected

 * at a time, since the second argument when creating the new scrolling

 * list is <code>false</code>. If the List does not allow multiple

 * selections, selecting an item causes any other selected item

 * to be deselected.

 * <p>

 * Note that the list in the example shown was created with four visible

 * rows.  Once the list has been created, the number of visible rows

 * cannot be changed.  A default <code>List</code> is created with

 * four rows, so that <code>lst = new List()</code> is equivalent to

 * <code>list = new List(4, false)</code>.

 * <p>

 * Beginning with Java 1.1, the Abstract Window Toolkit

 * sends the <code>List</code> object all mouse, keyboard, and focus events

 * that occur over it. (The old AWT event model is being maintained

 * only for backwards compatibility, and its use is discouraged.)

 * <p>

 * When an item is selected or deselected by the user, AWT sends an instance

 * of <code>ItemEvent</code> to the list.

 * When the user double-clicks on an item in a scrolling list,

 * AWT sends an instance of <code>ActionEvent</code> to the

 * list following the item event. AWT also generates an action event

 * when the user presses the return key while an item in the

 * list is selected.

 * <p>

 * If an application wants to perform some action based on an item

 * in this list being selected or activated by the user, it should implement

 * <code>ItemListener</code> or <code>ActionListener</code>

 * as appropriate and register the new listener to receive

 * events from this list.

 * <p>

 * For multiple-selection scrolling lists, it is considered a better

 * user interface to use an external gesture (such as clicking on a

 * button) to trigger the action.

 * @author      Sami Shaio

 * @see         java.awt.event.ItemEvent

 * @see         java.awt.event.ItemListener

 * @see         java.awt.event.ActionEvent

 * @see         java.awt.event.ActionListener

 * @since       JDK1.0

 */

public class List extends Component implements ItemSelectable, Accessible {

    /**

     * A vector created to contain items which will become

     * part of the List Component.

     *

     * @serial

     * @see #addItem(String)

     * @see #getItem(int)

     */

    Vector<String>      items = new Vector<>();

    /**

     * This field will represent the number of visible rows in the

     * <code>List</code> Component.  It is specified only once, and

     * that is when the list component is actually

     * created.  It will never change.

     *

     * @serial

     * @see #getRows()

     */

    int         rows = 0;

    /**

     * <code>multipleMode</code> is a variable that will

     * be set to <code>true</code> if a list component is to be set to

     * multiple selection mode, that is where the user can

     * select more than one item in a list at one time.

     * <code>multipleMode</code> will be set to false if the

     * list component is set to single selection, that is where

     * the user can only select one item on the list at any

     * one time.

     *

     * @serial

     * @see #isMultipleMode()

     * @see #setMultipleMode(boolean)

     */

    boolean     multipleMode = false;

    /**

     * <code>selected</code> is an array that will contain

     * the indices of items that have been selected.

     *

     * @serial

     * @see #getSelectedIndexes()

     * @see #getSelectedIndex()

     */

    int         selected[] = new int[0];

    /**

     * This variable contains the value that will be used

     * when trying to make a particular list item visible.

     *

     * @serial

     * @see #makeVisible(int)

     */

    int         visibleIndex = -1;

    transient ActionListener actionListener;

    transient ItemListener itemListener;

    private static final String base = "list";

    private static int nameCounter = 0;

    /*

     * JDK 1.1 serialVersionUID

     */

     private static final long serialVersionUID = -3304312411574666869L;

    /**

     * Creates a new scrolling list.

     * By default, there are four visible lines and multiple selections are

     * not allowed.  Note that this is a convenience method for

     * <code>List(0, false)</code>.  Also note that the number of visible

     * lines in the list cannot be changed after it has been created.

     * @exception HeadlessException if GraphicsEnvironment.isHeadless()

     * returns true.

     * @see java.awt.GraphicsEnvironment#isHeadless

     */

    public List() throws HeadlessException {

        this(0, false);

    }

    /**

     * Creates a new scrolling list initialized with the specified

     * number of visible lines. By default, multiple selections are

     * not allowed.  Note that this is a convenience method for

     * <code>List(rows, false)</code>.  Also note that the number

     * of visible rows in the list cannot be changed after it has

     * been created.

     * @param       rows the number of items to show.

     * @exception HeadlessException if GraphicsEnvironment.isHeadless()

     * returns true.

     * @see java.awt.GraphicsEnvironment#isHeadless

     * @since       JDK1.1

     */

    public List(int rows) throws HeadlessException {

        this(rows, false);

    }

    /**

     * The default number of visible rows is 4.  A list with

     * zero rows is unusable and unsightly.

     */

    final static int    DEFAULT_VISIBLE_ROWS = 4;

    /**

     * Creates a new scrolling list initialized to display the specified

     * number of rows. Note that if zero rows are specified, then

     * the list will be created with a default of four rows.

     * Also note that the number of visible rows in the list cannot

     * be changed after it has been created.

     * If the value of <code>multipleMode</code> is

     * <code>true</code>, then the user can select multiple items from

     * the list. If it is <code>false</code>, only one item at a time

     * can be selected.

     * @param       rows   the number of items to show.

     * @param       multipleMode   if <code>true</code>,

     *                     then multiple selections are allowed;

     *                     otherwise, only one item can be selected at a time.

     * @exception HeadlessException if GraphicsEnvironment.isHeadless()

     * returns true.

     * @see java.awt.GraphicsEnvironment#isHeadless

     */

    public List(int rows, boolean multipleMode) throws HeadlessException {

        GraphicsEnvironment.checkHeadless();

        this.rows = (rows != 0) ? rows : DEFAULT_VISIBLE_ROWS;

        this.multipleMode = multipleMode;

    }

    /**

     * Construct a name for this component.  Called by

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

     */

    String constructComponentName() {

        synchronized (List.class) {

            return base + nameCounter++;

        }

    }

    /**

     * Creates the peer for the list.  The peer allows us to modify the

     * list's appearance without changing its functionality.

     */

    public void addNotify() {

        synchronized (getTreeLock()) {

            if (peer == null)

                peer = getToolkit().createList(this);

            super.addNotify();

        }

    }

    /**

     * Removes the peer for this list.  The peer allows us to modify the

     * list's appearance without changing its functionality.

     */

    public void removeNotify() {

        synchronized (getTreeLock()) {

            ListPeer peer = (ListPeer)this.peer;

            if (peer != null) {

                selected = peer.getSelectedIndexes();

            }

            super.removeNotify();

        }

    }

    /**

     * Gets the number of items in the list.

     * @return     the number of items in the list

     * @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 items.size();

    }

    /**

     * Gets the item associated with the specified index.

     * @return       an item that is associated with

     *                    the specified index

     * @param        index the position of the item

     * @see          #getItemCount

     */

    public String getItem(int index) {

        return getItemImpl(index);

    }

    // NOTE: This method may be called by privileged threads.

    //       We implement this functionality in a package-private method

    //       to insure that it cannot be overridden by client subclasses.

    //       DO NOT INVOKE CLIENT CODE ON THIS THREAD!

    final String getItemImpl(int index) {

        return items.elementAt(index);

    }

    /**

     * Gets the items in the list.

     * @return       a string array containing items of the list

     * @see          #select

     * @see          #deselect

     * @see          #isIndexSelected

     * @since        JDK1.1

     */

    public synchronized String[] getItems() {

        String itemCopies[] = new String[items.size()];

        items.copyInto(itemCopies);

        return itemCopies;

    }

    /**

     * Adds the specified item to the end of scrolling list.

     * @param item the item to be added

     * @since JDK1.1

     */

    public void add(String item) {

        addItem(item);

    }

    /**

     * @deprecated      replaced by <code>add(String)</code>.

     */

    @Deprecated

    public void addItem(String item) {

        addItem(item, -1);

    }

    /**

     * Adds the specified item to the the scrolling list

     * at the position indicated by the index.  The index is

     * zero-based.  If the value of the index is less than zero,

     * or if the value of the index is greater than or equal to

     * the number of items in the list, then the item is added

     * to the end of the list.

     * @param       item   the item to be added;

     *              if this parameter is <code>null</code> then the item is

     *              treated as an empty string, <code>""</code>

     * @param       index  the position at which to add the item

     * @since       JDK1.1

     */

    public void add(String item, int index) {

        addItem(item, index);

    }

    /**

     * @deprecated      replaced by <code>add(String, int)</code>.

     */

    @Deprecated

    public synchronized void addItem(String item, int index) {

        if (index < -1 || index >= items.size()) {

            index = -1;

        }

        if (item == null) {

            item = "";

        }

        if (index == -1) {

            items.addElement(item);

        } else {

            items.insertElementAt(item, index);

        }

        ListPeer peer = (ListPeer)this.peer;

        if (peer != null) {

            peer.add(item, index);

        }

    }

    /**

     * Replaces the item at the specified index in the scrolling list

     * with the new string.

     * @param       newValue   a new string to replace an existing item

     * @param       index      the position of the item to replace

     * @exception ArrayIndexOutOfBoundsException if <code>index</code>

     *          is out of range

     */

    public synchronized void replaceItem(String newValue, int index) {

        remove(index);

        add(newValue, index);

    }

    /**

     * Removes all items from this list.

     * @see #remove

     * @see #delItems

     * @since JDK1.1

     */

    public void removeAll() {

        clear();

    }

    /**

     * @deprecated As of JDK version 1.1,

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

     */

    @Deprecated

    public synchronized void clear() {

        ListPeer peer = (ListPeer)this.peer;

        if (peer != null) {

            peer.removeAll();

        }

        items = new Vector<>();

        selected = new int[0];

    }

    /**

     * Removes the first occurrence of an item from the list.

     * If the specified item is selected, and is the only selected

     * item in the list, the list is set to have no selection.

     * @param        item  the item to remove from the list

     * @exception    IllegalArgumentException

     *                     if the item doesn't exist in the list

     * @since        JDK1.1

     */

    public synchronized void remove(String item) {

        int index = items.indexOf(item);

        if (index < 0) {

            throw new IllegalArgumentException("item " + item +

                                               " not found in list");

        } else {

            remove(index);

        }

    }

    /**

     * Removes the item at the specified position

     * from this scrolling list.

     * If the item with the specified position is selected, and is the

     * only selected item in the list, the list is set to have no selection.

     * @param      position   the index of the item to delete

     * @see        #add(String, int)

     * @since      JDK1.1

     * @exception    ArrayIndexOutOfBoundsException

     *               if the <code>position</code> is less than 0 or

     *               greater than <code>getItemCount()-1</code>

     */

    public void remove(int position) {

        delItem(position);

    }

    /**

     * @deprecated     replaced by <code>remove(String)</code>

     *                         and <code>remove(int)</code>.

     */

    @Deprecated

    public void delItem(int position) {

        delItems(position, position);

    }

    /**

     * Gets the index of the selected item on the list,

     *

     * @return        the index of the selected item;

     *                if no item is selected, or if multiple items are

     *                selected, <code>-1</code> is returned.

     * @see           #select

     * @see           #deselect

     * @see           #isIndexSelected

     */

    public synchronized int getSelectedIndex() {

        int sel[] = getSelectedIndexes();

        return (sel.length == 1) ? sel[0] : -1;

    }

    /**

     * Gets the selected indexes on the list.

     *

     * @return        an array of the selected indexes on this scrolling list;

     *                if no item is selected, a zero-length array is returned.

     * @see           #select

     * @see           #deselect

     * @see           #isIndexSelected

     */

    public synchronized int[] getSelectedIndexes() {

        ListPeer peer = (ListPeer)this.peer;

        if (peer != null) {

            selected = peer.getSelectedIndexes();

        }

        return selected.clone();

    }

    /**

     * Gets the selected item on this scrolling list.

     *

     * @return        the selected item on the list;

     *                if no item is selected, or if multiple items are

     *                selected, <code>null</code> is returned.

     * @see           #select

     * @see           #deselect

     * @see           #isIndexSelected

     */

    public synchronized String getSelectedItem() {

        int index = getSelectedIndex();

        return (index < 0) ? null : getItem(index);

    }

    /**

     * Gets the selected items on this scrolling list.

     *

     * @return        an array of the selected items on this scrolling list;

     *                if no item is selected, a zero-length array is returned.

     * @see           #select

     * @see           #deselect

     * @see           #isIndexSelected

     */

    public synchronized String[] getSelectedItems() {

        int sel[] = getSelectedIndexes();