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

/** this is a simple interface to load components by a URL into a
    frame environment

    @see Desktop
    @see Frame
    @see XFrame
 */
published interface XComponentLoader: com::sun::star::uno::XInterface
{
    /** loads a component specified by a URL into the specified
        new or existing frame.

        @param URL
            specifies the URL of the document to load

            <p>
            To create new documents, use "private:factory/scalc", "private:factory/swriter", etc.
            Other special protocols (e.g. "slot:", ".uno") are not allowed and raise
            a com::sun::star::lang::IllegalArgumentException.
            </p>

        @param TargetFrameName
            specifies the name of the frame to view the document in

            <p>
            If a frame with the specified name already exists, it is used, otherwise it
            is created. There exist some special targets which never can be used
            as real frame names:
            <table border=1>
                <tr>
                    <td><strong>"_blank"</strong></td>
                    <td>always creates a new frame</td>
                </tr>
                <tr>
                    <td><strong>"_default"</strong></td>
                    <td>special UI functionality<br>(e.g. detecting of already loaded documents, using of empty frames of creating of new top frames as fallback)</td>
                </tr>
                <tr>
                    <td><strong>"_self", ""(!)</strong></td>
                    <td>means frame himself</td>
                </tr>
                <tr>
                    <td><strong>"_parent"</strong></td>
                    <td>address direct parent of frame</td>
                </tr>
                <tr>
                    <td><strong>"_top"</strong></td>
                    <td>indicates top frame of current path in tree</td>
                </tr>
                <tr>
                    <td><strong>"_beamer"</strong></td>
                    <td>means special sub frame</td>
                </tr>
            </table>

        @param SearchFlags
            use the values of FrameSearchFlag to specify
            how to find the specified <var>TargetFrameName</var>

            <p>
            Note: These flags are optional ones and will be used for non special
            target names only.
            </p>

        @param Arguments
            these arguments specify component or filter specific behavior

            <p>
            For example, "ReadOnly" with a boolean value specifies whether
            the document is opened read-only. "FilterName" specifies the
            component type to create and the filter to use, for example:
            "Text - CSV". For more information see
            com::sun::star::document::MediaDescriptor.
            </p>

        @return
            a com::sun::star::lang::XComponent for successfully loaded
            documents or
            <br>
            `NULL`if it failed

            <p>
            This interface is a generic one and can be used to start further requests on
            loaded document or control the lifetime of it (means dispose() it after using).
            The real document service behind this interface can be one of follow three ones:
            <ul>
                <li>
                    com::sun::star::awt::XWindow for simple components<br/>
                    Should be used for viewable components only. It is not allowed to dispose
                    it after use directly, because the frame containing the component is its owner.
                    Because the frame object is not accessible through the interface too,
                    only an interacting user can do this by closing the frame's window.
                </li>
                <li>
                    XController for richer components<br/>
                    Should be used for real editable components which doesn't need a model.
                    It is not allowed to dispose it after use directly, because the frame
                    containing the component is its owner. Here the object can be disposed
                    by disposing the frame, that the XController::getFrame()
                    method of the controller returns. But for visible components the controller
                    should be asked for permission by calling XController::suspend() before.
                </li>
                <li>
                    XModel for full featured components<br/>
                    A model that in general can be shared between several view/controller pairs,
                    does not have an explicit owner. Every view and also the component that
                    loaded the document may consider itself as an owner.
                    Simply calling com::sun::star::lang::XComponent::dispose() on this model may
                    cause problems, if some members of the "owner community" are currently
                    busy working on the model. These problems are handled by explicit closing
                    negotiations through the interface com::sun::star::util::XCloseable.
                    Direct dispose of the model is allowed only, if this special interface doesn't exist.
                </li>
            </ul>
            </p>

        @throws com::sun::star::io::IOException
            when <var>URL</var> couldn't be found or was corrupt

        @throws com::sun::star::lang::IllegalArgumentException
            when given parameters doesn't perform the specification
     */
    com::sun::star::lang::XComponent loadComponentFromURL(
        [in] string URL,
        [in] string TargetFrameName,
        [in] long SearchFlags,
        [in] sequence<com::sun::star::beans::PropertyValue> Arguments)
        raises( com::sun::star::io::IOException,
                com::sun::star::lang::IllegalArgumentException );
};


}; }; }; };

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