xref: /trunk/main/offapi/com/sun/star/frame/XFrame.idl (revision ffd38472365e95f6a578737bc9a5eb0fac624a86)

/**************************************************************
 *
 * 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
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 *
 *************************************************************/


#ifndef __com_sun_star_frame_XFrame_idl__
#define __com_sun_star_frame_XFrame_idl__

#ifndef __com_sun_star_lang_XComponent_idl__
#include <com/sun/star/lang/XComponent.idl>
#endif

#ifndef __com_sun_star_awt_XWindow_idl__
#include <com/sun/star/awt/XWindow.idl>
#endif

//=============================================================================

 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 willn't be
    accessible by using the api. This mode make sense for previews.
    The root node of the tree can be a <type>Desktop</type> 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. <member>XFrame::findFrame()</member>)
        </p>

        @param Creator
            the creator (parent) of this frame

        @see XFrame::getCreator()
     */
    [oneway] 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><member>XFrame::findFrame()</member>
            <li><member>XDispatchProvider::queryDispatch()</member>
            <li><member>XComponentLoader::loadComponentFromURL()</member>
        </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
     */
    [oneway] 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 <const>FrameSearchFlag::CREATE</const>.
        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 <const>FrameSearchFlag::TASKS</const>
        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 <member>XFramesSupplier::setActiveFrame()</member>,
        then it broadcasts an <type>FrameActionEvent</type> with
        <const>FrameAction::FRAME_ACTIVATED</const>. 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 <type>FrameLoader</type>.
        </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()
    */
    [oneway] 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 <type>FrameActionEvent</type> with
        <const>FrameAction::FRAME_DEACTIVATING</const>.
        </p>

        @see XFrame::activate()
        @see XFrame::isActive()
     */
    [oneway] 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 <type scope="com::sun::star::awt">XWindow</type> 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
            <member>XController::suspend()</member> 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 <member>XController::getFrame()</member> to dispose
        the frame after you the controller agreed with a
        <member>XController::suspend()</member> 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
        <method>XFrameEventListener::frameAction</method> with
        <const>FrameAction::CONTEXT_CHANGED</const> to all listeners which
        are registered using <member>XFrame::addFrameActionListener</member>.
        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()
     */
    [oneway] void addFrameActionListener( [in]XFrameActionListener xListener );

    //-------------------------------------------------------------------------
    /** unregisters an event listener

        @param xListener
            specifies the listener which willn't be informed any longer

        @see XFrame::addFrameActionListener()
     */
    [oneway] void removeFrameActionListener( [in] XFrameActionListener xListener );
};

//=============================================================================

}; }; }; };

#endif