Adding upstream version 4:7.4.7.upstream/4%7.4.7upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 357 insertions, 0 deletions

diff --git a/offapi/com/sun/star/frame/XFrame.idl b/offapi/com/sun/star/frame/XFrame.idl
new file mode 100644
index 000000000..b2d7e41e4
--- /dev/null
+++ b/offapi/com/sun/star/frame/XFrame.idl
@@ -0,0 +1,357 @@
+/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/*
+ * This file is part of the LibreOffice project.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * This file incorporates work covered by the following license notice:
+ *
+ *   Licensed to the Apache Software Foundation (ASF) under one or more
+ *   contributor license agreements. See the NOTICE file distributed
+ *   with this work for additional information regarding copyright
+ *   ownership. The ASF licenses this file to you under the Apache
+ *   License, Version 2.0 (the "License"); you may not use this file
+ *   except in compliance with the License. You may obtain a copy of
+ *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
+ */
+#ifndef __com_sun_star_frame_XFrame_idl__
+#define __com_sun_star_frame_XFrame_idl__
+
+#include <com/sun/star/lang/XComponent.idl>
+#include <com/sun/star/awt/XWindow.idl>
+
+
+ module com {  module sun {  module star {  module frame {
+
+ published interface XFrameActionListener;
+ published interface XController;
+ published interface XFramesSupplier;
+
+/** a frame object can be considered to be an "anchor" object where a component
+    can be attached to.
+
+    <p>
+    A frame can be (it's not a must!) a part of a frame tree. If not this frame won't be
+    accessible by using the API. This mode make sense for previews.
+    The root node of the tree can be a Desktop implementation.
+    </p>
+
+    @see Desktop
+ */
+published interface XFrame: com::sun::star::lang::XComponent
+{
+    /** is called to initialize the frame within a window - the container window.
+
+        <p>
+        This window will be used as parent for the component window and to support
+        some UI relevant features of the frame service.
+        Note: Re-parenting mustn't supported by a real frame implementation!
+        It's designed for initializing - not for setting.
+        </p>
+
+        <p>This frame will take over ownership of the window referred from
+        <var>xWindow</var>.  Thus, the previous owner is not allowed to
+        dispose this window anymore. </p>
+
+        @param xWindow
+            the new container window
+
+        @see XFrame::getContainerWindow()
+     */
+    void initialize( [in] com::sun::star::awt::XWindow xWindow );
+
+    /** provides access to the container window of the frame.
+
+        <p>
+        Normally this is used as the parent window of the
+        component window.
+        </p>
+
+        @return
+            the container window of this frame
+
+        @see XFrame::initialize()
+     */
+    com::sun::star::awt::XWindow getContainerWindow();
+
+    /** sets the frame container that created this frame.
+
+        <p>
+        Only the creator is allowed to call this method.
+        But creator doesn't mean the implementation which creates this instance ...
+        it means the parent frame of the frame hierarchy.
+        Because; normally a frame should be created by using the API
+        and is necessary for searches inside the tree (e.g. XFrame::findFrame())
+        </p>
+
+        @param Creator
+            the creator (parent) of this frame
+
+        @see XFrame::getCreator()
+     */
+    void setCreator( [in] XFramesSupplier Creator );
+
+    /** provides access to the creator (parent) of this frame
+
+        @returns
+            the frame container that created and contains this frame.
+
+        @see XFrame::setCreator()
+     */
+    XFramesSupplier getCreator();
+
+    /** access to the name property of this frame
+
+        @returns
+            the programmatic name of this frame.
+
+        @see XFrame::setName()
+     */
+    string getName();
+
+    /** sets the name of the frame.
+
+        <p>
+        Normally the name of the frame is set initially (e.g. by the creator).
+        The name of a frame will be used for identifying it if a frame search was started.
+        These searches can be forced by:
+        <ul>
+            <li>XFrame::findFrame()
+            <li>XDispatchProvider::queryDispatch()
+            <li>XComponentLoader::loadComponentFromURL()
+        </ul>
+        Note: Special targets like "_blank", "_self" etc. are not allowed.
+        That's why frame names shouldn't start with a sign "_".
+        </p>
+
+        @param aName
+            the new programmatic name of this frame
+
+        @see XFrame::findFrame()
+        @see XFrame::getName()
+        @see XDispatchProvider
+        @see XComponentLoader
+     */
+    void setName( [in] string aName );
+
+    /** searches for a frame with the specified name.
+
+        <p>
+        Frames may contain other frames (e.g., a frameset) and may
+        be contained in other frames. This hierarchy is searched with
+        this method.
+        First some special names are taken into account, i.e. "",
+        "_self", "_top", "_blank" etc. <var>SearchFlags</var> is ignored when
+        comparing these names with <var>TargetFrameName</var>; further steps are
+        controlled by <var>SearchFlags</var>. If allowed, the name of the frame
+        itself is compared with the desired one, and then ( again if allowed )
+        the method is called for all children of the frame. Finally may be called
+        for the siblings and then for parent frame (if allowed).
+        </p>
+
+        <p>
+        List of special target names:
+        <table border=1>
+        <tr><td>""/"_self"</td><td>address the starting frame itself</td></tr>
+        <tr><td>"_parent"</td><td>address the direct parent frame only</td></tr>
+        <tr><td>"_top"</td><td>address the top frame of this subtree of the frametree</td></tr>
+        <tr><td>"_blank"</td><td>creates a new top frame</td></tr>
+        </table>
+        </p>
+
+        <p>
+        If no frame with the given name is found, a new top frame is
+        created; if this is allowed by a special flag FrameSearchFlag::CREATE.
+        The new frame also gets the desired name.
+        </p>
+
+        @param aTargetFrameName
+            identify
+            <ul><li>(a) a special target ("_blank","_self" ...) or</li>
+                <li>(b) any well known frame</li></ul>
+            to search it inside the current hierarchy
+
+        @param nSearchFlags
+            optional parameter to regulate search if no special target was used for <var>TargetFrameName</var>
+
+         @see FrameSearchFlag
+         */
+    XFrame findFrame(
+        [in] string aTargetFrameName,
+        [in] long nSearchFlags);
+
+    /** determines if the frame is a top frame.
+
+        <p>
+        In general a top frame is the frame which is a direct child of
+        a task frame or which does not have a parent. Possible frame searches must
+        stop the search at such a frame unless the flag FrameSearchFlag::TASKS
+        is set.
+        </p>
+
+        @return
+            `TRUE` if frame supports top frame specification
+            <br>
+            `FALSE` otherwise
+     */
+    boolean isTop();
+
+    /** activates this frame and thus the component within.
+
+        <p>
+        At first the frame sets itself as the active frame of its
+        creator by calling XFramesSupplier::setActiveFrame(),
+        then it broadcasts a FrameActionEvent with
+        FrameAction::FRAME_ACTIVATED. The component within
+        this frame may listen to this event to grab the focus on activation;
+        for simple components this can be done by the FrameLoader.
+        </p>
+
+        <p>
+        Finally, most frames may grab the focus to one of its windows
+        or forward the activation to a sub-frame.
+        </p>
+
+        @see XFrame::deactivate()
+        @see XFrame::isActive()
+    */
+    void activate();
+
+    /** is called by the creator frame when another sub-frame gets activated.
+
+        <p>
+        At first the frame deactivates its active sub-frame, if any.
+        Then broadcasts a FrameActionEvent with
+        FrameAction::FRAME_DEACTIVATING.
+        </p>
+
+        @see XFrame::activate()
+        @see XFrame::isActive()
+     */
+    void deactivate();
+
+    /** determines if the frame is active.
+
+        @return
+            `TRUE` for active or UI active frames
+            <br>
+            `FALSE` otherwise
+
+        @see XFrame::activate()
+        @see XFrame::deactivate()
+     */
+    boolean isActive();
+
+    /** sets a new component into the frame or release an existing one from a frame.
+
+        @param xComponentWindow
+            the window of the new component or `NULL` for release
+
+            <p>
+            A valid component window should be a child of the frame container window.
+            </p>
+
+        @param xController
+            the controller of the new component or `NULL` for release
+
+            <p>
+            Simple components may implement a com::sun::star::awt::XWindow only.
+            In this case no controller must be given here.
+            </p>
+
+        @return
+            `TRUE`if setting of new component or release of an existing one was successfully
+            <br>
+            `FALSE` otherwise (especially, if an existing controller disagree within his
+            XController::suspend() call)
+
+        @see XFrame::getComponentWindow()
+        @see XFrame::getContainerWindow()
+        @see XFrame::getController()
+     */
+    boolean setComponent(
+        [in] com::sun::star::awt::XWindow xComponentWindow,
+        [in] XController xController);
+
+    /** provides access to the component window
+
+        <p>
+        Note: Don't dispose this window - the frame is the owner of it.
+        </p>
+
+        @returns
+            the current visible component in this frame
+            <br>
+            or `NULL` if no one currently exist
+
+        @see XFrame::setComponent()
+     */
+    com::sun::star::awt::XWindow getComponentWindow();
+
+    /** provides access to the controller
+
+        <p>
+        Note: Don't dispose it - the frame is the owner of it.
+        Use XController::getFrame() to dispose
+        the frame after you the controller agreed with a
+        XController::suspend() call.
+        </p>
+
+        @returns
+            the current controller within this frame
+            <br>
+            or `NULL` if no one currently exist
+
+        @see XFrame::setComponent()
+     */
+    XController getController();
+
+    /** notifies the frame that the context of the controller within this
+        frame changed (i.e. the selection).
+
+        <p>
+        According to a call to this interface, the frame calls
+        XFrameActionListener::frameAction() with
+        FrameAction::CONTEXT_CHANGED to all listeners which
+        are registered using XFrame::addFrameActionListener().
+        For external controllers this event can be used to requery dispatches.
+
+        @see XFrameEventListener
+        @see FrameAction
+        @see XFrame::addFrameActionListener()
+    */
+    void contextChanged();
+
+    /** registers an event listener, which will be called when certain things
+        happen to the components within this frame or within sub-frames of this frame.
+
+        <p>
+        E.g., it is possible to determine instantiation/destruction and
+        activation/deactivation of components.
+        </p>
+
+        @param xListener
+            specifies the listener which will be informed
+
+        @see XFrame::removeFrameActionListener()
+     */
+    void addFrameActionListener( [in]XFrameActionListener xListener );
+
+    /** unregisters an event listener
+
+        @param xListener
+            specifies the listener which won't be informed any longer
+
+        @see XFrame::addFrameActionListener()
+     */
+    void removeFrameActionListener( [in] XFrameActionListener xListener );
+};
+
+
+}; }; }; };
+
+#endif
+
+/* vim:set shiftwidth=4 softtabstop=4 expandtab: */