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 */
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
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.
|
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}
44 * will return null.
45 *
46 * <p>
47 *
48 * A TreeSelectionModel can be configured to allow only one
49 * path ({@code SINGLE_TREE_SELECTION}) a number of
50 * contiguous paths ({@code CONTIGUOUS_TREE_SELECTION}) or a number of
51 * discontiguous paths ({@code DISCONTIGUOUS_TREE_SELECTION}).
52 * A {@code RowMapper} is used to determine if TreePaths are
53 * contiguous.
54 * In the absence of a RowMapper {@code CONTIGUOUS_TREE_SELECTION} and
55 * {@code DISCONTIGUOUS_TREE_SELECTION} 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} any
61 * time the paths are changed ({@code setSelectionPath},
62 * {@code addSelectionPath} ...) 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}. 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}, and
78 * not two copies of {@code treePath}.
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},
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},
120 * {@code CONTIGUOUS_TREE_SELECTION} or
121 * {@code DISCONTIGUOUS_TREE_SELECTION}.
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} is
130 * null, this has the same effect as invoking {@code clearSelection}.
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} is
139 * null, this has the same effect as invoking {@code clearSelection}.
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} 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} 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} 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}
176 * are in the selection, the TreeSelectionListeners are notified.
177 * This method has no effect if {@code paths} 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}.
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}, 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
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} 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.
|