1. /*
  2. * @(#)TreeModel.java 1.21 03/01/23
  3. *
  4. * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package javax.swing.tree;
  8. import javax.swing.event.*;
  9. /**
  10. * The interface that defines a suitable data model for a <code>JTree</code>.
  11. * For further information on tree models,
  12. * including an example of a custom implementation,
  13. * see <a
  14. href="http://java.sun.com/docs/books/tutorial/uiswing/components/tree.html">How to Use Trees</a>
  15. * in <em>The Java Tutorial.</em>
  16. * <p>
  17. * <code>JTree</code> and its related classes make extensive use of
  18. * <code>TreePath</code>s for indentifying nodes in the <code>TreeModel</code>.
  19. * If a <code>TreeModel</code> returns the same object, as compared by
  20. * <code>equals</code>, at two different indices under the same parent
  21. * than the resulting <code>TreePath</code> objects will be considered equal
  22. * as well. Some implementations may assume that if two
  23. * <code>TreePath</code>s are equal, they identify the same node. If this
  24. * condition is not met, painting problems and other oddities may result.
  25. * In other words, if <code>getChild</code> for a given parent returns
  26. * the same Object (as determined by <code>equals</code>) problems may
  27. * result, and it is recommended you avoid doing this.
  28. *
  29. * @see TreePath
  30. *
  31. * @version 1.21 01/23/03
  32. * @author Rob Davis
  33. * @author Ray Ryan
  34. */
  35. public interface TreeModel
  36. {
  37. /**
  38. * Returns the root of the tree. Returns <code>null</code>
  39. * only if the tree has no nodes.
  40. *
  41. * @return the root of the tree
  42. */
  43. public Object getRoot();
  44. /**
  45. * Returns the child of <code>parent</code> at index <code>index</code>
  46. * in the parent's
  47. * child array. <code>parent</code> must be a node previously obtained
  48. * from this data source. This should not return <code>null</code>
  49. * if <code>index</code>
  50. * is a valid index for <code>parent</code> (that is <code>index >= 0 &&
  51. * index < getChildCount(parent</code>)).
  52. *
  53. * @param parent a node in the tree, obtained from this data source
  54. * @return the child of <code>parent</code> at index <code>index</code>
  55. */
  56. public Object getChild(Object parent, int index);
  57. /**
  58. * Returns the number of children of <code>parent</code>.
  59. * Returns 0 if the node
  60. * is a leaf or if it has no children. <code>parent</code> must be a node
  61. * previously obtained from this data source.
  62. *
  63. * @param parent a node in the tree, obtained from this data source
  64. * @return the number of children of the node <code>parent</code>
  65. */
  66. public int getChildCount(Object parent);
  67. /**
  68. * Returns <code>true</code> if <code>node</code> is a leaf.
  69. * It is possible for this method to return <code>false</code>
  70. * even if <code>node</code> has no children.
  71. * A directory in a filesystem, for example,
  72. * may contain no files; the node representing
  73. * the directory is not a leaf, but it also has no children.
  74. *
  75. * @param node a node in the tree, obtained from this data source
  76. * @return true if <code>node</code> is a leaf
  77. */
  78. public boolean isLeaf(Object node);
  79. /**
  80. * Messaged when the user has altered the value for the item identified
  81. * by <code>path</code> to <code>newValue</code>.
  82. * If <code>newValue</code> signifies a truly new value
  83. * the model should post a <code>treeNodesChanged</code> event.
  84. *
  85. * @param path path to the node that the user has altered
  86. * @param newValue the new value from the TreeCellEditor
  87. */
  88. public void valueForPathChanged(TreePath path, Object newValue);
  89. /**
  90. * Returns the index of child in parent. If <code>parent</code>
  91. * is <code>null</code> or <code>child</code> is <code>null</code>,
  92. * returns -1.
  93. *
  94. * @param parent a note in the tree, obtained from this data source
  95. * @param child the node we are interested in
  96. * @return the index of the child in the parent, or -1 if either
  97. * <code>child</code> or <code>parent</code> are <code>null</code>
  98. */
  99. public int getIndexOfChild(Object parent, Object child);
  100. //
  101. // Change Events
  102. //
  103. /**
  104. * Adds a listener for the <code>TreeModelEvent</code>
  105. * posted after the tree changes.
  106. *
  107. * @param l the listener to add
  108. * @see #removeTreeModelListener
  109. */
  110. void addTreeModelListener(TreeModelListener l);
  111. /**
  112. * Removes a listener previously added with
  113. * <code>addTreeModelListener</code>.
  114. *
  115. * @see #addTreeModelListener
  116. * @param l the listener to remove
  117. */
  118. void removeTreeModelListener(TreeModelListener l);
  119. }