/*

 * Copyright (c) 1997, 2002, 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.tree;

import javax.swing.event.*;

import java.beans.PropertyChangeListener;

/**

  * This interface represents the current state of the selection for

  * the tree component.

  * For information and examples of using tree selection models,

  * see <a href="http://java.sun.com/docs/books/tutorial/uiswing/components/tree.html">How to Use Trees</a>

  * in <em>The Java Tutorial.</em>

  *

  * <p>

  * The state of the tree selection is characterized by

  * a set of TreePaths, and optionally a set of integers. The mapping

  * from TreePath to integer is done by way of an instance of RowMapper.

  * It is not necessary for a TreeSelectionModel to have a RowMapper to

  * correctly operate, but without a RowMapper <code>getSelectionRows</code>

  * will return null.

  *

  * <p>

  *

  * A TreeSelectionModel can be configured to allow only one

  * path (<code>SINGLE_TREE_SELECTION</code>) a number of

  * continguous paths (<code>CONTIGUOUS_TREE_SELECTION</code>) or a number of

  * discontiguous paths (<code>DISCONTIGUOUS_TREE_SELECTION</code>).

  * A <code>RowMapper</code> is used to determine if TreePaths are

  * contiguous.

  * In the absence of a RowMapper <code>CONTIGUOUS_TREE_SELECTION</code> and

  * <code>DISCONTIGUOUS_TREE_SELECTION</code> behave the same, that is they

  * allow any number of paths to be contained in the TreeSelectionModel.

  *

  * <p>

  *

  * For a selection model of <code>CONTIGUOUS_TREE_SELECTION</code> any

  * time the paths are changed (<code>setSelectionPath</code>,

  * <code>addSelectionPath</code> ...) the TreePaths are again checked to

  * make they are contiguous. A check of the TreePaths can also be forced

  * by invoking <code>resetRowSelection</code>. How a set of discontiguous

  * TreePaths is mapped to a contiguous set is left to implementors of

  * this interface to enforce a particular policy.

  *

  * <p>

  *

  * Implementations should combine duplicate TreePaths that are

  * added to the selection. For example, the following code

  * <pre>

  *   TreePath[] paths = new TreePath[] { treePath, treePath };

  *   treeSelectionModel.setSelectionPaths(paths);

  * </pre>

  * should result in only one path being selected:

  * <code>treePath</code>, and

  * not two copies of <code>treePath</code>.

  *

  * <p>

  *

  * The lead TreePath is the last path that was added (or set). The lead

  * row is then the row that corresponds to the TreePath as determined

  * from the RowMapper.

  *

  * @author Scott Violet

  */

public interface TreeSelectionModel

{

    /** Selection can only contain one path at a time. */

    public static final int               SINGLE_TREE_SELECTION = 1;

    /** Selection can only be contiguous. This will only be enforced if

     * a RowMapper instance is provided. That is, if no RowMapper is set

     * this behaves the same as DISCONTIGUOUS_TREE_SELECTION. */

    public static final int               CONTIGUOUS_TREE_SELECTION = 2;

    /** Selection can contain any number of items that are not necessarily

     * contiguous. */

    public static final int               DISCONTIGUOUS_TREE_SELECTION = 4;

    /**

     * Sets the selection model, which must be one of SINGLE_TREE_SELECTION,

     * CONTIGUOUS_TREE_SELECTION or DISCONTIGUOUS_TREE_SELECTION.

     * <p>

     * This may change the selection if the current selection is not valid

     * for the new mode. For example, if three TreePaths are

     * selected when the mode is changed to <code>SINGLE_TREE_SELECTION</code>,

     * only one TreePath will remain selected. It is up to the particular

     * implementation to decide what TreePath remains selected.

     */

    void setSelectionMode(int mode);

    /**

     * Returns the current selection mode, one of

     * <code>SINGLE_TREE_SELECTION</code>,

     * <code>CONTIGUOUS_TREE_SELECTION</code> or

     * <code>DISCONTIGUOUS_TREE_SELECTION</code>.

     */

    int getSelectionMode();

    /**

      * Sets the selection to path. If this represents a change, then

      * the TreeSelectionListeners are notified. If <code>path</code> is

      * null, this has the same effect as invoking <code>clearSelection</code>.

      *

      * @param path new path to select

      */

    void setSelectionPath(TreePath path);

    /**

      * Sets the selection to path. If this represents a change, then

      * the TreeSelectionListeners are notified. If <code>paths</code> is

      * null, this has the same effect as invoking <code>clearSelection</code>.

      *

      * @param paths new selection

      */

    void setSelectionPaths(TreePath[] paths);

