/*

 * Copyright (c) 1997, 2006, 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 javax.swing;

import javax.swing.event.*;

/**

 * This interface represents the current state of the

 * selection for any of the components that display a

 * list of values with stable indices.  The selection is

 * modeled as a set of intervals, each interval represents

 * a contiguous range of selected list elements.

 * The methods for modifying the set of selected intervals

 * all take a pair of indices, index0 and index1, that represent

 * a closed interval, i.e. the interval includes both index0 and

 * index1.

 *

 * @author Hans Muller

 * @author Philip Milne

 * @see DefaultListSelectionModel

 */

public interface ListSelectionModel

{

    /**

     * A value for the selectionMode property: select one list index

     * at a time.

     *

     * @see #setSelectionMode

     */

    int SINGLE_SELECTION = 0;

    /**

     * A value for the selectionMode property: select one contiguous

     * range of indices at a time.

     *

     * @see #setSelectionMode

     */

    int SINGLE_INTERVAL_SELECTION = 1;

    /**

     * A value for the selectionMode property: select one or more

     * contiguous ranges of indices at a time.

     *

     * @see #setSelectionMode

     */

    int MULTIPLE_INTERVAL_SELECTION = 2;

    /**

     * Changes the selection to be between {@code index0} and {@code index1}

     * inclusive. {@code index0} doesn't have to be less than or equal to

     * {@code index1}.

     * <p>

     * In {@code SINGLE_SELECTION} selection mode, only the second index

     * is used.

     * <p>

     * If this represents a change to the current selection, then each

     * {@code ListSelectionListener} is notified of the change.

     *

     * @param index0 one end of the interval.

     * @param index1 other end of the interval

     * @see #addListSelectionListener

     */

    void setSelectionInterval(int index0, int index1);

    /**

     * Changes the selection to be the set union of the current selection

     * and the indices between {@code index0} and {@code index1} inclusive.

     * {@code index0} doesn't have to be less than or equal to {@code index1}.

     * <p>

     * In {@code SINGLE_SELECTION} selection mode, this is equivalent

     * to calling {@code setSelectionInterval}, and only the second index

     * is used. In {@code SINGLE_INTERVAL_SELECTION} selection mode, this

     * method behaves like {@code setSelectionInterval}, unless the given

     * interval is immediately adjacent to or overlaps the existing selection,

     * and can therefore be used to grow the selection.

     * <p>

     * If this represents a change to the current selection, then each

     * {@code ListSelectionListener} is notified of the change.

     *

     * @param index0 one end of the interval.

     * @param index1 other end of the interval

     * @see #addListSelectionListener

     * @see #setSelectionInterval

     */

    void addSelectionInterval(int index0, int index1);

    /**

     * Changes the selection to be the set difference of the current selection

     * and the indices between {@code index0} and {@code index1} inclusive.

     * {@code index0} doesn't have to be less than or equal to {@code index1}.

     * <p>

     * In {@code SINGLE_INTERVAL_SELECTION} selection mode, if the removal

     * would produce two disjoint selections, the removal is extended through

     * the greater end of the selection. For example, if the selection is

     * {@code 0-10} and you supply indices {@code 5,6} (in any order) the

     * resulting selection is {@code 0-4}.

     * <p>

     * If this represents a change to the current selection, then each

     * {@code ListSelectionListener} is notified of the change.

     *

     * @param index0 one end of the interval.

     * @param index1 other end of the interval

     * @see #addListSelectionListener

     */

    void removeSelectionInterval(int index0, int index1);

    /**

     * Returns the first selected index or -1 if the selection is empty.

     */

    int getMinSelectionIndex();

    /**

     * Returns the last selected index or -1 if the selection is empty.

     */

    int getMaxSelectionIndex();

    /**

     * Returns true if the specified index is selected.

     */

    boolean isSelectedIndex(int index);

    /**

     * Return the first index argument from the most recent call to

     * setSelectionInterval(), addSelectionInterval() or removeSelectionInterval().

     * The most recent index0 is considered the "anchor" and the most recent

     * index1 is considered the "lead".  Some interfaces display these

     * indices specially, e.g. Windows95 displays the lead index with a

     * dotted yellow outline.

     *

     * @see #getLeadSelectionIndex

     * @see #setSelectionInterval

     * @see #addSelectionInterval

     */

    int getAnchorSelectionIndex();

    /**

     * Set the anchor selection index.

     *

     * @see #getAnchorSelectionIndex

     */

    void setAnchorSelectionIndex(int index);

