1/**************************************************************
2 *
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements.  See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership.  The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License.  You may obtain a copy of the License at
10 *
11 *   http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied.  See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 *
20 *************************************************************/
21
22
23#ifndef __com_sun_star_awt_tree_XTreeControl_idl__
24#define __com_sun_star_awt_tree_XTreeControl_idl__
25
26#ifndef __com_sun_star_awt_XControl_idl__
27#include <com/sun/star/awt/XControl.idl>
28#endif
29
30#ifndef __com_sun_star_awt_tree_XTreeExpansionListener_idl__
31#include <com/sun/star/awt/tree/XTreeExpansionListener.idl>
32#endif
33
34#ifndef __com_sun_star_view_XMultiSelectionSupplier_idl__
35#include <com/sun/star/view/XMultiSelectionSupplier.idl>
36#endif
37
38#ifndef __com_sun_star_awt_tree_XTreeEditListener_idl__
39#include <com/sun/star/awt/tree/XTreeEditListener.idl>
40#endif
41
42//=============================================================================
43
44module com {  module sun {  module star {  module awt { module tree {
45
46//=============================================================================
47
48/** An interface to a control that displays a set of hierarchical data as an outline.
49
50    @see TreeControl
51 */
52published interface XTreeControl
53{
54    /**	This interfaces provides access to the selection of tree nodes for this control.
55
56        <p>valid selection values for this interface are
57        <type>XTreeNode</type> or sequence&lt;<type>XTreeNode</type>&gt;.</p>
58
59        <method scope="::com::sun::star::view">XSelectionSupplier::getSelection()</method>
60        returns an emtpy any for no selection, an any with <type>XTreeNode</type> for
61        a single selection and a sequence&lt;<type>XTreeNode</type>&gt; for a multiselection.
62    */
63    interface ::com::sun::star::view::XMultiSelectionSupplier;
64
65    // ----------------------------
66    // expanding/collapsing/visible
67    // ----------------------------
68
69    /** Returns <TRUE/> if <var>Node</var> is currently expanded.
70
71        @param Node
72            the <type>XTreeNode</type> specifying the node to check.
73
74        @returns
75            <FALSE/> if <var>Node</var> or at least one of its parent nodes are collapsed,
76            <TRUE/> if <var>Node</var> and all of its parent nodes are expanded.
77
78        @throws ::com::sun::star::lang::IllegalArgumentException
79            if <var>Node</var> is not a valid node of the corresponding <type>XTreeDataModel</type>.
80    */
81    boolean isNodeExpanded( [in] XTreeNode Node )
82        raises( ::com::sun::star::lang::IllegalArgumentException );
83
84    /** Returns <TRUE/> if <var>Node</var> is currently collapsed.
85
86        @param Node
87            the <type>XTreeNode</type> specifying the node to check
88
89        @returns
90            <TRUE/> if <var>Node</var> or at least one of its parent nodes are collapsed,
91            <FALSE/> if <var>Node</var> and all of its parent nodes are expanded
92
93        @throws ::com::sun::star::lang::IllegalArgumentException
94            if <var>Node</var> is not a valid node of the corresponding <type>XTreeDataModel</type>.
95    */
96    boolean isNodeCollapsed( [in] XTreeNode Node )
97        raises( ::com::sun::star::lang::IllegalArgumentException );
98
99    /** Ensures that <var>Node</var> is currently visible.
100        <p>This includes expanding all parent nodes and scroll the control so this
101        node is visible in the controls display area.</p>
102
103        @param Node
104            the <type>XTreeNode</type> specifying the node to make visible.
105
106        @throws ::com::sun::star::lang::IllegalArgumentException
107            if <var>Node</var> is not a valid node of the corresponding <type>XTreeDataModel</type>.
108
109        @throws ExpandVetoException
110            if <var>Node</var>can't be made visible since at least one of the parent nodes are
111            collapsed and expanding failed because at least one of the registered
112            <type>XTreeExpansionListener</type> raised a <type>ExpandVetoException</type>.
113    */
114    void makeNodeVisible( [in] XTreeNode Node )
115        raises( com::sun::star::lang::IllegalArgumentException, ExpandVetoException );
116
117    /** Returns <TRUE/> if <var>Node</var> is currently visible.
118        <p>Visible means it is either the root or all of its parents are expanded.</p>
119
120        @returns
121            <TRUE/> if <var>Node</var> is visible, otherwise <FALSE/>
122
123        @throws ::com::sun::star::lang::IllegalArgumentException
124            if <var>Node</var> is not a valid node of the corresponding <type>XTreeDataModel</type>.
125    */
126    boolean isNodeVisible( [in] XTreeNode Node )
127        raises( com::sun::star::lang::IllegalArgumentException );
128
129    /** Ensures that <var>Node</var> is expanded and visible.
130        <p>If <var>Node</var> is a leaf node, this will have no effect.</p>
131
132        @param Node
133            the <type>XTreeNode</type> identifying a node.
134
135        @throws ::com::sun::star::lang::IllegalArgumentException
136            if <var>Node</var> is not a valid node of the corresponding <type>XTreeDataModel</type>.
137
138        @throws ExpandVetoException
139            if expanding <var>Node</var> failed because at least one of the registered
140            <type>XTreeExpansionListener</type> raised a <type>ExpandVetoException</type>.
141    */
142    void expandNode( [in] XTreeNode Node )
143        raises( com::sun::star::lang::IllegalArgumentException, ExpandVetoException );
144
145    /** Ensures that <var>Node</var> is collapsed.
146
147        @param Node
148            the <type>XTreeNode</type> identifying a node
149
150        @throws ::com::sun::star::lang::IllegalArgumentException
151            if <var>Node</var> is not a valid node of the corresponding <type>XTreeDataModel</type>.
152
153        @throws ExpandVetoException
154            if collapsing <var>Node</var> failed because at least one of the registered
155            <type>XTreeExpansionListener</type> raised a <type>ExpandVetoException</type>.
156    */
157    void collapseNode( [in] XTreeNode Node )
158        raises( com::sun::star::lang::IllegalArgumentException, ExpandVetoException );
159
160    /** Adds a listener for <type>TreeExpansion</type> events.
161
162        @param Listener
163            a <type>XTreeExpansionListener</type> that will be notified when a tree
164            node is expanded or collapsed.
165    */
166    void addTreeExpansionListener( [in] XTreeExpansionListener Listener );
167
168    /** Removes a listener for <type>TreeExpansion</type> events.
169
170        @param Listener
171            the <type>XTreeExpansionListener</type> to remove.
172    */
173    void removeTreeExpansionListener( [in] XTreeExpansionListener Listener );
174
175    /** If the given URL points to a loadable graphic, the graphic is rendered
176        before expanded non leaf nodes.
177
178        <p>This can be overriden for individual nodes by <member>XTreeNode::getExpandedGraphicURL()</member></p>
179    */
180    [attribute] string DefaultExpandedGraphicURL;
181
182    /** If the given URL points to a loadable graphic, the graphic is rendered
183        before collapsed non leaf nodes.
184
185        <p>This can be overriden for individual nodes by <member>XTreeNode::getCollapsedGraphicURL()</member></p>
186    */
187    [attribute] string DefaultCollapsedGraphicURL;
188
189    // ------------
190    // tree geometry
191    // ------------
192
193    /** Returns the node at the specified location.
194
195        @param x
196            an integer giving the number of pixels horizontally from the left edge of the controls display area
197        @param y
198            an integer giving the number of pixels vertically from the top edge of the controls display area
199        @returns
200            the <type>XTreeNode</type> for the node at that location, or 0 if there is no node at the given position
201    */
202    XTreeNode getNodeForLocation( [in] long x, [in] long y );
203
204    /** Returns the node that is closest to x,y.
205        <p>If no nodes are currently viewable, or there is no model, returns null,
206        otherwise it always returns a valid node. To test if the node is exactly
207        at x, y, use <member>getNodeForLocation()</member>.
208
209        @param x
210            an integer giving the number of pixels horizontally from the left edge of the controls display area
211        @para y
212            an integer giving the number of pixels vertically from the top edge of the controls display area
213        @returns
214            the <type>XTreeNode</type> for the node closest to that location, null if nothing is viewable or there is no model
215    */
216    XTreeNode getClosestNodeForLocation( [in] long x, [in] long y );
217
218    /** returns the rectangle occupied by the visual representation of the given node
219
220        @param Node
221            the node whose geometry should be obtained
222        @throws ::com::sun::star::lang::IllegalArgumentException
223            if the given node is <NULL/>, or does not belong to the tree's data model
224    */
225    ::com::sun::star::awt::Rectangle
226        getNodeRect( [in] XTreeNode Node )
227            raises( ::com::sun::star::lang::IllegalArgumentException );
228
229    // ------------
230    // tree editing
231    // ------------
232
233    /** Returns <TRUE/> if one of tree's nodes is being currently edited.
234        <p>The node that is being edited can be obtained using <method scope="com::sun::star::view">XSelectionSupplier::getSelection()</method>.
235
236        @returns
237            <TRUE/> if the user is currently editing a node
238    */
239    boolean isEditing();
240
241    /** Ends the current editing session.
242        <p>All registered <type>XTreeEditListener</type> are notified if an editing session was in progress</p>
243        <p>Has no effect if the tree isn't being edited.</p>
244
245        @returns
246            <TRUE/> if editing was in progress and is now stopped, <FALSE/> if editing was not in progress
247    */
248    boolean stopEditing();
249
250    /** Cancels the current editing session.
251        <p>Has no effect if the tree isn't being edited.</p>
252    */
253    void cancelEditing();
254
255    /** Selects <var>Node</var> and initiates editing.
256
257        <p>If <member>TreeControlModel::Editable</member> is <FALSE/> or if there are no
258        registered <type>XTreeEditListener</type>, this call has no effect.</p>
259
260        <p>Calling this method also ensures that <var>Node</var> will become visible.</p>
261
262        @param Node
263            the <type>XTreeNode</type> identifying a node.
264
265        @throws ::com::sun::star::lang::IllegalArgumentException
266            if <var>Node</var> is not a valid node of the corresponding <type>XTreeDataModel</type>.
267    */
268    void startEditingAtNode( [in] XTreeNode Node )
269        raises( ::com::sun::star::lang::IllegalArgumentException );
270
271    /** Adds a <type>XTreeEditListener</type>.
272
273        @param xListener
274            a <type>XTreeEditListener</type> that will be notified
275            before and after a tree node is edited.
276    */
277    void addTreeEditListener( [in] XTreeEditListener Listener );
278
279    /** Removes a <type>XTreeEditListener</type>.
280
281        @param xListener
282            the <type>XTreeEditListener</type> to remove
283    */
284    void removeTreeEditListener( [in] XTreeEditListener Listener );
285};
286
287//=============================================================================
288
289}; }; }; }; };
290
291#endif
292