Source for javax.swing.plaf.TreeUI

   1: /* TreeUI.java --
   2:    Copyright (C) 2002, 2003, 2004  Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: 
  39: package javax.swing.plaf;
  40: 
  41: import java.awt.Rectangle;
  42: 
  43: import javax.swing.JTree;
  44: import javax.swing.tree.TreePath;
  45: 
  46: /**
  47:  * An abstract base class for delegates that provide the user
  48:  * interface for <code>JTree</code>.
  49:  *
  50:  * @see javax.swing.JTree
  51:  *
  52:  * @author Sascha Brawer (brawer@dandelis.ch)
  53:  */
  54: public abstract class TreeUI extends ComponentUI
  55: {
  56:   /**
  57:    * Constructs a new <code>TreeUI</code>.
  58:    */
  59:   public TreeUI()
  60:   {
  61:     // Nothing to do here.
  62:   }
  63: 
  64: 
  65:   /**
  66:    * Determines the geometric extent of the label that is
  67:    * drawn for a path.
  68:    *
  69:    * @param tree the <code>JTree</code> for which this delegate
  70:    *        object provides the user interface.
  71:    *
  72:    * @param path the path whose label extent is requested.
  73:    *
  74:    * @return a rectangle enclosing the label, or <code>null</code>
  75:    *         if <code>path</code> contains invalid nodes.
  76:    */
  77:   public abstract Rectangle getPathBounds(JTree tree, TreePath path);
  78: 
  79: 
  80:   /**
  81:    * Creates a <code>TreePath</code> for the specified row.
  82:    *
  83:    * @param tree the <code>JTree</code> for which this delegate
  84:    *        object provides the user interface.
  85:    *
  86:    * @param row the index of the row, which should be a number
  87:    *        in the range <code>[0, getRowCount(tree) - 1]</code>.
  88:    *
  89:    * @return a <code>TreePath</code> for the specified row, or
  90:    *         <code>null</code> if <code>row</code> is outside
  91:    *         the valid range.
  92:    */
  93:   public abstract TreePath getPathForRow(JTree tree, int row);
  94: 
  95: 
  96:   /**
  97:    * Determines in which row a <code>TreePath</code> is currently
  98:    * being displayed.
  99:    *
 100:    * @param tree the <code>JTree</code> for which this delegate
 101:    *        object provides the user interface.
 102:    *
 103:    * @param path the path for which the caller wants to know
 104:    *        in which row it is being displayed.
 105:    *
 106:    * @return a number in the range <code>[0, getRowCount(tree)
 107:    *         - 1]</code> if the path is currently on display;
 108:    *         <code>-1</code> if the path is not shown to the
 109:    *        user.
 110:    */
 111:   public abstract int getRowForPath(JTree tree, TreePath path);
 112: 
 113: 
 114:   /**
 115:    * Counts how many rows are currently displayed.
 116:    *
 117:    * @param tree the <code>JTree</code> for which this delegate
 118:    *        object provides the user interface.
 119:    *
 120:    * @return the number of visible rows.
 121:    */
 122:   public abstract int getRowCount(JTree tree);
 123: 
 124: 
 125:   /**
 126:    * Finds the path that is closest to the specified position.
 127:    *
 128:    * <p><img src="doc-files/TreeUI-1.png" width="300" height="250"
 129:    * alt="[A screen shot of a JTree]" />
 130:    *
 131:    * <p>As shown by the above illustration, the bounds of the
 132:    * closest path do not necessarily need to contain the passed
 133:    * location.
 134:    *
 135:    * @param tree the <code>JTree</code> for which this delegate
 136:    *        object provides the user interface.
 137:    *
 138:    * @param x the horizontal location, relative to the origin
 139:    *        of <code>tree</code>.
 140:    *
 141:    * @param y the vertical location, relative to the origin
 142:    *        of <code>tree</code>.
 143:    *
 144:    * @return the closest path, or <code>null</code> if the
 145:    *         tree is currenlty not displaying any paths at all.
 146:    */
 147:   public abstract TreePath getClosestPathForLocation(JTree tree,
 148:                                                      int x, int y);
 149: 
 150: 
 151:   /**
 152:    * Determines whether the user is currently editing a tree cell.
 153:    *
 154:    * @param tree the <code>JTree</code> for which this delegate
 155:    *        object provides the user interface.
 156:    *
 157:    * @see #getEditingPath
 158:    */
 159:   public abstract boolean isEditing(JTree tree);
 160: 
 161: 
 162:   /**
 163:    * Stops editing a tree cell, committing the entered value into the
 164:    * tree&#x2019;s model. If no editing session is active, or if the
 165:    * active editor does not agree to stopping, nothing happens.  In
 166:    * some look and feels, this action happens when the user has
 167:    * pressed the enter key.
 168:    *
 169:    * @param tree the <code>JTree</code> for which this delegate
 170:    *        object provides the user interface.
 171:    *
 172:    * @return <code>false</code> if the editing still goes on because
 173:    *         the cell editor has objected to stopping the session;
 174:    *         <code>true</code> if editing has been stopped.
 175:    */
 176:   public abstract boolean stopEditing(JTree tree);
 177: 
 178: 
 179:   /**
 180:    * Cancels editing a tree cell, discarding any entered value.
 181:    * If no editing session is active, nothing happens. The cell
 182:    * editor is not given an opportunity to veto the canceling.
 183:    * In some look and feels, this action happens when the user has
 184:    * pressed the escape key.
 185:    *
 186:    * @param tree the <code>JTree</code> for which this delegate
 187:    *        object provides the user interface.
 188:    */
 189:   public abstract void cancelEditing(JTree tree);
 190: 
 191: 
 192:   /**
 193:    * Starts a session to edit a tree cell. If the cell editor
 194:    * rejects editing the cell, it will just be selected.
 195:    *
 196:    * @param tree the <code>JTree</code> for which this delegate
 197:    *        object provides the user interface.
 198:    *
 199:    * @param path the cell to edit.
 200:    */
 201:   public abstract void startEditingAtPath(JTree tree, TreePath path);
 202: 
 203: 
 204:   /**
 205:    * Retrieves the tree cell that is currently being edited.
 206:    *
 207:    * @return the currently edited path, or <code>null</code>
 208:    *         if no editing session is currently active.
 209:    */
 210:   public abstract TreePath getEditingPath(JTree tree);
 211: }