    /**

     * Return the second index argument from the most recent call to

     * setSelectionInterval(), addSelectionInterval() or removeSelectionInterval().

     *

     * @see #getAnchorSelectionIndex

     * @see #setSelectionInterval

     * @see #addSelectionInterval

     */

    int getLeadSelectionIndex();

    /**

     * Set the lead selection index.

     *

     * @see #getLeadSelectionIndex

     */

    void setLeadSelectionIndex(int index);

    /**

     * Change the selection to the empty set.  If this represents

     * a change to the current selection then notify each ListSelectionListener.

     *

     * @see #addListSelectionListener

     */

    void clearSelection();

    /**

     * Returns true if no indices are selected.

     */

    boolean isSelectionEmpty();

    /**

     * Insert length indices beginning before/after index.  This is typically

     * called to sync the selection model with a corresponding change

     * in the data model.

     */

    void insertIndexInterval(int index, int length, boolean before);

    /**

     * Remove the indices in the interval index0,index1 (inclusive) from

     * the selection model.  This is typically called to sync the selection

     * model width a corresponding change in the data model.

     */

    void removeIndexInterval(int index0, int index1);

    /**

     * Sets the {@code valueIsAdjusting} property, which indicates whether

     * or not upcoming selection changes should be considered part of a single

     * change. The value of this property is used to initialize the

     * {@code valueIsAdjusting} property of the {@code ListSelectionEvent}s that

     * are generated.

     * <p>

     * For example, if the selection is being updated in response to a user

     * drag, this property can be set to {@code true} when the drag is initiated

     * and set to {@code false} when the drag is finished. During the drag,

     * listeners receive events with a {@code valueIsAdjusting} property

     * set to {@code true}. At the end of the drag, when the change is

     * finalized, listeners receive an event with the value set to {@code false}.

     * Listeners can use this pattern if they wish to update only when a change

     * has been finalized.

     * <p>

     * Setting this property to {@code true} begins a series of changes that

     * is to be considered part of a single change. When the property is changed

     * back to {@code false}, an event is sent out characterizing the entire

     * selection change (if there was one), with the event's

     * {@code valueIsAdjusting} property set to {@code false}.

     *

     * @param valueIsAdjusting the new value of the property

     * @see #getValueIsAdjusting

     * @see javax.swing.event.ListSelectionEvent#getValueIsAdjusting

     */

    void setValueIsAdjusting(boolean valueIsAdjusting);

    /**

     * Returns {@code true} if the selection is undergoing a series of changes.

     *

     * @return true if the selection is undergoing a series of changes

     * @see #setValueIsAdjusting

     */

    boolean getValueIsAdjusting();

    /**

     * Sets the selection mode. The following list describes the accepted

     * selection modes:

     * <ul>

     * <li>{@code ListSelectionModel.SINGLE_SELECTION} -

     *   Only one list index can be selected at a time. In this mode,

     *   {@code setSelectionInterval} and {@code addSelectionInterval} are

     *   equivalent, both replacing the current selection with the index

     *   represented by the second argument (the "lead").

     * <li>{@code ListSelectionModel.SINGLE_INTERVAL_SELECTION} -

     *   Only one contiguous interval can be selected at a time.

     *   In this mode, {@code addSelectionInterval} behaves like

     *   {@code setSelectionInterval} (replacing the current selection),

     *   unless the given interval is immediately adjacent to or overlaps

     *   the existing selection, and can therefore be used to grow it.

     * <li>{@code ListSelectionModel.MULTIPLE_INTERVAL_SELECTION} -

     *   In this mode, there's no restriction on what can be selected.

     * </ul>

     *

     * @see #getSelectionMode

     * @throws IllegalArgumentException if the selection mode isn't

     *         one of those allowed

     */

    void setSelectionMode(int selectionMode);

    /**

     * Returns the current selection mode.

     *

     * @return the current selection mode

     * @see #setSelectionMode

     */

    int getSelectionMode();

    /**

     * Add a listener to the list that's notified each time a change

     * to the selection occurs.

     *

     * @param x the ListSelectionListener

     * @see #removeListSelectionListener

     * @see #setSelectionInterval

     * @see #addSelectionInterval

     * @see #removeSelectionInterval

     * @see #clearSelection

     * @see #insertIndexInterval

     * @see #removeIndexInterval

     */

    void addListSelectionListener(ListSelectionListener x);

    /**

     * Remove a listener from the list that's notified each time a

     * change to the selection occurs.

     *

     * @param x the ListSelectionListener

     * @see #addListSelectionListener

     */

    void removeListSelectionListener(ListSelectionListener x);

}