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