001 /*
002 * Copyright 1997-2002 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.swing.tree;
027
028 import javax.swing.event.*;
029 import java.beans.PropertyChangeListener;
030
031 /**
032 * This interface represents the current state of the selection for
033 * the tree component.
034 * For information and examples of using tree selection models,
035 * see <a href="http://java.sun.com/docs/books/tutorial/uiswing/components/tree.html">How to Use Trees</a>
036 * in <em>The Java Tutorial.</em>
037 *
038 * <p>
039 * The state of the tree selection is characterized by
040 * a set of TreePaths, and optionally a set of integers. The mapping
041 * from TreePath to integer is done by way of an instance of RowMapper.
042 * It is not necessary for a TreeSelectionModel to have a RowMapper to
043 * correctly operate, but without a RowMapper <code>getSelectionRows</code>
044 * will return null.
045 *
046 * <p>
047 *
048 * A TreeSelectionModel can be configured to allow only one
049 * path (<code>SINGLE_TREE_SELECTION</code>) a number of
050 * continguous paths (<code>CONTIGUOUS_TREE_SELECTION</code>) or a number of
051 * discontiguous paths (<code>DISCONTIGUOUS_TREE_SELECTION</code>).
052 * A <code>RowMapper</code> is used to determine if TreePaths are
053 * contiguous.
054 * In the absence of a RowMapper <code>CONTIGUOUS_TREE_SELECTION</code> and
055 * <code>DISCONTIGUOUS_TREE_SELECTION</code> behave the same, that is they
056 * allow any number of paths to be contained in the TreeSelectionModel.
057 *
058 * <p>
059 *
060 * For a selection model of <code>CONTIGUOUS_TREE_SELECTION</code> any
061 * time the paths are changed (<code>setSelectionPath</code>,
062 * <code>addSelectionPath</code> ...) the TreePaths are again checked to
063 * make they are contiguous. A check of the TreePaths can also be forced
064 * by invoking <code>resetRowSelection</code>. How a set of discontiguous
065 * TreePaths is mapped to a contiguous set is left to implementors of
066 * this interface to enforce a particular policy.
067 *
068 * <p>
069 *
070 * Implementations should combine duplicate TreePaths that are
071 * added to the selection. For example, the following code
072 * <pre>
073 * TreePath[] paths = new TreePath[] { treePath, treePath };
074 * treeSelectionModel.setSelectionPaths(paths);
075 * </pre>
076 * should result in only one path being selected:
077 * <code>treePath</code>, and
078 * not two copies of <code>treePath</code>.
079 *
080 * <p>
081 *
082 * The lead TreePath is the last path that was added (or set). The lead
083 * row is then the row that corresponds to the TreePath as determined
084 * from the RowMapper.
085 *
086 * @version 1.31 05/05/07
087 * @author Scott Violet
088 */
089
090 public interface TreeSelectionModel {
091 /** Selection can only contain one path at a time. */
092 public static final int SINGLE_TREE_SELECTION = 1;
093
094 /** Selection can only be contiguous. This will only be enforced if
095 * a RowMapper instance is provided. That is, if no RowMapper is set
096 * this behaves the same as DISCONTIGUOUS_TREE_SELECTION. */
097 public static final int CONTIGUOUS_TREE_SELECTION = 2;
098
099 /** 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 }
|