KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > swing > tree > TreeSelectionModel


1 /*
2  * @(#)TreeSelectionModel.java 1.24 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7
8 package javax.swing.tree;
9
10 import javax.swing.event.*;
11 import java.beans.PropertyChangeListener JavaDoc;
12
13 /**
14   * This interface represents the current state of the selection for
15   * the tree component.
16   * For information and examples of using tree selection models,
17   * see <a HREF="http://java.sun.com/docs/books/tutorial/uiswing/components/tree.html">How to Use Trees</a>
18   * in <em>The Java Tutorial.</em>
19   *
20   * <p>
21   * The state of the tree selection is characterized by
22   * a set of TreePaths, and optionally a set of integers. The mapping
23   * from TreePath to integer is done by way of an instance of RowMapper.
24   * It is not necessary for a TreeSelectionModel to have a RowMapper to
25   * correctly operate, but without a RowMapper <code>getSelectionRows</code>
26   * will return null.
27   *
28   * <p>
29   *
30   * A TreeSelectionModel can be configured to allow only one
31   * path (<code>SINGLE_TREE_SELECTION</code>) a number of
32   * continguous paths (<code>CONTIGUOUS_TREE_SELECTION</code>) or a number of
33   * discontiguous paths (<code>DISCONTIGUOUS_TREE_SELECTION</code>).
34   * A <code>RowMapper</code> is used to determine if TreePaths are
35   * contiguous.
36   * In the absence of a RowMapper <code>CONTIGUOUS_TREE_SELECTION</code> and
37   * <code>DISCONTIGUOUS_TREE_SELECTION</code> behave the same, that is they
38   * allow any number of paths to be contained in the TreeSelectionModel.
39   *
40   * <p>
41   *
42   * For a selection model of <code>CONTIGUOUS_TREE_SELECTION</code> any
43   * time the paths are changed (<code>setSelectionPath</code>,
44   * <code>addSelectionPath</code> ...) the TreePaths are again checked to
45   * make they are contiguous. A check of the TreePaths can also be forced
46   * by invoking <code>resetRowSelection</code>. How a set of discontiguous
47   * TreePaths is mapped to a contiguous set is left to implementors of
48   * this interface to enforce a particular policy.
49   *
50   * <p>
51   *
52   * Implementations should combine duplicate TreePaths that are
53   * added to the selection. For example, the following code
54   * <pre>
55   * TreePath[] paths = new TreePath[] { treePath, treePath };
56   * treeSelectionModel.setSelectionPaths(paths);
57   * </pre>
58   * should result in only one path being selected:
59   * <code>treePath</code>, and
60   * not two copies of <code>treePath</code>.
61   *
62   * <p>
63   *
64   * The lead TreePath is the last path that was added (or set). The lead
65   * row is then the row that corresponds to the TreePath as determined
66   * from the RowMapper.
67   *
68   * @version 1.24 12/19/03
69   * @author Scott Violet
70   */

