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

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