libjava/classpath/javax/swing/event/TreeSelectionEvent.java

   1 /* TreeSelectionEvent.java --
   2    Copyright (C) 2002, 2004, 2005, 2006, 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.event;
  40
  41 import java.util.EventObject;
  42
  43 import javax.swing.tree.TreePath;
  44 import javax.swing.tree.TreeSelectionModel;
  45
  46 /**
  47  * An event that carries information about a change to a
  48  * {@link TreeSelectionModel}.
  49  *
  50  * @see TreeSelectionListener
  51  *
  52  * @author Andrew Selkirk
  53  */
  54 public class TreeSelectionEvent extends EventObject
  55 {
  56
  57   /**
  58    * The paths that have been added or removed from the selection.
  59    */
  60   protected TreePath[] paths;
  61
  62   /**
  63    * Flags indicating if the paths were added (<code>true</code>) or removed
  64    * (<code>false</code>) from the selection.
  65    */
  66   protected boolean[] areNew;
  67
  68   /**
  69    * The old lead selection path (may be <code>null</code>).
  70    */
  71   protected TreePath oldLeadSelectionPath;
  72
  73   /**
  74    * The new lead selection path (may be <code>null</code>).
  75    */
  76   protected TreePath newLeadSelectionPath;
  77
  78   /**
  79    * Creates a new <code>TreeSelectionEvent</code>.
  80    *
  81    * @param source  the source (usually a {@link TreeSelectionModel},
  82    *                <code>null</code> not permitted).
  83    * @param paths  an array of the paths that have been added to or removed
  84    *     from the selection.
  85    * @param areNew  a flag for each path where <code>true</code> indicates the
  86    *     corresponding path has been added to the selection and
  87    *     <code>false</code> indicates the path has been removed.
  88    * @param oldLeadSelectionPath  the old lead selection path (<code>null</code>
  89    *     permitted).
  90    * @param newLeadSelectionPath  the new lead selection path (<code>null</code>
  91    *     permitted).
  92    *
  93    * @throws IllegalArgumentException if <code>source</code> is
  94    *     <code>null</code>.
  95    */
  96   public TreeSelectionEvent(Object source, TreePath[] paths,
  97                             boolean[] areNew, TreePath oldLeadSelectionPath,
  98                             TreePath newLeadSelectionPath)
  99   {
 100     super(source);
 101     this.paths                                  = paths;
 102     this.areNew                                 = areNew;
 103     this.oldLeadSelectionPath   = oldLeadSelectionPath;
 104     this.newLeadSelectionPath   = newLeadSelectionPath;
 105   }
 106
 107   /**
 108    * Creates a new <code>TreeSelectionEvent</code>.
 109    *
 110    * @param source  the event source (usually a {@link TreeSelectionModel},
 111    *     <code>null</code> not permitted).
 112    * @param path  the path.
 113    * @param isNew <code>true</code> indicates that <code>path</code> has been
 114    *     added to the selection, and <code>false</code> indicates that it has
 115    *     been removed.
 116    * @param oldLeadSelectionPath  the old lead selection path (<code>null</code>
 117    *     permitted).
 118    * @param newLeadSelectionPath  the new lead selection path (<code>null</code>
 119    *     permitted).
 120    *
 121    * @throws IllegalArgumentException if <code>source</code> is
 122    *     <code>null</code>.
 123    */
 124   public TreeSelectionEvent(Object source, TreePath path,
 125                             boolean isNew, TreePath oldLeadSelectionPath,
 126                             TreePath newLeadSelectionPath)
 127   {
 128     super(source);
 129     this.paths = new TreePath[]{path};
 130     this.areNew = new boolean[]{isNew};
 131     this.oldLeadSelectionPath   = oldLeadSelectionPath;
 132     this.newLeadSelectionPath   = newLeadSelectionPath;
 133   }
 134
 135   /**
 136    * Returns the first path element.
 137    *
 138    * @return The first path element.
 139    *
 140    * @see #getPaths()
 141    */
 142   public TreePath getPath()
 143   {
 144     return paths[0];
 145   }
 146
 147   /**
 148    * Returns an array of the paths that changed in the selection.
 149    *
 150    * @return The paths that changed in the selection.
 151    *
 152    * @see #isAddedPath(TreePath)
 153    */
 154   public TreePath[] getPaths()
 155   {
 156     return (TreePath[]) paths.clone();
 157   }
 158
 159   /**
 160    * Returns <code>true</code> if the path returned by {@link #getPath()} has
 161    * been added to the selection, and <code>false</code> if it has been
 162    * removed.
 163    *
 164    * @return A boolean.
 165    *
 166    * @see #isAddedPath(int)
 167    */
 168   public boolean isAddedPath()
 169   {
 170     return areNew[0];
 171   }
 172
 173   /**
 174    * Returns <code>true</code> if <code>path</code> has been added to the
 175    * selection, and <code>false</code> if the path has been removed from the
 176    * selection.
 177    *
 178    * @param path  the path to check.
 179    *
 180    * @return A flag indicating whether the path has been added to, or removed
 181    *     from, the selection.
 182    *
 183    * @throw IllegalArgumentException if <code>path</code> is not one of the
 184    *     paths in {@link #getPaths()}.
 185    *
 186    * @see #isAddedPath(int)
 187    */
 188   public boolean isAddedPath(TreePath path)
 189   {
 190     for (int i = paths.length - 1; i >= 0; i--)
 191       if (paths[i].equals(path))
 192         return areNew[i];
 193
 194     throw new IllegalArgumentException("Unknown 'path' argument.");
 195   }
 196
 197   /**
 198    * Returns <code>true</code> if the path at the specified index has been
 199    * added to the selection, and <code>false</code> if the path has been
 200    * removed from the selection.
 201    *
 202    * @param index  the path index.
 203    *
 204    * @return A flag indicating whether the path has been added to, or removed
 205    *     from, the selection.
 206    *
 207    * @since 1.3
 208    *
 209    * @see #isAddedPath(TreePath)
 210    */
 211   public boolean isAddedPath(int index)
 212   {
 213     return areNew[index];
 214   }
 215
 216   /**
 217    * Returns the old lead selection path.
 218    *
 219    * @return The old lead selection path (possibly <code>null</code>).
 220    *
 221    * @see #getNewLeadSelectionPath()
 222    */
 223   public TreePath getOldLeadSelectionPath()
 224   {
 225     return oldLeadSelectionPath;
 226   }
 227
 228   /**
 229    * Returns the new lead selection path.
 230    *
 231    * @return The new lead selection path (possibly <code>null</code>).
 232    *
 233    * @see #getOldLeadSelectionPath()
 234    */
 235   public TreePath getNewLeadSelectionPath()
 236   {
 237     return newLeadSelectionPath;
 238   }
 239
 240   /**
 241    * Creates a shallow copy of this <code>TreeSelectionEvent</code>, replacing
 242    * the source with <code>source</code>.
 243    *
 244    * @param source  the new event source (<code>null</code> not permitted).
 245    *
 246    * @return A cloned event with another event source.
 247    *
 248    * @throws IllegalArgumentException if <code>source</code> is
 249    *     <code>null</code>.
 250    */
 251   public Object cloneWithSource(Object source)
 252   {
 253     return new TreeSelectionEvent (source, paths, areNew, oldLeadSelectionPath,
 254         newLeadSelectionPath);
 255   }
 256
 257 }