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