1 /*
2 * Copyright (c) 1997, 2006, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.swing.event;
27
28 import java.util.EventObject;
29 import javax.swing.tree.TreePath;
30
31 /**
32 * An event that characterizes a change in the current
33 * selection. The change is based on any number of paths.
34 * TreeSelectionListeners will generally query the source of
35 * the event for the new selected status of each potentially
36 * changed row.
37 * <p>
38 * <strong>Warning:</strong>
39 * Serialized objects of this class will not be compatible with
40 * future Swing releases. The current serialization support is
41 * appropriate for short term storage or RMI between applications running
42 * the same version of Swing. As of 1.4, support for long term storage
43 * of all JavaBeans™
44 * has been added to the <code>java.beans</code> package.
45 * Please see {@link java.beans.XMLEncoder}.
46 *
47 * @see TreeSelectionListener
48 * @see javax.swing.tree.TreeSelectionModel
49 *
50 * @author Scott Violet
51 */
52 public class TreeSelectionEvent extends EventObject
53 {
54 /** Paths this event represents. */
55 protected TreePath[] paths;
56 /** For each path identifies if that path is in fact new. */
57 protected boolean[] areNew;
58 /** leadSelectionPath before the paths changed, may be null. */
59 protected TreePath oldLeadSelectionPath;
60 /** leadSelectionPath after the paths changed, may be null. */
61 protected TreePath newLeadSelectionPath;
62
63 /**
64 * Represents a change in the selection of a TreeSelectionModel.
65 * paths identifies the paths that have been either added or
66 * removed from the selection.
67 *
68 * @param source source of event
69 * @param paths the paths that have changed in the selection
70 */
71 public TreeSelectionEvent(Object source, TreePath[] paths,
72 boolean[] areNew, TreePath oldLeadSelectionPath,
73 TreePath newLeadSelectionPath)
74 {
75 super(source);
76 this.paths = paths;
77 this.areNew = areNew;
78 this.oldLeadSelectionPath = oldLeadSelectionPath;
79 this.newLeadSelectionPath = newLeadSelectionPath;
80 }
81
82 /**
83 * Represents a change in the selection of a TreeSelectionModel.
84 * path identifies the path that have been either added or
85 * removed from the selection.
86 *
87 * @param source source of event
88 * @param path the path that has changed in the selection
89 * @param isNew whether or not the path is new to the selection, false
90 * means path was removed from the selection.
91 */
92 public TreeSelectionEvent(Object source, TreePath path, boolean isNew,
93 TreePath oldLeadSelectionPath,
94 TreePath newLeadSelectionPath)
95 {
96 super(source);
97 paths = new TreePath[1];
98 paths[0] = path;
99 areNew = new boolean[1];
100 areNew[0] = isNew;
101 this.oldLeadSelectionPath = oldLeadSelectionPath;
102 this.newLeadSelectionPath = newLeadSelectionPath;
103 }
104
105 /**
106 * Returns the paths that have been added or removed from the
107 * selection.
108 */
109 public TreePath[] getPaths()
110 {
111 int numPaths;
112 TreePath[] retPaths;
113
114 numPaths = paths.length;
115 retPaths = new TreePath[numPaths];
116 System.arraycopy(paths, 0, retPaths, 0, numPaths);
117 return retPaths;
118 }
119
120 /**
121 * Returns the first path element.
122 */
123 public TreePath getPath()
124 {
125 return paths[0];
126 }
127
128 /**
129 * Returns whether the path identified by {@code getPath} was
130 * added to the selection. A return value of {@code true}
131 * indicates the path identified by {@code getPath} was added to
132 * the selection. A return value of {@code false} indicates {@code
133 * getPath} was selected, but is no longer selected.
134 *
135 * @return {@code true} if {@code getPath} was added to the selection,
136 * {@code false} otherwise
137 */
138 public boolean isAddedPath() {
139 return areNew[0];
140 }
141
142 /**
143 * Returns whether the specified path was added to the selection.
144 * A return value of {@code true} indicates the path identified by
145 * {@code path} was added to the selection. A return value of
146 * {@code false} indicates {@code path} is no longer selected. This method
147 * is only valid for the paths returned from {@code getPaths()}; invoking
148 * with a path not included in {@code getPaths()} throws an
149 * {@code IllegalArgumentException}.
150 *
151 * @param path the path to test
152 * @return {@code true} if {@code path} was added to the selection,
153 * {@code false} otherwise
154 * @throws IllegalArgumentException if {@code path} is not contained
155 * in {@code getPaths}
156 * @see #getPaths
157 */
158 public boolean isAddedPath(TreePath path) {
159 for(int counter = paths.length - 1; counter >= 0; counter--)
160 if(paths[counter].equals(path))
161 return areNew[counter];
162 throw new IllegalArgumentException("path is not a path identified by the TreeSelectionEvent");
163 }
164
165 /**
166 * Returns whether the path at {@code getPaths()[index]} was added
167 * to the selection. A return value of {@code true} indicates the
168 * path was added to the selection. A return value of {@code false}
169 * indicates the path is no longer selected.
170 *
171 * @param index the index of the path to test
172 * @return {@code true} if the path was added to the selection,
173 * {@code false} otherwise
174 * @throws IllegalArgumentException if index is outside the range of
175 * {@code getPaths}
176 * @see #getPaths
177 *
178 * @since 1.3
179 */
180 public boolean isAddedPath(int index) {
181 if (paths == null || index < 0 || index >= paths.length) {
182 throw new IllegalArgumentException("index is beyond range of added paths identified by TreeSelectionEvent");
183 }
184 return areNew[index];
185 }
186
187 /**
188 * Returns the path that was previously the lead path.
189 */
190 public TreePath getOldLeadSelectionPath() {
191 return oldLeadSelectionPath;
192 }
193
194 /**
195 * Returns the current lead path.
196 */
197 public TreePath getNewLeadSelectionPath() {
198 return newLeadSelectionPath;
199 }
200
201 /**
202 * Returns a copy of the receiver, but with the source being newSource.
203 */
204 public Object cloneWithSource(Object newSource) {
205 // Fix for IE bug - crashing
206 return new TreeSelectionEvent(newSource, paths,areNew,
207 oldLeadSelectionPath,
208 newLeadSelectionPath);
209 }
210 }