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