1 /*
2  * Copyright (c) 1997, 2013, 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   * contiguous 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      * @param   mode    selection mode to be set
114      */
setSelectionMode(int mode)115     void setSelectionMode(int mode);
116 
117     /**
118      * Returns the current selection mode, one of
119      * <code>SINGLE_TREE_SELECTION</code>,
120      * <code>CONTIGUOUS_TREE_SELECTION</code> or
121      * <code>DISCONTIGUOUS_TREE_SELECTION</code>.
122      *
123      * @return          the current selection mode
124      */
getSelectionMode()125     int getSelectionMode();
126 
127     /**
128       * Sets the selection to path. If this represents a change, then
129       * the TreeSelectionListeners are notified. If <code>path</code> is
130       * null, this has the same effect as invoking <code>clearSelection</code>.
131       *
132       * @param  path    new path to select
133       */
setSelectionPath(TreePath path)134     void setSelectionPath(TreePath path);
135 
136     /**
137       * Sets the selection to path. If this represents a change, then
138       * the TreeSelectionListeners are notified. If <code>paths</code> is
139       * null, this has the same effect as invoking <code>clearSelection</code>.
140       *
141       * @param  paths   new selection
142       */
setSelectionPaths(TreePath[] paths)143     void setSelectionPaths(TreePath[] paths);
144 
145     /**
146       * Adds path to the current selection. If path is not currently
147       * in the selection the TreeSelectionListeners are notified. This has
148       * no effect if <code>path</code> is null.
149       *
150       * @param  path    the new path to add to the current selection
151       */
addSelectionPath(TreePath path)152     void addSelectionPath(TreePath path);
153 
154     /**
155       * Adds paths to the current selection.  If any of the paths in
156       * paths are not currently in the selection the TreeSelectionListeners
157       * are notified. This has
158       * no effect if <code>paths</code> is null.
159       *
160       * @param  paths   the new paths to add to the current selection
161       */
addSelectionPaths(TreePath[] paths)162     void addSelectionPaths(TreePath[] paths);
163 
164     /**
165       * Removes path from the selection. If path is in the selection
166       * The TreeSelectionListeners are notified. This has no effect if
167       * <code>path</code> is null.
168       *
169       * @param  path    the path to remove from the selection
170       */
removeSelectionPath(TreePath path)171     void removeSelectionPath(TreePath path);
172 
173     /**
174       * Removes paths from the selection.  If any of the paths in
175       * <code>paths</code>
176       * are in the selection, the TreeSelectionListeners are notified.
177       * This method has no effect if <code>paths</code> is null.
178       *
179       * @param  paths   the path to remove from the selection
180       */
removeSelectionPaths(TreePath[] paths)181     void removeSelectionPaths(TreePath[] paths);
182 
183     /**
184       * Returns the first path in the selection. How first is defined is
185       * up to implementors, and may not necessarily be the TreePath with
186       * the smallest integer value as determined from the
187       * <code>RowMapper</code>.
188       *
189       * @return         the first path in the selection
190       */
getSelectionPath()191     TreePath getSelectionPath();
192 
193     /**
194       * Returns the paths in the selection. This will return null (or an
195       * empty array) if nothing is currently selected.
196       *
197       * @return         the paths in the selection
198       */
getSelectionPaths()199     TreePath[] getSelectionPaths();
200 
201     /**
202      * Returns the number of paths that are selected.
203      *
204      * @return          the number of paths that are selected
205      */
getSelectionCount()206     int getSelectionCount();
207 
208     /**
209       * Returns true if the path, <code>path</code>, is in the current
210       * selection.
211       *
212       * @param  path    the path to be loked for
213       * @return         whether the {@code path} is in the current selection
214       */
isPathSelected(TreePath path)215     boolean isPathSelected(TreePath path);
216 
217     /**
218       * Returns true if the selection is currently empty.
219       *
220       * @return         whether the selection is currently empty
221       */
isSelectionEmpty()222     boolean isSelectionEmpty();
223 
224     /**
225       * Empties the current selection.  If this represents a change in the
226       * current selection, the selection listeners are notified.
227       */
clearSelection()228     void clearSelection();
229 
230     /**
231      * Sets the RowMapper instance. This instance is used to determine
232      * the row for a particular TreePath.
233      *
234      * @param   newMapper   RowMapper to be set
235      */
setRowMapper(RowMapper newMapper)236     void setRowMapper(RowMapper newMapper);
237 
238     /**
239      * Returns the RowMapper instance that is able to map a TreePath to a
240      * row.
241      *
242      * @return          the RowMapper instance that is able to map a TreePath
243      *                  to a row
244      */
getRowMapper()245     RowMapper getRowMapper();
246 
247     /**
248       * Returns all of the currently selected rows. This will return
249       * null (or an empty array) if there are no selected TreePaths or
250       * a RowMapper has not been set.
251       *
252       * @return         all of the currently selected rows
253       */
getSelectionRows()254     int[] getSelectionRows();
255 
256     /**
257      * Returns the smallest value obtained from the RowMapper for the
258      * current set of selected TreePaths. If nothing is selected,
259      * or there is no RowMapper, this will return -1.
260      *
261      * @return          the smallest value obtained from the RowMapper
262      *                  for the current set of selected TreePaths
263       */
getMinSelectionRow()264     int getMinSelectionRow();
265 
266     /**
267      * Returns the largest value obtained from the RowMapper for the
268      * current set of selected TreePaths. If nothing is selected,
269      * or there is no RowMapper, this will return -1.
270      *
271      * @return          the largest value obtained from the RowMapper
272      *                  for the current set of selected TreePaths
273       */
getMaxSelectionRow()274     int getMaxSelectionRow();
275 
276     /**
277       * Returns true if the row identified by <code>row</code> is selected.
278       *
279       * @param  row     row to check
280       * @return         whether the row is selected
281       */
isRowSelected(int row)282     boolean isRowSelected(int row);
283 
284     /**
285      * Updates this object's mapping from TreePaths to rows. This should
286      * be invoked when the mapping from TreePaths to integers has changed
287      * (for example, a node has been expanded).
288      * <p>
289      * You do not normally have to call this; JTree and its associated
290      * listeners will invoke this for you. If you are implementing your own
291      * view class, then you will have to invoke this.
292      */
resetRowSelection()293     void resetRowSelection();
294 
295     /**
296      * Returns the lead selection index. That is the last index that was
297      * added.
298      *
299      * @return          the lead selection index
300      */
getLeadSelectionRow()301     int getLeadSelectionRow();
302 
303     /**
304      * Returns the last path that was added. This may differ from the
305      * leadSelectionPath property maintained by the JTree.
306      *
307      * @return          the last path that was added
308      */
getLeadSelectionPath()309     TreePath getLeadSelectionPath();
310 
311     /**
312      * Adds a PropertyChangeListener to the listener list.
313      * The listener is registered for all properties.
314      * <p>
315      * A PropertyChangeEvent will get fired when the selection mode
316      * changes.
317      *
318      * @param   listener    the PropertyChangeListener to be added
319      */
addPropertyChangeListener(PropertyChangeListener listener)320     void addPropertyChangeListener(PropertyChangeListener listener);
321 
322     /**
323      * Removes a PropertyChangeListener from the listener list.
324      * This removes a PropertyChangeListener that was registered
325      * for all properties.
326      *
327      * @param   listener    the PropertyChangeListener to be removed
328      */
removePropertyChangeListener(PropertyChangeListener listener)329     void removePropertyChangeListener(PropertyChangeListener listener);
330 
331     /**
332       * Adds x to the list of listeners that are notified each time the
333       * set of selected TreePaths changes.
334       *
335       * @param  x       the new listener to be added
336       */
addTreeSelectionListener(TreeSelectionListener x)337     void addTreeSelectionListener(TreeSelectionListener x);
338 
339     /**
340       * Removes x from the list of listeners that are notified each time
341       * the set of selected TreePaths changes.
342       *
343       * @param  x       the listener to remove
344       */
removeTreeSelectionListener(TreeSelectionListener x)345     void removeTreeSelectionListener(TreeSelectionListener x);
346 }
347