TreeSelectionModel.java revision 10444:f08705540498 
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
26package javax.swing.tree;
27
28import javax.swing.event.*;
29import 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
89public 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     */
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     */
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      */
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      */
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      */
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      */
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      */
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      */
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      */
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      */
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     */
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      */
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      */
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      */
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     */
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     */
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      */
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      */
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      */
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      */
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     */
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     */
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     */
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     */
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     */
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      */
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      */
345    void removeTreeSelectionListener(TreeSelectionListener x);
346}
347