1 /*
   2  * Copyright (c) 1997, 2013, 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}.
  31  * <p>
  32  * {@code JTree} and its related classes make extensive use of
  33  * {@code TreePath}s for identifying nodes in the {@code TreeModel}.
  34  * If a {@code TreeModel} returns the same object, as compared by
  35  * {@code equals}, at two different indices under the same parent
  36  * than the resulting {@code TreePath} objects will be considered equal
  37  * as well. Some implementations may assume that if two
  38  * {@code TreePath}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} for a given parent returns
  41  * the same Object (as determined by {@code equals}) problems may
  42  * result, and it is recommended you avoid doing this.
  43  * <p>
  44  * Similarly {@code JTree} and its related classes place
  45  * {@code TreePath}s in {@code Map}s.  As such if
  46  * a node is requested twice, the return values must be equal
  47  * (using the {@code equals} method) and have the same
  48  * {@code hashCode}.
  49  * <p>
  50  * For further information on tree models,
  51  * including an example of a custom implementation,
  52  * see <a
  53  href="http://docs.oracle.com/javase/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}
  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} at index {@code index}
  75      * in the parent's
  76      * child array.  {@code parent} must be a node previously obtained
  77      * from this data source. This should not return {@code null}
  78      * if {@code index}
  79      * is a valid index for {@code parent} (that is
  80      * {@code index >= 0 && index < getChildCount(parent)}).
  81      *
  82      * @param parent    a node in the tree, obtained from this data source
  83      * @param index     index of child to be returned
  84      * @return          the child of {@code parent} at index {@code index}
  85      */
  86     public Object getChild(Object parent, int index);
  87 
  88 
  89     /**
  90      * Returns the number of children of {@code parent}.
  91      * Returns 0 if the node
  92      * is a leaf or if it has no children.  {@code parent} must be a node
  93      * previously obtained from this data source.
  94      *
  95      * @param   parent  a node in the tree, obtained from this data source
  96      * @return  the number of children of the node {@code parent}
  97      */
  98     public int getChildCount(Object parent);
  99 
 100 
 101     /**
 102      * Returns {@code true} if {@code node} is a leaf.
 103      * It is possible for this method to return {@code false}
 104      * even if {@code node} has no children.
 105      * A directory in a filesystem, for example,
 106      * may contain no files; the node representing
 107      * the directory is not a leaf, but it also has no children.
 108      *
 109      * @param   node  a node in the tree, obtained from this data source
 110      * @return  true if {@code node} is a leaf
 111      */
 112     public boolean isLeaf(Object node);
 113 
 114     /**
 115       * Messaged when the user has altered the value for the item identified
 116       * by {@code path} to {@code newValue}.
 117       * If {@code newValue} signifies a truly new value
 118       * the model should post a {@code treeNodesChanged} event.
 119       *
 120       * @param path path to the node that the user has altered
 121       * @param newValue the new value from the TreeCellEditor
 122       */
 123     public void valueForPathChanged(TreePath path, Object newValue);
 124 
 125     /**
 126      * Returns the index of child in parent.  If either {@code parent}
 127      * or {@code child} is {@code null}, returns -1.
 128      * If either {@code parent} or {@code child} don't
 129      * belong to this tree model, returns -1.
 130      *
 131      * @param parent a node in the tree, obtained from this data source
 132      * @param child the node we are interested in
 133      * @return the index of the child in the parent, or -1 if either
 134      *    {@code child} or {@code parent} are {@code null}
 135      *    or don't belong to this tree model
 136      */
 137     public int getIndexOfChild(Object parent, Object child);
 138 
 139 //
 140 //  Change Events
 141 //
 142 
 143     /**
 144      * Adds a listener for the {@code TreeModelEvent}
 145      * posted after the tree changes.
 146      *
 147      * @param   l       the listener to add
 148      * @see     #removeTreeModelListener
 149      */
 150     void addTreeModelListener(TreeModelListener l);
 151 
 152     /**
 153      * Removes a listener previously added with
 154      * {@code addTreeModelListener}.
 155      *
 156      * @see     #addTreeModelListener
 157      * @param   l       the listener to remove
 158      */
 159     void removeTreeModelListener(TreeModelListener l);
 160 
 161 }
--- EOF ---