001/* TreeSelectionEvent.java --
002   Copyright (C) 2002, 2004, 2005, 2006, Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package javax.swing.event;
040
041import java.util.EventObject;
042
043import javax.swing.tree.TreePath;
044import javax.swing.tree.TreeSelectionModel;
045
046/**
047 * An event that carries information about a change to a
048 * {@link TreeSelectionModel}.
049 *
050 * @see TreeSelectionListener
051 *
052 * @author Andrew Selkirk
053 */
054public class TreeSelectionEvent extends EventObject
055{
056
057  /**
058   * The paths that have been added or removed from the selection.
059   */
060  protected TreePath[] paths;
061
062  /**
063   * Flags indicating if the paths were added (<code>true</code>) or removed
064   * (<code>false</code>) from the selection.
065   */
066  protected boolean[] areNew;
067
068  /**
069   * The old lead selection path (may be <code>null</code>).
070   */
071  protected TreePath oldLeadSelectionPath;
072
073  /**
074   * The new lead selection path (may be <code>null</code>).
075   */
076  protected TreePath newLeadSelectionPath;
077
078  /**
079   * Creates a new <code>TreeSelectionEvent</code>.
080   *
081   * @param source  the source (usually a {@link TreeSelectionModel},
082   *                <code>null</code> not permitted).
083   * @param paths  an array of the paths that have been added to or removed
084   *     from the selection.
085   * @param areNew  a flag for each path where <code>true</code> indicates the
086   *     corresponding path has been added to the selection and
087   *     <code>false</code> indicates the path has been removed.
088   * @param oldLeadSelectionPath  the old lead selection path (<code>null</code>
089   *     permitted).
090   * @param newLeadSelectionPath  the new lead selection path (<code>null</code>
091   *     permitted).
092   *
093   * @throws IllegalArgumentException if <code>source</code> is
094   *     <code>null</code>.
095   */
096  public TreeSelectionEvent(Object source, TreePath[] paths,
097                            boolean[] areNew, TreePath oldLeadSelectionPath,
098                            TreePath newLeadSelectionPath)
099  {
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}