/* -*- 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 .
 */


 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 );
};


}; }; }; };

/* vim:set shiftwidth=4 softtabstop=4 expandtab: */