1 /*
2 * Copyright (c) 1997, 2002, 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.tree;
27
28 import javax.swing.event.*;
29 import java.beans.PropertyChangeListener;
30
31 /**
32 * This interface represents the current state of the selection for
33 * the tree component.
34 * For information and examples of using tree selection models,
35 * see <a href="http://docs.oracle.com/javase/tutorial/uiswing/components/tree.html">How to Use Trees</a>
36 * in <em>The Java Tutorial.</em>
37 *
38 * <p>
39 * The state of the tree selection is characterized by
40 * a set of TreePaths, and optionally a set of integers. The mapping
41 * from TreePath to integer is done by way of an instance of RowMapper.
42 * It is not necessary for a TreeSelectionModel to have a RowMapper to
43 * correctly operate, but without a RowMapper <code>getSelectionRows</code>
44 * will return null.
45 *
46 * <p>
47 *
48 * A TreeSelectionModel can be configured to allow only one
49 * path (<code>SINGLE_TREE_SELECTION</code>) a number of
50 * continguous paths (<code>CONTIGUOUS_TREE_SELECTION</code>) or a number of
51 * discontiguous paths (<code>DISCONTIGUOUS_TREE_SELECTION</code>).
52 * A <code>RowMapper</code> is used to determine if TreePaths are
53 * contiguous.
54 * In the absence of a RowMapper <code>CONTIGUOUS_TREE_SELECTION</code> and
55 * <code>DISCONTIGUOUS_TREE_SELECTION</code> behave the same, that is they
56 * allow any number of paths to be contained in the TreeSelectionModel.
57 *
58 * <p>
59 *
60 * For a selection model of <code>CONTIGUOUS_TREE_SELECTION</code> any
61 * time the paths are changed (<code>setSelectionPath</code>,
62 * <code>addSelectionPath</code> ...) the TreePaths are again checked to
63 * make they are contiguous. A check of the TreePaths can also be forced
64 * by invoking <code>resetRowSelection</code>. How a set of discontiguous
65 * TreePaths is mapped to a contiguous set is left to implementors of
66 * this interface to enforce a particular policy.
67 *
68 * <p>
69 *
70 * Implementations should combine duplicate TreePaths that are
71 * added to the selection. For example, the following code
72 * <pre>
73 * TreePath[] paths = new TreePath[] { treePath, treePath };
74 * treeSelectionModel.setSelectionPaths(paths);
75 * </pre>
76 * should result in only one path being selected:
77 * <code>treePath</code>, and
78 * not two copies of <code>treePath</code>.
79 *
80 * <p>
81 *
82 * The lead TreePath is the last path that was added (or set). The lead
83 * row is then the row that corresponds to the TreePath as determined
84 * from the RowMapper.
85 *
86 * @author Scott Violet
87 */
88
89 public interface TreeSelectionModel
90 {
91 /** Selection can only contain one path at a time. */
92 public static final int SINGLE_TREE_SELECTION = 1;
93
94 /** Selection can only be contiguous. This will only be enforced if
95 * a RowMapper instance is provided. That is, if no RowMapper is set
96 * this behaves the same as DISCONTIGUOUS_TREE_SELECTION. */
97 public static final int CONTIGUOUS_TREE_SELECTION = 2;
98
99 /** Selection can contain any number of items that are not necessarily
100 * contiguous. */
101 public static final int DISCONTIGUOUS_TREE_SELECTION = 4;
102
103 /**
104 * Sets the selection model, which must be one of SINGLE_TREE_SELECTION,
105 * CONTIGUOUS_TREE_SELECTION or DISCONTIGUOUS_TREE_SELECTION.
106 * <p>
107 * This may change the selection if the current selection is not valid
108 * for the new mode. For example, if three TreePaths are
109 * selected when the mode is changed to <code>SINGLE_TREE_SELECTION</code>,
110 * only one TreePath will remain selected. It is up to the particular
111 * implementation to decide what TreePath remains selected.
112 */
113 void setSelectionMode(int mode);
114
115 /**
116 * Returns the current selection mode, one of
117 * <code>SINGLE_TREE_SELECTION</code>,
118 * <code>CONTIGUOUS_TREE_SELECTION</code> or
119 * <code>DISCONTIGUOUS_TREE_SELECTION</code>.
120 */
121 int getSelectionMode();
122
123 /**
124 * Sets the selection to path. If this represents a change, then
125 * the TreeSelectionListeners are notified. If <code>path</code> is
126 * null, this has the same effect as invoking <code>clearSelection</code>.
127 *
128 * @param path new path to select
129 */
130 void setSelectionPath(TreePath path);
131
132 /**
133 * Sets the selection to path. If this represents a change, then
134 * the TreeSelectionListeners are notified. If <code>paths</code> is
135 * null, this has the same effect as invoking <code>clearSelection</code>.
136 *
137 * @param paths new selection
138 */
139 void setSelectionPaths(TreePath[] paths);
140
141 /**
142 * Adds path to the current selection. If path is not currently
143 * in the selection the TreeSelectionListeners are notified. This has
144 * no effect if <code>path</code> is null.
145 *
146 * @param path the new path to add to the current selection
147 */
148 void addSelectionPath(TreePath path);
149
150 /**
151 * Adds paths to the current selection. If any of the paths in
152 * paths are not currently in the selection the TreeSelectionListeners
153 * are notified. This has
154 * no effect if <code>paths</code> is null.
155 *
156 * @param paths the new paths to add to the current selection
157 */
158 void addSelectionPaths(TreePath[] paths);
159
160 /**
161 * Removes path from the selection. If path is in the selection
162 * The TreeSelectionListeners are notified. This has no effect if
163 * <code>path</code> is null.
164 *
165 * @param path the path to remove from the selection
166 */
167 void removeSelectionPath(TreePath path);
168
169 /**
170 * Removes paths from the selection. If any of the paths in
171 * <code>paths</code>
172 * are in the selection, the TreeSelectionListeners are notified.
173 * This method has no effect if <code>paths</code> is null.
174 *
175 * @param paths the path to remove from the selection
176 */
177 void removeSelectionPaths(TreePath[] paths);
178
179 /**
180 * Returns the first path in the selection. How first is defined is
181 * up to implementors, and may not necessarily be the TreePath with
182 * the smallest integer value as determined from the
183 * <code>RowMapper</code>.
184 */
185 TreePath getSelectionPath();
186
187 /**
188 * Returns the paths in the selection. This will return null (or an
189 * empty array) if nothing is currently selected.
190 */
191 TreePath[] getSelectionPaths();
192
193 /**
194 * Returns the number of paths that are selected.
195 */
196 int getSelectionCount();
197
198 /**
199 * Returns true if the path, <code>path</code>, is in the current
200 * selection.
201 */
202 boolean isPathSelected(TreePath path);
203
204 /**
205 * Returns true if the selection is currently empty.
206 */
207 boolean isSelectionEmpty();
208
209 /**
210 * Empties the current selection. If this represents a change in the
211 * current selection, the selection listeners are notified.
212 */
213 void clearSelection();
214
215 /**
216 * Sets the RowMapper instance. This instance is used to determine
217 * the row for a particular TreePath.
218 */
219 void setRowMapper(RowMapper newMapper);
220
221 /**
222 * Returns the RowMapper instance that is able to map a TreePath to a
223 * row.
224 */
225 RowMapper getRowMapper();
226
227 /**
228 * Returns all of the currently selected rows. This will return
229 * null (or an empty array) if there are no selected TreePaths or
230 * a RowMapper has not been set.
231 */
232 int[] getSelectionRows();
233
234 /**
235 * Returns the smallest value obtained from the RowMapper for the
236 * current set of selected TreePaths. If nothing is selected,
237 * or there is no RowMapper, this will return -1.
238 */
239 int getMinSelectionRow();
240
241 /**
242 * Returns the largest value obtained from the RowMapper for the
243 * current set of selected TreePaths. If nothing is selected,
244 * or there is no RowMapper, this will return -1.
245 */
246 int getMaxSelectionRow();
247
248 /**
249 * Returns true if the row identified by <code>row</code> is selected.
250 */
251 boolean isRowSelected(int row);
252
253 /**
254 * Updates this object's mapping from TreePaths to rows. This should
255 * be invoked when the mapping from TreePaths to integers has changed
256 * (for example, a node has been expanded).
257 * <p>
258 * You do not normally have to call this; JTree and its associated
259 * listeners will invoke this for you. If you are implementing your own
260 * view class, then you will have to invoke this.
261 */
262 void resetRowSelection();
263
264 /**
265 * Returns the lead selection index. That is the last index that was
266 * added.
267 */
268 int getLeadSelectionRow();
269
270 /**
271 * Returns the last path that was added. This may differ from the
272 * leadSelectionPath property maintained by the JTree.
273 */
274 TreePath getLeadSelectionPath();
275
276 /**
277 * Adds a PropertyChangeListener to the listener list.
278 * The listener is registered for all properties.
279 * <p>
280 * A PropertyChangeEvent will get fired when the selection mode
281 * changes.
282 *
283 * @param listener the PropertyChangeListener to be added
284 */
285 void addPropertyChangeListener(PropertyChangeListener listener);
286
287 /**
288 * Removes a PropertyChangeListener from the listener list.
289 * This removes a PropertyChangeListener that was registered
290 * for all properties.
291 *
292 * @param listener the PropertyChangeListener to be removed
293 */
294 void removePropertyChangeListener(PropertyChangeListener listener);
295
296 /**
297 * Adds x to the list of listeners that are notified each time the
298 * set of selected TreePaths changes.
299 *
300 * @param x the new listener to be added
301 */
302 void addTreeSelectionListener(TreeSelectionListener x);
303
304 /**
305 * Removes x from the list of listeners that are notified each time
306 * the set of selected TreePaths changes.
307 *
308 * @param x the listener to remove
309 */
310 void removeTreeSelectionListener(TreeSelectionListener x);
311 }