1 /*
   2  * Copyright (c) 1997, 2005, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 package javax.swing.tree;
  26 
  27 import javax.swing.event.*;
  28 
  29 /**
  30  * The model used by <code>JTree</code>.
  31  * <p>
  32  * <code>JTree</code> and its related classes make extensive use of
  33  * <code>TreePath</code>s for indentifying nodes in the <code>TreeModel</code>.
  34  * If a <code>TreeModel</code> returns the same object, as compared by
  35  * <code>equals</code>, at two different indices under the same parent
  36  * than the resulting <code>TreePath</code> objects will be considered equal
  37  * as well. Some implementations may assume that if two
  38  * <code>TreePath</code>s are equal, they identify the same node. If this
  39  * condition is not met, painting problems and other oddities may result.
  40  * In other words, if <code>getChild</code> for a given parent returns
  41  * the same Object (as determined by <code>equals</code>) problems may
  42  * result, and it is recommended you avoid doing this.
  43  * <p>
  44  * Similarly <code>JTree</code> and its related classes place
  45  * <code>TreePath</code>s in <code>Map</code>s.  As such if
  46  * a node is requested twice, the return values must be equal
  47  * (using the <code>equals</code> method) and have the same
  48  * <code>hashCode</code>.
  49  * <p>
  50  * For further information on tree models,
  51  * including an example of a custom implementation,
  52  * see <a
  53  href="http://java.sun.com/docs/books/tutorial/uiswing/components/tree.html">How to Use Trees</a>
  54  * in <em>The Java Tutorial.</em>
  55  *
  56  * @see TreePath
  57  *
  58  * @author Rob Davis
  59  * @author Ray Ryan
  60  */
  61 public interface TreeModel
  62 {
  63 
  64     /**
  65      * Returns the root of the tree.  Returns <code>null</code>
  66      * only if the tree has no nodes.
  67      *
  68      * @return  the root of the tree
  69      */
  70     public Object getRoot();
  71 
  72 
  73     /**
  74      * Returns the child of <code>parent</code> at index <code>index</code>
  75      * in the parent's
  76      * child array.  <code>parent</code> must be a node previously obtained
  77      * from this data source. This should not return <code>null</code>
  78      * if <code>index</code>
  79      * is a valid index for <code>parent</code> (that is <code>index &gt;= 0 &amp;&amp;
  80      * index &lt; getChildCount(parent</code>)).
  81      *
  82      * @param   parent  a node in the tree, obtained from this data source
  83      * @return  the child of <code>parent</code> at index <code>index</code>
  84      */
  85     public Object getChild(Object parent, int index);
  86 
  87 
  88     /**
  89      * Returns the number of children of <code>parent</code>.
  90      * Returns 0 if the node
  91      * is a leaf or if it has no children.  <code>parent</code> must be a node
  92      * previously obtained from this data source.
  93      *
  94      * @param   parent  a node in the tree, obtained from this data source
  95      * @return  the number of children of the node <code>parent</code>
  96      */
  97     public int getChildCount(Object parent);
  98 
  99 
 100     /**
 101      * Returns <code>true</code> if <code>node</code> is a leaf.
 102      * It is possible for this method to return <code>false</code>
 103      * even if <code>node</code> has no children.
 104      * A directory in a filesystem, for example,
 105      * may contain no files; the node representing
 106      * the directory is not a leaf, but it also has no children.
 107      *
 108      * @param   node  a node in the tree, obtained from this data source
 109      * @return  true if <code>node</code> is a leaf
 110      */
 111     public boolean isLeaf(Object node);
 112 
 113     /**
 114       * Messaged when the user has altered the value for the item identified
 115       * by <code>path</code> to <code>newValue</code>.
 116       * If <code>newValue</code> signifies a truly new value
 117       * the model should post a <code>treeNodesChanged</code> event.
 118       *
 119       * @param path path to the node that the user has altered
 120       * @param newValue the new value from the TreeCellEditor
 121       */
 122     public void valueForPathChanged(TreePath path, Object newValue);
 123 
 124     /**
 125      * Returns the index of child in parent.  If either <code>parent</code>
 126      * or <code>child</code> is <code>null</code>, returns -1.
 127      * If either <code>parent</code> or <code>child</code> don't
 128      * belong to this tree model, returns -1.
 129      *
 130      * @param parent a node in the tree, obtained from this data source
 131      * @param child the node we are interested in
 132      * @return the index of the child in the parent, or -1 if either
 133      *    <code>child</code> or <code>parent</code> are <code>null</code>
 134      *    or don't belong to this tree model
 135      */
 136     public int getIndexOfChild(Object parent, Object child);
 137 
 138 //
 139 //  Change Events
 140 //
 141 
 142     /**
 143      * Adds a listener for the <code>TreeModelEvent</code>
 144      * posted after the tree changes.
 145      *
 146      * @param   l       the listener to add
 147      * @see     #removeTreeModelListener
 148      */
 149     void addTreeModelListener(TreeModelListener l);
 150 
 151     /**
 152      * Removes a listener previously added with
 153      * <code>addTreeModelListener</code>.
 154      *
 155      * @see     #addTreeModelListener
 156      * @param   l       the listener to remove
 157      */
 158     void removeTreeModelListener(TreeModelListener l);
 159 
 160 }