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