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_frame_XFrame_idl__ 28#define __com_sun_star_frame_XFrame_idl__ 29 30#ifndef __com_sun_star_lang_XComponent_idl__ 31#include <com/sun/star/lang/XComponent.idl> 32#endif 33 34#ifndef __com_sun_star_awt_XWindow_idl__ 35#include <com/sun/star/awt/XWindow.idl> 36#endif 37 38//============================================================================= 39 40 module com { module sun { module star { module frame { 41 42 published interface XFrameActionListener; 43 published interface XController; 44 published interface XFramesSupplier; 45 46//============================================================================= 47/** a frame object can be considered to be an "anchor" object where a component 48 can be attached to. 49 50 <p> 51 A frame can be (it's not a must!) a part of a frame tree. If not this frame willn't be 52 accessible by using the api. This mode make sense for previews. 53 The root node of the tree can be a <type>Desktop</type> implementation. 54 </p> 55 56 @see Desktop 57 */ 58published interface XFrame: com::sun::star::lang::XComponent 59{ 60 //------------------------------------------------------------------------- 61 /** is called to initialize the frame within a window - the container window. 62 63 <p> 64 This window will be used as parent for the component window and to support 65 some UI relevant features of the frame service. 66 Note: Re-parenting mustn't supported by a real frame implementation! 67 It's designed for initializing - not for setting. 68 </p> 69 70 <p>This frame will take over ownership of the window refered from 71 <var>xWindow</var>. Thus, the previous owner is not allowed to 72 dispose this window anymore. </p> 73 74 @param xWindow 75 the new container window 76 77 @see XFrame::getContainerWindow() 78 */ 79 void initialize( [in] com::sun::star::awt::XWindow xWindow ); 80 81 //------------------------------------------------------------------------- 82 /** provides access to the container window of the frame. 83 84 <p> 85 Normally this is used as the parent window of the 86 component window. 87 </p> 88 89 @return 90 the container window of this frame 91 92 @see XFrame::initialize() 93 */ 94 com::sun::star::awt::XWindow getContainerWindow(); 95 96 //------------------------------------------------------------------------- 97 /** sets the frame container that created this frame. 98 99 <p> 100 Only the creator is allowed to call this method. 101 But creator doesn't mean the implementation which creates this instance ... 102 it means the parent frame of the frame hierarchy. 103 Because; normaly a frame should be created by using the api 104 and is neccessary for searches inside the tree (e.g. <member>XFrame::findFrame()</member>) 105 </p> 106 107 @param Creator 108 the creator (parent) of this frame 109 110 @see XFrame::getCreator() 111 */ 112 [oneway] void setCreator( [in] XFramesSupplier Creator ); 113 114 //------------------------------------------------------------------------- 115 /** provides access to the creator (parent) of this frame 116 117 @returns 118 the frame container that created and contains this frame. 119 120 @see XFrame::setCreator() 121 */ 122 XFramesSupplier getCreator(); 123 124 //------------------------------------------------------------------------- 125 /** access to the name property of this frame 126 127 @returns 128 the programmatic name of this frame. 129 130 @see XFrame::setName() 131 */ 132 string getName(); 133 134 //------------------------------------------------------------------------- 135 /** sets the name of the frame. 136 137 <p> 138 Normally the name of the frame is set initially (e.g. by the creator). 139 The name of a frame will be used for identifying it if a frame search was started. 140 These searches can be forced by: 141 <ul> 142 <li><member>XFrame::findFrame()</member> 143 <li><member>XDispatchProvider::queryDispatch()</member> 144 <li><member>XComponentLoader::loadComponentFromURL()</member> 145 </ul> 146 Note: Special targets like "_blank", "_self" etc. are not allowed. 147 That's why frame names shouldn't start with a sign "_". 148 </p> 149 150 @param aName 151 the new programmatic name of this frame 152 153 @see XFrame::findFrame() 154 @see XFrame::getName() 155 @see XDispatchProvider 156 @see XComponentLoader 157 */ 158 [oneway] void setName( [in] string aName ); 159 160 //------------------------------------------------------------------------- 161 /** searches for a frame with the specified name. 162 163 <p> 164 Frames may contain other frames (e.g., a frameset) and may 165 be contained in other frames. This hierarchy is searched with 166 this method. 167 First some special names are taken into account, i.e. "", 168 "_self", "_top", "_blank" etc. <var>SearchFlags</var> is ignored when 169 comparing these names with <var>TargetFrameName</var>; further steps are 170 controlled by <var>SearchFlags</var>. If allowed, the name of the frame 171 itself is compared with the desired one, and then ( again if allowed ) 172 the method is called for all children of the frame. Finally may be called 173 for the siblings and then for parent frame (if allowed). 174 </p> 175 176 <p> 177 List of special target names: 178 <table border=1> 179 <tr><td>""/"_self"</td><td>address the starting frame itself</td></tr> 180 <tr><td>"_parent"</td><td>address the direct parent frame only</td></tr> 181 <tr><td>"_top"</td><td>address the top frame of this subtree of the frametree</td></tr> 182 <tr><td>"_blank"</td><td>creates a new top frame</td></tr> 183 </table> 184 </p> 185 186 <p> 187 If no frame with the given name is found, a new top frame is 188 created; if this is allowed by a special flag <const>FrameSearchFlag::CREATE</const>. 189 The new frame also gets the desired name. 190 </p> 191 192 @param aTargetFrameName 193 identify 194 <ul><li>(a) a special target ("_blank","_self" ...) or</li> 195 <li>(b) any well known frame</li><ul> 196 to search it inside the current hierarchy 197 198 @param nSearchFlags 199 optional parameter to regulate search if no special target was used for <var>TargetFrameName</var> 200 201 @see FrameSearchFlag 202 */ 203 XFrame findFrame( 204 [in] string aTargetFrameName, 205 [in] long nSearchFlags); 206 207 //------------------------------------------------------------------------- 208 /** determines if the frame is a top frame. 209 210 <p> 211 In general a top frame is the frame which is a direct child of 212 a task frame or which does not have a parent. Possible frame searches must 213 stop the search at such a frame unless the flag <const>FrameSearchFlag::TASKS</const> 214 is set. 215 </p> 216 217 @return 218 <TRUE/> if frame supports top frame specification 219 <br> 220 <FALSE/> otherwise 221 */ 222 boolean isTop(); 223 224 //------------------------------------------------------------------------- 225 /** activates this frame and thus the component within. 226 227 <p> 228 At first the frame sets itself as the active frame of its 229 creator by calling <member>XFramesSupplier::setActiveFrame()</member>, 230 then it broadcasts an <type>FrameActionEvent</type> with 231 <const>FrameAction::FRAME_ACTIVATED</const>. The component within 232 this frame may listen to this event to grab the focus on activation; 233 for simple components this can be done by the <type>FrameLoader</type>. 234 </p> 235 236 <p> 237 Finally, most frames may grab the focus to one of its windows 238 or forward the activation to a sub-frame. 239 </p> 240 241 @see XFrame::deactivate() 242 @see XFrame::isActive() 243 */ 244 [oneway] void activate(); 245 246 //------------------------------------------------------------------------- 247 /** is called by the creator frame when another sub-frame gets activated. 248 249 <p> 250 At first the frame deactivates its active sub-frame, if any. 251 Then broadcasts a <type>FrameActionEvent</type> with 252 <const>FrameAction::FRAME_DEACTIVATING</const>. 253 </p> 254 255 @see XFrame::activate() 256 @see XFrame::isActive() 257 */ 258 [oneway] void deactivate(); 259 260 //------------------------------------------------------------------------- 261 /** determines if the frame is active. 262 263 @return 264 <TRUE/> for active or UI active frames 265 <br> 266 <FALSE/> otherwise 267 268 @see XFrame::activate() 269 @see XFrame::deactivate() 270 */ 271 boolean isActive(); 272 273 //------------------------------------------------------------------------- 274 /** sets a new component into the frame or release an existing one from a frame. 275 276 @param xComponentWindow 277 the window of the new component or <NULL/> for release 278 279 <p> 280 A valid component window should be a child of the frame container window. 281 </p> 282 283 @param xController 284 the controller of the new component or <NULL/> for release 285 286 <p> 287 Simple components may implement a <type scope="com::sun::star::awt">XWindow</type> only. 288 In this case no controller must be given here. 289 </p> 290 291 @return 292 <TRUE/>if setting of new component or release of an existing one was successfully 293 <br> 294 <FALSE/> otherwise (especialy, if an existing controller disagree within his 295 <member>XController::suspend()</member> call) 296 297 @see XFrame::getComponentWindow() 298 @see XFrame::getContainerWindow() 299 @see XFrame::getController() 300 */ 301 boolean setComponent( 302 [in] com::sun::star::awt::XWindow xComponentWindow, 303 [in] XController xController); 304 305 //------------------------------------------------------------------------- 306 /** provides access to the component window 307 308 <p> 309 Note: Don't dispose this window - the frame is the owner of it. 310 </p> 311 312 @returns 313 the current visible component in this frame 314 <br> 315 or <NULL/> if no one currently exist 316 317 @see XFrame::setComponent() 318 */ 319 com::sun::star::awt::XWindow getComponentWindow(); 320 321 //------------------------------------------------------------------------- 322 /** provides access to the controller 323 324 <p> 325 Note: Don't dispose it - the frame is the owner of it. 326 Use <member>XController::getFrame()</member> to dispose 327 the frame after you the controller agreed with a 328 <member>XController::suspend()</member> call. 329 </p> 330 331 @returns 332 the current controller within this frame 333 <br> 334 or <NULL/> if no one currently exist 335 336 @see XFrame::setComponent() 337 */ 338 XController getController(); 339 340 //------------------------------------------------------------------------- 341 /** notifies the frame that the context of the controller within this 342 frame changed (i.e. the selection). 343 344 <p> 345 According to a call to this interface, the frame calls 346 <method>XFrameEventListener::frameAction</method> with 347 <const>FrameAction::CONTEXT_CHANGED</const> to all listeners which 348 are registered using <member>XFrame::addFrameActionListener</member>. 349 For external controllers this event can be used to requery dispatches. 350 351 @see XFrameEventListener 352 @see FrameAction 353 @see XFrame::addFrameActionListener() 354 */ 355 void contextChanged(); 356 357 //------------------------------------------------------------------------- 358 /** registers an event listener, which will be called when certain things 359 happen to the components within this frame or within sub-frames of this frame. 360 361 <p> 362 E.g., it is possible to determine instantiation/destruction and 363 activation/deactivation of components. 364 </p> 365 366 @param xListener 367 specifies the listener which will be informed 368 369 @see XFrame::removeFrameActionListener() 370 */ 371 [oneway] void addFrameActionListener( [in]XFrameActionListener xListener ); 372 373 //------------------------------------------------------------------------- 374 /** unregisters an event listener 375 376 @param xListener 377 specifies the listener which willn't be informed any longer 378 379 @see XFrame::addFrameActionListener() 380 */ 381 [oneway] void removeFrameActionListener( [in] XFrameActionListener xListener ); 382}; 383 384//============================================================================= 385 386}; }; }; }; 387 388#endif 389