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 ---