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<<type>XTreeNode</type>>.</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<<type>XTreeNode</type>> 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 overridden 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 overridden 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 @param 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