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