offapi/com/sun/star/frame/XLayoutManager.idl

   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
  65 module 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.0
  99 */
 100
 101 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