71
72 public interface TreeSelectionModel
73 {
74     /** Selection can only contain one path at a time. */
75     public static final int SINGLE_TREE_SELECTION = 1;
76
77     /** Selection can only be contiguous. This will only be enforced if
78      * a RowMapper instance is provided. That is, if no RowMapper is set
79      * this behaves the same as DISCONTIGUOUS_TREE_SELECTION. */

80     public static final int CONTIGUOUS_TREE_SELECTION = 2;
81
82     /** Selection can contain any number of items that are not necessarily
83      * contiguous. */

84     public static final int DISCONTIGUOUS_TREE_SELECTION = 4;
85
86     /**
87      * Sets the selection model, which must be one of SINGLE_TREE_SELECTION,
88      * CONTIGUOUS_TREE_SELECTION or DISCONTIGUOUS_TREE_SELECTION.
89      * <p>
90      * This may change the selection if the current selection is not valid
91      * for the new mode. For example, if three TreePaths are
92      * selected when the mode is changed to <code>SINGLE_TREE_SELECTION</code>,
93      * only one TreePath will remain selected. It is up to the particular
94      * implementation to decide what TreePath remains selected.
95      */

96     void setSelectionMode(int mode);
97
98     /**
99      * Returns the current selection mode, one of
100      * <code>SINGLE_TREE_SELECTION</code>,
101      * <code>CONTIGUOUS_TREE_SELECTION</code> or
102      * <code>DISCONTIGUOUS_TREE_SELECTION</code>.
103      */

104     int getSelectionMode();
105
106     /**
107       * Sets the selection to path. If this represents a change, then
108       * the TreeSelectionListeners are notified. If <code>path</code> is
109       * null, this has the same effect as invoking <code>clearSelection</code>.
110       *
111       * @param path new path to select
112       */

113     void setSelectionPath(TreePath JavaDoc path);
114
115     /**
116       * Sets the selection to path. If this represents a change, then
117       * the TreeSelectionListeners are notified. If <code>paths</code> is
118       * null, this has the same effect as invoking <code>clearSelection</code>.
119       *
120       * @param paths new selection
121       */

122     void setSelectionPaths(TreePath JavaDoc[] paths);
123
124     /**
125       * Adds path to the current selection. If path is not currently
126       * in the selection the TreeSelectionListeners are notified. This has
127       * no effect if <code>path</code> is null.
128       *
129       * @param path the new path to add to the current selection
130       */

131     void addSelectionPath(TreePath JavaDoc path);
132
133     /**
134       * Adds paths to the current selection. If any of the paths in
135       * paths are not currently in the selection the TreeSelectionListeners
136       * are notified. This has
137       * no effect if <code>paths</code> is null.
138       *
139       * @param paths the new paths to add to the current selection
140       */

141     void addSelectionPaths(TreePath JavaDoc[] paths);
142
143     /**
144       * Removes path from the selection. If path is in the selection
145       * The TreeSelectionListeners are notified. This has no effect if
146       * <code>path</code> is null.
147       *
148       * @param path the path to remove from the selection
149       */

150     void removeSelectionPath(TreePath JavaDoc path);
151
152     /**
153       * Removes paths from the selection. If any of the paths in
154       * <code>paths</code>
155       * are in the selection, the TreeSelectionListeners are notified.
156       * This method has no effect if <code>paths</code> is null.
157       *
158       * @param paths the path to remove from the selection
159       */

160     void removeSelectionPaths(TreePath JavaDoc[] paths);
161
162     /**
163       * Returns the first path in the selection. How first is defined is
164       * up to implementors, and may not necessarily be the TreePath with
165       * the smallest integer value as determined from the
166       * <code>RowMapper</code>.
167       */

168     TreePath JavaDoc getSelectionPath();
169
170     /**
171       * Returns the paths in the selection. This will return null (or an
172       * empty array) if nothing is currently selected.
173       */

174     TreePath JavaDoc[] getSelectionPaths();
175
176     /**
177      * Returns the number of paths that are selected.
178      */

179     int getSelectionCount();
180
181     /**
182       * Returns true if the path, <code>path</code>, is in the current
183       * selection.
184       */

185     boolean isPathSelected(TreePath JavaDoc path);
186
187     /**
188       * Returns true if the selection is currently empty.
189       */

190     boolean isSelectionEmpty();
191
192     /**
193       * Empties the current selection. If this represents a change in the
194       * current selection, the selection listeners are notified.
195       */

196     void clearSelection();
197
198     /**
199      * Sets the RowMapper instance. This instance is used to determine
200      * the row for a particular TreePath.
201      */

202     void setRowMapper(RowMapper JavaDoc newMapper);
203
204     /**
205      * Returns the RowMapper instance that is able to map a TreePath to a
206      * row.
207      */

208     RowMapper JavaDoc getRowMapper();
209
210     /**
211       * Returns all of the currently selected rows. This will return
212       * null (or an empty array) if there are no selected TreePaths or
213       * a RowMapper has not been set.
214       */

215     int[] getSelectionRows();
216
217     /**
218      * Returns the smallest value obtained from the RowMapper for the
219      * current set of selected TreePaths. If nothing is selected,
220      * or there is no RowMapper, this will return -1.
221       */

222     int getMinSelectionRow();
223
224     /**
225      * Returns the largest value obtained from the RowMapper for the
226      * current set of selected TreePaths. If nothing is selected,
227      * or there is no RowMapper, this will return -1.
228       */

229     int getMaxSelectionRow();
230
231     /**
232       * Returns true if the row identified by <code>row</code> is selected.
233       */

234     boolean isRowSelected(int row);
235
236     /**
237      * Updates this object's mapping from TreePaths to rows. This should
238      * be invoked when the mapping from TreePaths to integers has changed
239      * (for example, a node has been expanded).
240      * <p>
241      * You do not normally have to call this; JTree and its associated
242      * listeners will invoke this for you. If you are implementing your own
243      * view class, then you will have to invoke this.
244      */

245     void resetRowSelection();
246
247     /**
248      * Returns the lead selection index. That is the last index that was
249      * added.
250      */

251     int getLeadSelectionRow();
252
253     /**
254      * Returns the last path that was added. This may differ from the
255      * leadSelectionPath property maintained by the JTree.
256      */

257     TreePath JavaDoc getLeadSelectionPath();
258
259     /**
260      * Adds a PropertyChangeListener to the listener list.
261      * The listener is registered for all properties.
262      * <p>
263      * A PropertyChangeEvent will get fired when the selection mode
264      * changes.
265      *
266      * @param listener the PropertyChangeListener to be added
267      */

268     void addPropertyChangeListener(PropertyChangeListener JavaDoc listener);
269
270     /**
271      * Removes a PropertyChangeListener from the listener list.
272      * This removes a PropertyChangeListener that was registered
273      * for all properties.
274      *
275      * @param listener the PropertyChangeListener to be removed
276      */

277     void removePropertyChangeListener(PropertyChangeListener JavaDoc listener);
278
279     /**
280       * Adds x to the list of listeners that are notified each time the
281       * set of selected TreePaths changes.
282       *
283       * @param x the new listener to be added
284       */

285     void addTreeSelectionListener(TreeSelectionListener x);
286
287     /**
288       * Removes x from the list of listeners that are notified each time
289       * the set of selected TreePaths changes.
290       *
291       * @param x the listener to remove
292       */

293     void removeTreeSelectionListener(TreeSelectionListener x);
294 }
295
Popular Tags