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 28#ifndef __com_sun_star_frame_XLayoutManager_idl__ 29#define __com_sun_star_frame_XLayoutManager_idl__ 30 31#ifndef __com_sun_star_uno_XInterface_idl__ 32#include <com/sun/star/uno/XInterface.idl> 33#endif 34 35#ifndef __com_sun_star_frame_XFrame_idl__ 36#include <com/sun/star/frame/XFrame.idl> 37#endif 38 39#ifndef __com_sun_star_awt_Point_idl__ 40#include <com/sun/star/awt/Point.idl> 41#endif 42 43#ifndef __com_sun_star_awt_Size_idl__ 44#include <com/sun/star/awt/Size.idl> 45#endif 46 47#ifndef __com_sun_star_awt_XWindow_idl__ 48#include <com/sun/star/awt/XWindow.idl> 49#endif 50 51#ifndef __com_sun_star_ui_XUIElement_idl__ 52#include <com/sun/star/ui/XUIElement.idl> 53#endif 54 55#ifndef __com_sun_star_ui_DockingArea_idl__ 56#include <com/sun/star/ui/DockingArea.idl> 57#endif 58 59#ifndef __com_sun_star_ui_XDockingAreaAcceptor_idl__ 60#include <com/sun/star/ui/XDockingAreaAcceptor.idl> 61#endif 62 63//============================================================================= 64 65module com { module sun { module star { module frame { 66 67//============================================================================= 68 69/** central interface to query for, create, destroy and manipulate user 70 interface elements which are bound to a layout manager. 71 72 <p> 73 Every user interface element which is controlled by a layout manager has 74 a unique identifier called resource URL. 75 76 A resourcce URL must meet the following syntax: 77 "private:resource/$type/$name". It is only allowed to use ascii characters 78 for type and name. 79 80 Currently the following user interface element types are defined: 81 <ul> 82 <li><b>menubar</b>A configurable user interface element representing 83 a menu bar.</li> 84 <li><b>popupmenu</b>A configurable user interface element representing 85 a popup menu.</li> 86 <li><b>toolbar</b>A configurable user interface element a tool 87 bar.</li> 88 <li><b>statusbar</b>A configurable user interfave element representing 89 a status bar.</li> 90 <li><b>floater</b>A basic user interface element representing a 91 floating window.</li> 92 </ul> 93 94 @see com::sun::star::ui::UIElementTypes 95 @see com::sun::star::frame::XFrame 96 </p> 97 98 @since OOo 2.0 99*/ 100 101published interface XLayoutManager : com::sun::star::uno::XInterface 102{ 103 /** attaches a <type scope="com::sun::star::frame">XFrame</type> to a layout manager. 104 105 @param Frame 106 specifies the frame that should be attached to the layout manager 107 108 <p> 109 A layout manager needs a <type scope="com::sun::star::frame">XFrame</type> to be 110 able to work. Without a it no user interface elements can be created. 111 </p> 112 */ 113 void attachFrame( [in] com::sun::star::frame::XFrame Frame ); 114 115 /** resets the layout manager and remove all of its internal user interface 116 elements. 117 118 <p> 119 This call should be handled with care as all user interface elements will 120 be destroyed and the layout manager is reseted to a state after a 121 <member>attachFrame</member> has been made. That means an attached frame 122 which has been set by <member>attachFrame</member> is not released. 123 The layout manager itself calls reset after a component has been attached 124 or reattached to a frame. 125 </p> 126 */ 127 void reset(); 128 129 /** provides the current docking area size of the layout manager. 130 131 @return 132 The <type scope="com::sun::star::awt">Rectangle</type> contains pixel values. The 133 members of <type scope="com::sun::star::awt">Rectangle</type> are filled as following: 134 <ul> 135 <li>X = docking area on left side (in pixel)</li> 136 <li>Y = docking area on top side (in pixel)</li> 137 <li>Width = docking area on right side (in pixel)</li> 138 <li>Height = docking area on bottom side (in pixel)</li> 139 </ul> 140 */ 141 com::sun::star::awt::Rectangle getCurrentDockingArea(); 142 143 /** retrieves the current docking area acceptor that controls the border space of the frame's 144 container window. 145 146 @return 147 current docking area acceptor which controls the border space of frame's container window. 148 149 <p> 150 A docking area acceptor retrieved by this method is owned by the layout manager. It is not 151 allowed to dispose this object, it will be destroyed on reference count! 152 </p> 153 */ 154 com::sun::star::ui::XDockingAreaAcceptor getDockingAreaAcceptor(); 155 156 /** sets a docking area acceptor that controls the border space of the frame's container window. 157 158 @param xDockingAreaAcceptor 159 a docking area acceptor which controls the border space of frame's container window. 160 161 <p> 162 A docking area acceptor decides if the layout manager can use requested border space for 163 docking windows. If the acceptor denies the requested space the layout manager automatically 164 set all docked windows into floating state and will not use this space for docking.<br/> 165 After setting a docking area acceptor the object is owned by the layout manager. It is not 166 allowed to dispose this object, it will be destroyed on reference count! 167 </p> 168 */ 169 void setDockingAreaAcceptor( [in] com::sun::star::ui::XDockingAreaAcceptor xDockingAreaAcceptor ); 170 171 /** creates a new user interface element. 172 173 @param ResourceURL 174 specifies which user interface element should be created. A resourcce URL must meet the following 175 syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and 176 name. 177 */ 178 void createElement( [in] string ResourceURL ); 179 180 /** destroys a user interface element. 181 182 @param ResourceURL 183 specifies which user interface element should be destroyed. A resourcce URL must meet 184 the following syntax: "private:resource/$type/$name". It is only allowed to use ascii 185 characters for type and name. 186 */ 187 void destroyElement( [in] string ResourceURL ); 188 189 /** request to make a user interface element visible if it is not in hidden state. 190 191 @param ResourceURL 192 specifies which user interface element should be made visible. A resourcce URL must 193 meet the following syntax: "private:resource/$type/$name". It is only allowed to use 194 ascii characters for type and 195 name. 196 197 @return 198 returns <TRUE/> if the user interface element could be made visible, otherwise 199 <FALSE/> will be returned. 200 201 <p> 202 If a user interface element should forced to the visible state 203 <member>XLayoutManager::showElement</member> should be used. This function can be 204 used for context dependent elements which should respect a the current visibility 205 state. 206 </p> 207 */ 208 boolean requestElement( [in] string ResourceURL ); 209 210 /** retrieves a user interface element which has been created before. 211 212 @param ResourceURL 213 specifies which user interface element should be retrieved. A resourcce URL must meet the following 214 syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and 215 name. 216 217 <p> 218 The layout manager instance is owner of the returned user interface element. That means that the life time of 219 the user interface element is controlled by the layout manager. It can be disposed at every time! 220 </p> 221 */ 222 com::sun::star::ui::XUIElement getElement( [in] string ResourceURL ); 223 224 /** retrieves all user interface elements which are currently instanciated. 225 226 @return 227 a sequence of user interface elements providing <type scope="com::sun::star::ui">XUIElement</type> 228 interface. 229 230 <p> 231 The layout manager instance is owner of the returned user interface elements. That means that the life time of 232 the user interface elements is controlled by the layout manager. They can be disposed at every time! 233 </p> 234 */ 235 sequence< com::sun::star::ui::XUIElement > getElements(); 236 237 /** shows a user interface element. 238 239 @param ResourceURL 240 specifies which user interface element should be shown. A resourcce URL must meet the following 241 syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and 242 name. 243 244 @return 245 returns <TRUE/> if the user interface element has been shown, otherwise <FALSE/> will be returned. 246 */ 247 boolean showElement( [in] string ResourceURL ); 248 249 /** hides a user interface element. 250 251 @param ResourceURL 252 specifies which user interface element should be hidden. A resourcce URL must meet the following 253 syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and 254 name. 255 256 @return 257 returns <TRUE/> if the user interface element has been hidden, otherwise <FALSE/> will be returned. 258 */ 259 boolean hideElement( [in] string ResourceURL ); 260 261 /** docks a window based user interface element to a specified docking area. 262 263 @param ResourceURL 264 specifies which user interface element should be docked. A resourcce URL must meet the following 265 syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and 266 name. 267 268 @param DockingArea 269 specifies on which docking area the window based user interface element should docked. 270 271 @param Pos 272 specifies the position inside the docking area. 273 274 @return 275 returns <TRUE/> if the user interface element has been docked, otherwise <FALSE/> will be returned. 276 277 @see com::sun::star::ui::DockingArea 278 */ 279 boolean dockWindow( [in] string ResourceURL, [in] com::sun::star::ui::DockingArea DockingArea, [in] com::sun::star::awt::Point Pos ); 280 281 /** docks all windows which are member of the provided user interface element type. 282 283 @param nElementType 284 specifies which user interface element type should be docked. 285 286 @return 287 returns <TRUE/> if all user interface elements of the requested type could be 288 docked, otherwise <FALSE/> will be returned. 289 290 @see com::sun::star::ui::UIElementType 291 */ 292 boolean dockAllWindows( [in] short nElementType ); 293 294 /** forces a window based user interface element to float. 295 296 @param ResourceURL 297 specifies which user interface element should be float. A resourcce URL must meet the following 298 syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and 299 name. 300 301 @return 302 returns <TRUE/> if the user interface element has been docked, otherwise <FALSE/> will be returned. 303 */ 304 boolean floatWindow( [in] string ResourceURL ); 305 306 /** locks a window based user interface element if it's in a docked state. 307 308 @param ResourceURL 309 specifies which user interface element should be locked. A resourcce URL must meet the following 310 syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and 311 name. 312 313 @return 314 returns <TRUE/> if the user interface element has been locked, otherwise <FALSE/> will be returned. 315 */ 316 boolean lockWindow( [in] string ResourceURL ); 317 318 /** unlocks a window based user interface element if it's in a docked state. 319 320 @param ResourceURL 321 specifies which user interface element should be unlocked. A resourcce URL must 322 meet the following syntax: "private:resource/$type/$name". It is only allowed 323 to use ascii characters for type and name. 324 325 @return 326 returns <TRUE/> if the user interface element has been unlocked, otherwise 327 <FALSE/> will be returned. 328 */ 329 boolean unlockWindow( [in] string ResourceURL ); 330 331 /** sets a new size for a window based user interface element. 332 333 @param ResourceURL 334 specifies which user interface element should be resized. A resourcce URL must meet the following 335 syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and 336 name. 337 338 @param Size 339 specifies the new size in pixel. 340 341 <p> 342 It is up to the layout manager to decide if the user interface element can be resized. The new size can be retrieved 343 by calling <member>getElementSize</member>. 344 </p> 345 */ 346 void setElementSize( [in] string ResourceURL, [in] com::sun::star::awt::Size Size ); 347 348 /** sets a new position for a window based user interface element. 349 350 @param ResourceURL 351 specifies which user interface element should be moved. A resourcce URL must meet the following 352 syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and 353 name. 354 355 @param Pos 356 specifies the new position in pixel. 357 358 <p> 359 It is up to the layout manager to decide if the user interface element can be moved. The new position can be retrieved 360 by calling <member>getElementPos</member>. 361 </p> 362 */ 363 void setElementPos( [in] string ResourceURL, [in] com::sun::star::awt::Point Pos ); 364 365 /** sets a new position and size for a window based user interface element. 366 367 @param ResourceURL 368 specifies which user interface element should be moved and resized. A resourcce URL must meet the following 369 syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and 370 name. 371 372 @param Pos 373 specifies the new position in pixel. 374 375 @param Size 376 specifies the new position in pixel. 377 378 <p> 379 It is up to the layout manager to decide if the user interface element can be moved and resized. The new position and size can 380 be retrieved by calling <member>getElementPos</member> and <member>getElementSize</member>. 381 </p> 382 */ 383 void setElementPosSize( [in] string ResourceURL, [in] com::sun::star::awt::Point Pos, [in] com::sun::star::awt::Size Size ); 384 385 /** retrieves the current visibility state of a window based user interface element. 386 387 @param ResourceURL 388 specifies for which user interface element the visibility state should be retrieved. A resource URL must meet 389 the following syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and 390 name. 391 392 @return 393 <TRUE/> if the user interface element is visible, otherwise <FALSE/>. 394 */ 395 boolean isElementVisible( [in] string ResourceURL ); 396 397 /** retrieves the current floating state of a window based user interface element. 398 399 @param ResourceURL 400 specifies for which user interface element the floating state should be retrieved. A resource URL must meet 401 the following syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and 402 name. 403 404 @return 405 <TRUE/> if the user interface element is floating, otherwise <FALSE/>. 406 */ 407 boolean isElementFloating( [in] string ResourceURL ); 408 409 /** retrieves the current docking state of a window based user interface element. 410 411 @param ResourceURL 412 specifies for which user interface element the docking state should be retrieved. A resource URL must meet 413 the following syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and 414 name. 415 416 @return 417 <TRUE/> if the user interface element is docked, otherwise <FALSE/>. 418 */ 419 boolean isElementDocked( [in] string ResourceURL ); 420 421 /** retrieves the current lock state of a window based user interface element. 422 423 @param ResourceURL 424 specifies for which user interface element the lock state should be retrieved. A resource URL must meet 425 the following syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and 426 name. 427 428 @return 429 <TRUE/> if the user interface element is locked, otherwise <FALSE/>. 430 */ 431 boolean isElementLocked( [in] string ResourceURL ); 432 433 /** retrieves the current size of a window based user interface element. 434 435 @param ResourceURL 436 specifies for which user interface element the current size should be retrieved. A resource URL must meet 437 the following syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and 438 name. 439 440 @return 441 the size in pixel of the user interface element. A non-window based user interface element provides a zero size. 442 */ 443 com::sun::star::awt::Size getElementSize( [in] string ResourceURL ); 444 445 /** retrieves the current pixel position of a window based user interface element. 446 447 @param ResourceURL 448 specifies for which user interface element the current position should be retrieved. A resource URL must meet 449 the following syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and 450 name. 451 452 @return 453 the size in pixel of the user interface element. A non-window based user interface element provides a zero size. 454 */ 455 com::sun::star::awt::Point getElementPos( [in] string ResourceURL ); 456 457 /** prohibit all layout updates until unlock is called again. 458 459 <p> 460 This call can be used to speed up the creation process of serveral user interface elements. Otherwise the layout manager 461 would calculate the layout for every creation. 462 </p> 463 */ 464 void lock(); 465 466 /** permit layout updates again. 467 468 <p> 469 This function should be called to permit layout updates. The layout manager starts to calculate the new layout after 470 this call. 471 </p> 472 */ 473 void unlock(); 474 475 /** forces a complete new layouting of all user interface elements. 476 */ 477 void doLayout(); 478 479 /** sets the layout manager to invisible state and hides all user interface elements. 480 481 <p> 482 A layout manager can be set to invisible state to force it to hide all of its 483 user interface elements. If another component wants to use the window for its 484 own user interface elements it can use this function. This function is normally 485 used to implement inplace editing. 486 </p> 487 488 @param Visible 489 provide <FALSE/> to make layout manager invisible otherwise this must be 490 set to <TRUE/>. 491 */ 492 void setVisible( [in] boolean Visible ); 493 494 /** retrieves the visibility state of a layout manager. 495 496 <p> 497 A layout manager can be set to invisible state to force it to hide all of its 498 user interface elements. If another component wants to use the window for its 499 own user interface elements it can use this function. This function is normally 500 used to implement inplace editing. 501 </p> 502 503 */ 504 boolean isVisible(); 505 506}; 507 508}; }; }; }; 509 510#endif 511