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_TreeControl_idl__
24#define __com_sun_star_awt_tree_TreeControl_idl__
25
26#ifndef __com_sun_star_awt_tree_XTreeControl_idl__
27#include <com/sun/star/awt/tree/XTreeControl.idl>
28#endif
29
30//=============================================================================
31
32module com {  module sun {  module star {  module awt { module tree {
33
34//=============================================================================
35
36/** A control that displays a set of hierarchical data as an outline.
37
38	<p>
39	<h4>The Data Model</h4>
40	<p>A specific node in a tree is identified by a <type>XTreeNode</type>.
41	A leaf node is a node without any children and that returns <FALSE/> when calling <member>XTreeNode::hasChildrenOnDemand()</member>.
42	An expanded node is a non-leaf node that will displays its children when all its ancestors are expanded.
43	A collapsed node is one which hides them.
44	A node is visible when all parent nodes are expanded and the node itself is in the display area.
45	</p>
46
47	<p>The nodes are retrieved from a <type>XTreeDataModel</type>.
48	You can implement it yourself or use the <type>MutableTreeDataModel</type>
49	which uses <type>XMutableTreeNode</type> and <type>XMutableTreeDataModel</type>
50	for a simple and mutable data model.
51
52	<p>The data model must be set at the <member>TreeControlModel::TreeDataModel</member> property.</p>
53
54	<h4>Selection</h4>
55	<p>If you are interested in knowing when the selection changes implement a
56	<type scope="com::sun::star::view">XSelectionChangeListener</type> and add the instance with the method
57	<member scope="::com::sun::star::view">XSelectionSupplier::addSelectionChangeListener()</member>.
58	You than will be notified for any selection change.
59	</p>
60
61	<p>
62	If you are interested in detecting either double-click events or when a user clicks on a node,
63	regardless of whether or not it was selected, you can get the <type scope="com::sun::star::awt">XWindow</type>
64	and add yourself as a <type scope="com::sun::star::awt">XMouseClickHandler</type>. You can use the
65	method <member>XTreeControl::getNodeForLocation()</member> to retrieve the node that was under the
66	mouse at the time the event was fired.
67	</p>
68
69	<h4>Adding child nodes on demand</h4>
70	<p>If you want to add child nodes to your tree on demand you can do the following.
71	<ul>
72	<li>Make sure the parent node returns <TRUE/> for <member>XTreeNode::hasChildrenOnDemand()</member> either
73	by implementing <type>XTreeNode</type> yourself or if you use the <type>MutableTreeDataModel</type>,
74	use <member>XMutableTreeNode::setHasChildrenOnDemand()</member>.</li>
75	<li>Implement a <type>XTreeExpansionListener</type> and add the instance with the method
76	<member>XTreeControl::addTreeExpansionListener()</member>.</li>
77	</ul>
78	Now you get called when the node will become expanded or collapsed.
79	So on <member>XTreeExpansionListener::treeExpanding()</member> you can
80	check the <type>TreeExpansionEvent</type> if the parent node with children on demand is going to
81	be expanded and in that case add the missing child nodes. You can also veto the expansion or
82	collapsing of a parent node by using the <type>ExpandVetoException</type>.
83	</p>
84 */
85service TreeControl: XTreeControl
86{
87};
88
89//=============================================================================
90
91}; }; }; }; };
92
93#endif
94