1 /*
2 * Copyright 2006-2016 The JGUIraffe Team.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License")
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package net.sf.jguiraffe.gui.builder.components.model;
17
18 import net.sf.jguiraffe.gui.forms.ComponentHandler;
19
20 import org.apache.commons.configuration.HierarchicalConfiguration;
21
22 /**
23 * <p>
24 * A specialized <code>ComponentHandler</code> interface for dealing with tree
25 * components.
26 * </p>
27 * <p>
28 * A tree component provides some enhanced functionality not covered by the
29 * default methods defined in the <code>ComponentHandler</code> interface.
30 * Therefore this interface is available for accessing this special
31 * functionality. New methods have been introduced for dealing for instance with
32 * querying the tree's selection or registering special event handlers.
33 * </p>
34 * <p>
35 * Note that this <code>ComponentHandler</code> is of type <code>Object</code>.
36 * This is due to the fact that a tree supports both single and multiple
37 * selections. In the former case the handler's data is an object of type
38 * <code>{@link TreeNodePath}</code>. In the latter case it is an array of this
39 * type.
40 * </p>
41 *
42 * @author Oliver Heger
43 * @version $Id: TreeHandler.java 205 2012-01-29 18:29:57Z oheger $
44 */
45 public interface TreeHandler extends ComponentHandler<Object>
46 {
47 /**
48 * Returns the path to the selected node. This method can be used for trees
49 * supporting single selection only. The <code>TreeNodePath</code> object
50 * returned points to the selected node. If nothing is selected, result will
51 * be <b>null</b>.
52 *
53 * @return the path to the selected node
54 */
55 TreeNodePath getSelectedPath();
56
57 /**
58 * Sets a single selected node. Using this method the selection of the tree
59 * is set to exactly one node.
60 *
61 * @param path the path to the selected node (must not be <b>null</b>)
62 */
63 void setSelectedPath(TreeNodePath path);
64
65 /**
66 * Returns an array with the paths to all selected nodes. This method can be
67 * used if multiple selection is active for querying all selected nodes at
68 * once. If nothing is selected, an empty array is returned.
69 *
70 * @return an array with the paths of all selected nodes
71 */
72 TreeNodePath[] getSelectedPaths();
73
74 /**
75 * Adds the specified path to the selection of the tree. With this method
76 * the selection can be extended. For this to work the tree must support
77 * multiple selection.
78 *
79 * @param path the path pointing to the node which should be added to the
80 * selection (must not be <b>null</b>)
81 */
82 void addSelectedPath(TreeNodePath path);
83
84 /**
85 * Removes the selection. After calling this method no node is selected any
86 * more.
87 */
88 void clearSelection();
89
90 /**
91 * Adds a <code>TreeExpansionListener</code> to this tree component. This
92 * listener will be notified whenever a node of this tree is expanded or
93 * collapsed.
94 *
95 * @param l the listener to add (must not be <b>null</b>)
96 * @throws IllegalArgumentException if the listener is <b>null</b>
97 */
98 void addExpansionListener(TreeExpansionListener l);
99
100 /**
101 * Removes the specified expansion listener from this tree component.
102 *
103 * @param l the listener to remove
104 */
105 void removeExpansionListener(TreeExpansionListener l);
106
107 /**
108 * Adds a <code>TreePreExpansionListener</code> to this tree component. This
109 * listener will be notified whenever a tree node is about to be expanded or
110 * collapsed and has the opportunity to forbid this operation.
111 *
112 * @param l the listener to add (must not be <b>null</b>)
113 * @throws IllegalArgumentException if the listener is <b>null</b>
114 */
115 void addPreExpansionListener(TreePreExpansionListener l);
116
117 /**
118 * Removes the specified <code>TreePreExpansionListener</code> from this
119 * tree component.
120 *
121 * @param l the listener to remove
122 */
123 void removePreExpansionListener(TreePreExpansionListener l);
124
125 /**
126 * Expands the node specified by the given path.
127 *
128 * @param path the path
129 */
130 void expand(TreeNodePath path);
131
132 /**
133 * Collapses the node specified by the given path.
134 *
135 * @param path the path
136 */
137 void collapse(TreeNodePath path);
138
139 /**
140 * Returns the tree's data model. This is a hierarchical configuration
141 * object. By manipulating this configuration the tree's content can be
142 * changed.
143 *
144 * @return the configuration that serves as data model for this tree
145 */
146 HierarchicalConfiguration getModel();
147 }