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  ;
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   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  [] 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   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  [] 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   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  [] 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   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  [] 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   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   newMapper);
203 
204     /**
205      * Returns the RowMapper instance that is able to map a TreePath to a
206      * row.
207      */
208     RowMapper   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   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   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   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags