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