libjava/javax/swing/plaf/TreeUI.java

   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., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 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
  55   extends ComponentUI
  56 {
  57   /**
  58    * Constructs a new <code>TreeUI</code>.
  59    */
  60   public TreeUI()
  61   {
  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 }