001/* ---------------------------------------------------------------------------- 002 The Kiwi Toolkit - A Java Class Library 003 Copyright (C) 1998-2004 Mark A. Lindner 004 005 This library is free software; you can redistribute it and/or 006 modify it under the terms of the GNU General Public License as 007 published by the Free Software Foundation; either version 2 of the 008 License, or (at your option) any later version. 009 010 This library is distributed in the hope that it will be useful, 011 but WITHOUT ANY WARRANTY; without even the implied warranty of 012 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 013 General Public License for more details. 014 015 You should have received a copy of the GNU General Public License 016 along with this library; if not, write to the Free Software 017 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 018 02111-1307, USA. 019 020 The author may be contacted at: mark_a_lindner@yahoo.com 021 ---------------------------------------------------------------------------- 022 $Log: KTreeModel.java,v $ 023 Revision 1.1 2004/05/31 07:30:26 markl 024 Final cleanup and bugfixes of kiwi.ui.model. 025 026 ---------------------------------------------------------------------------- 027*/ 028 029package kiwi.ui.model; 030 031import java.awt.*; 032import java.util.*; 033import javax.swing.*; 034 035import kiwi.event.*; 036import kiwi.util.*; 037 038/** This interface defines the behavior for a data model for tree data 039 * structures. 040 * 041 * @author Mark Lindner 042 * @since Kiwi 2.0 043 */ 044 045public interface KTreeModel extends ModelProperties 046 { 047 /** Get the root node. 048 * 049 * @return The root node. 050 */ 051 052 public Object getRoot(); 053 054 /** Set the root node. (For immutable data models, this method may be 055 * implemented as a no-op.) 056 * 057 * @param root The new root node. 058 */ 059 060 public void setRoot(Object root); 061 062 /** Get a child count for a node. 063 * 064 * @param parent The parent node. 065 * 066 * @return The number of children that the given node has. 067 */ 068 069 public int getChildCount(Object parent); 070 071 /** Get a child of a node. 072 * 073 * @param parent The parent node. 074 * @param index The index of the child within the parent's list of children. 075 * 076 * @return The node, or <code>null</code> if no such node exists. 077 */ 078 079 public Object getChild(Object parent, int index); 080 081 /** Get the children of a node. 082 * 083 * @param parent The parent node. 084 * 085 * @return An iterator to the list of child nodes. 086 */ 087 088 public Iterator getChildren(Object parent); 089 090 /** Get the index of a child node in its parent's list of children. 091 * 092 * @param parent The parent node. 093 * @param node The child node. 094 * @return The index of the node, or -1 if the node is not a child of the 095 * given parent. 096 */ 097 098 public int getIndexOfChild(Object parent, Object node); 099 100 /** Remove all of the children of a given parent node. (For 101 * immutable data models, this method may be implemented as a 102 * no-op.) 103 * 104 * @param parent The parent node. 105 */ 106 107 public void removeChildren(Object parent); 108 109 /** Remove a child node of a given parent node. (For immutable data 110 * models, this method may be implemented as a no-op.) 111 * 112 * @param parent The parent node. 113 * @param index The index of the child to remove within the parent's list of 114 * children. 115 */ 116 117 public void removeChild(Object parent, int index); 118 119 /** Add a new child node to the given parent node. The child is 120 * added at the end of the parent's list of children. (For immutable 121 * data models, this method may be implemented as a no-op.) 122 * 123 * @param parent The parent node. 124 * @param node The new child node. 125 */ 126 127 public void addChild(Object parent, Object node); 128 129 /** Add a new child node to the given parent node. (For immutable 130 * data models, this method may be implemented as a no-op.) 131 * 132 * @param parent The parent node. 133 * @param node The new child node. 134 * @param index The offset in the list of children at which the new node 135 * should be inserted. 136 */ 137 138 public void addChild(Object parent, Object node, int index); 139 140 /** Get the parent of a node. 141 * 142 * @param node The child node. 143 * return The parent of the specified child node. 144 */ 145 146 public Object getParent(Object node); 147 148 /** Determine if a node is expandable. 149 * 150 * @param node The node to test. 151 * @return <code>true</code> if the node is expandable, <code>false</code> 152 * otherwise. 153 */ 154 155 public boolean isExpandable(Object node); 156 157 /** Get the icon for a node. 158 * 159 * @param node The node. 160 * @param isExpanded The current expanded state for the node. 161 * @return An icon for the node. 162 */ 163 164 public Icon getIcon(Object node, boolean isExpanded); 165 166 /** Get the label for a node. 167 * 168 * @param node The node. 169 * @return A string label for the node. 170 */ 171 172 public String getLabel(Object node); 173 174 /** Indicate to listeners that the specified node has changed. 175 * 176 * @param node The node. 177 */ 178 179 public void updateNode(Object node); 180 181 /** Indicate to listeners that the list of children of the specified node 182 * has changed. 183 * 184 * @param parent The parent node. 185 */ 186 187 public void updateChildren(Object parent); 188 189 /** Preload the children of a given node. This method is intended 190 * for data models that are dynamically loaded from an external data 191 * source; it may be desirable to instruct a model to prefetch the 192 * children for a given node when that node is expanding. For models 193 * where this is not desirable or not applicable, this method may be 194 * implemented as a no-op. 195 * 196 * @param parent The node for which children should be preloaded. 197 */ 198 199 public void preloadChildren(Object parent); 200 201 /** Release the children of a given parent node. This method is 202 * intended for data models that are dynamically loaded from an 203 * external data source; it may be desirable to instruct a model to 204 * "forget" the subtree rooted at a given node when that node is 205 * collapsed. For models where this is not desirable or not 206 * applicable, the method may be implemented as a no-op. 207 * 208 * @param parent The root node of the subtree that should be released. 209 */ 210 211 public void releaseChildren(Object parent); 212 213 /** Get the value of an arbitrary property for a given node. 214 * 215 * @param node The node. 216 * @param property The name of the property. 217 * @return The value of the specified property, or <code>null</code> if 218 * there is no value for this property. 219 */ 220 221 public Object getValueForProperty(Object node, String property); 222 223 /** Add a <code>KTreeModelListener</code> to this model's list of listeners. 224 * 225 * @param listener The listener to add. 226 */ 227 228 public void addTreeModelListener(KTreeModelListener listener); 229 230 /** Remove a <code>KTreeModelListener</code> from this model's list of 231 * listeners. 232 * 233 * @param listener The listener to remove. 234 */ 235 236 public void removeTreeModelListener(KTreeModelListener listener); 237 238 } 239 240/* end of source file */