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

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