    /**

      * Adds path to the current selection. If path is not currently

      * in the selection the TreeSelectionListeners are notified. This has

      * no effect if <code>path</code> is null.

      *

      * @param path the new path to add to the current selection

      */

    void addSelectionPath(TreePath path);

    /**

      * Adds paths to the current selection.  If any of the paths in

      * paths are not currently in the selection the TreeSelectionListeners

      * are notified. This has

      * no effect if <code>paths</code> is null.

      *

      * @param paths the new paths to add to the current selection

      */

    void addSelectionPaths(TreePath[] paths);

    /**

      * Removes path from the selection. If path is in the selection

      * The TreeSelectionListeners are notified. This has no effect if

      * <code>path</code> is null.

      *

      * @param path the path to remove from the selection

      */

    void removeSelectionPath(TreePath path);

    /**

      * Removes paths from the selection.  If any of the paths in

      * <code>paths</code>

      * are in the selection, the TreeSelectionListeners are notified.

      * This method has no effect if <code>paths</code> is null.

      *

      * @param paths the path to remove from the selection

      */

    void removeSelectionPaths(TreePath[] paths);

    /**

      * Returns the first path in the selection. How first is defined is

      * up to implementors, and may not necessarily be the TreePath with

      * the smallest integer value as determined from the

      * <code>RowMapper</code>.

      */

    TreePath getSelectionPath();

    /**

      * Returns the paths in the selection. This will return null (or an

      * empty array) if nothing is currently selected.

      */

    TreePath[] getSelectionPaths();

    /**

     * Returns the number of paths that are selected.

     */

    int getSelectionCount();

    /**

      * Returns true if the path, <code>path</code>, is in the current

      * selection.

      */

    boolean isPathSelected(TreePath path);

    /**

      * Returns true if the selection is currently empty.

      */

    boolean isSelectionEmpty();

    /**

      * Empties the current selection.  If this represents a change in the

      * current selection, the selection listeners are notified.

      */

    void clearSelection();

    /**

     * Sets the RowMapper instance. This instance is used to determine

     * the row for a particular TreePath.

     */

    void setRowMapper(RowMapper newMapper);

    /**

     * Returns the RowMapper instance that is able to map a TreePath to a

     * row.

     */

    RowMapper getRowMapper();

    /**

      * Returns all of the currently selected rows. This will return

      * null (or an empty array) if there are no selected TreePaths or

      * a RowMapper has not been set.

      */

    int[] getSelectionRows();

    /**

     * Returns the smallest value obtained from the RowMapper for the

     * current set of selected TreePaths. If nothing is selected,

     * or there is no RowMapper, this will return -1.

      */

    int getMinSelectionRow();

    /**

     * Returns the largest value obtained from the RowMapper for the

     * current set of selected TreePaths. If nothing is selected,

     * or there is no RowMapper, this will return -1.

      */

    int getMaxSelectionRow();

    /**

      * Returns true if the row identified by <code>row</code> is selected.

      */

    boolean isRowSelected(int row);

    /**

     * Updates this object's mapping from TreePaths to rows. This should

     * be invoked when the mapping from TreePaths to integers has changed

     * (for example, a node has been expanded).

     * <p>

     * You do not normally have to call this; JTree and its associated

     * listeners will invoke this for you. If you are implementing your own

     * view class, then you will have to invoke this.

     */

    void resetRowSelection();

    /**

     * Returns the lead selection index. That is the last index that was

     * added.

     */

    int getLeadSelectionRow();

    /**

     * Returns the last path that was added. This may differ from the

     * leadSelectionPath property maintained by the JTree.

     */

    TreePath getLeadSelectionPath();

    /**

     * Adds a PropertyChangeListener to the listener list.

     * The listener is registered for all properties.

     * <p>

     * A PropertyChangeEvent will get fired when the selection mode

     * changes.

     *

     * @param listener  the PropertyChangeListener to be added

     */

    void addPropertyChangeListener(PropertyChangeListener listener);

    /**

     * Removes a PropertyChangeListener from the listener list.

     * This removes a PropertyChangeListener that was registered

     * for all properties.

     *

     * @param listener  the PropertyChangeListener to be removed

     */

    void removePropertyChangeListener(PropertyChangeListener listener);

    /**

      * Adds x to the list of listeners that are notified each time the

      * set of selected TreePaths changes.

      *

      * @param x the new listener to be added

      */

    void addTreeSelectionListener(TreeSelectionListener x);

    /**

      * Removes x from the list of listeners that are notified each time

      * the set of selected TreePaths changes.

      *

      * @param x the listener to remove

      */

    void removeTreeSelectionListener(TreeSelectionListener x);

}