xref: /trunk/main/offapi/com/sun/star/frame/Frame.idl (revision a893be29)

/**************************************************************
 *
 * 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_Frame_idl__
#define __com_sun_star_frame_Frame_idl__

#ifndef __com_sun_star_frame_XFrame_idl__
#include <com/sun/star/frame/XFrame.idl>
#endif

#ifndef __com_sun_star_frame_XDispatchProvider_idl__
#include <com/sun/star/frame/XDispatchProvider.idl>
#endif

#ifndef __com_sun_star_frame_XDispatchRecorderSupplier_idl__
#include <com/sun/star/frame/XDispatchRecorderSupplier.idl>
#endif

#ifndef __com_sun_star_frame_XDispatchProviderInterception_idl__
#include <com/sun/star/frame/XDispatchProviderInterception.idl>
#endif

#ifndef __com_sun_star_frame_XFramesSupplier_idl__
#include <com/sun/star/frame/XFramesSupplier.idl>
#endif

#ifndef __com_sun_star_task_XStatusIndicatorFactory_idl__
#include <com/sun/star/task/XStatusIndicatorFactory.idl>
#endif

#ifndef __com_sun_star_beans_XPropertySet_idl__
#include <com/sun/star/beans/XPropertySet.idl>
#endif

#ifndef __com_sun_star_frame_XDispatchInformationProvider_idl__
#include <com/sun/star/frame/XDispatchInformationProvider.idl>
#endif

#ifndef _com_sun_star_xml_UserDefinedAttributesSupplier_idl_
#include <com/sun/star/xml/UserDefinedAttributesSupplier.idl>
#endif

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

 module com {  module sun {  module star {  module frame {

//=============================================================================
/** represents the environment for a desktop component

    <p>
    Frames are the anchors for the office components and they are the components' link
    to the outside world. They create a skeleton for the whole office api infrastructure
    by building frame hierarchys. These hierarchies contains all currently loaded
    documents and make it possible to walk during these trees.
    A special service <type>Desktop</type> can(!) combine different of such trees
    to a global one which life time will be controlled by it.
    </p>

    @see Desktop
 */
published service Frame
{
    //-------------------------------------------------------------------------
    /** contains user defined attributes.

        @see    <type scope="com::sun::star::xml">UserDefinedAttributesSupplier</type>
     */
    [optional] service com::sun::star::xml::UserDefinedAttributesSupplier;

    //-------------------------------------------------------------------------
	/** allows the component to be loaded and accessed
        within the frame; it is the main connection to the
        environment of the component.
	 */
    interface XFrame;

    //-------------------------------------------------------------------------
	/** provides access to dispatchers for the frame.

        <p>
        What kind of URLs a frame accepts in the calls to <member>XDispatchProvider::queryDispatch()</member>,
		and how the returned dispatcher handles dispatches is completely implementation dependent
        (though of course the restrictions of <type>XDispatchProvider</type> must be met).
        Frame implementations may (optionally) support special targets in the call to
        <member>XDispatchProvider::queryDispatch()</member>.
        Such special targets are passed as target frame name. They may, in addition,
		require special frame search flags (see <type>FrameSearchFlag</type>), or,
		in opposite, limit the set of allowed flags.<br>
		Common special targets include:
		<ul>
                        <li><b>_blank</b><br> is used to create a new frame when dispatching the URL.</li>
            <li><b>_default</b><br> is used to recycle empty or create a new frame when dispatching the URL.</li>
            <li><b>_self</b><br> forces the frame to dispatch the URL into itself. ("" means the same)</li>
                        <li><b>_parent</b><br> dispatches the URL into the parent frame.</li>
                        <li><b>_top</b><br> dispatches the URL into the top level frame, the frame where this is invoked belongs to.</li>
		</ul>
		</p>

		@see XDispatch
        @see XFrame::findFrame()
	*/
    interface XDispatchProvider;

    //-------------------------------------------------------------------------
    /** provides information about supported commands

        @since OpenOffice 2.0
    */
    [optional] interface XDispatchInformationProvider;

    //-------------------------------------------------------------------------
    /** supports interception mechanism for dispatched URLs

        <p>
        Registered objects can intercept, suppress or deroute dispatched URLs.
        If they support another interface too (<type>XInterceptorInfo</type>)
        it's possible to perform it by directly calling of right interceptor without
        using list of all registered ones.
        </p>
	 */
    interface XDispatchProviderInterception;

    //-------------------------------------------------------------------------
    /** provides access to sub frames within this frame
	 */
    interface XFramesSupplier;

    //-------------------------------------------------------------------------
    /** supplies access to <type scope="com::sun::star::task">XStatusIndicator</type> objects
        for the component within the frame to show progresses
	 */
	[optional] interface com::sun::star::task::XStatusIndicatorFactory;

    //-------------------------------------------------------------------------
    /** if possible it sets/gets the UI title on/from the frame container window

        <p>
        It depends from the type of the frame container window. If it is a system
        task window all will be OK. Otherwise the title can't be set.
        Setting/getting of the pure value of this property must be possible in every
        case. Only showing on the UI can be fail.
        </p>
     */
    [property] string Title;

    //-------------------------------------------------------------------------
    /** provides access to the dispatch recorder of the frame

        <p>
        Such recorder can be used to record dispatch requests.
        The supplier contains a dispatch recorder and provide the functionality
        to use it for any dispatch object from outside which supports the interface
        <type>XDispatch</type>. A supplier is available only, if recording was enabled.
        That means: if somewhere whish to enable recoding on a frame he must set
        a supplier with a recorder object inside of it. Every user of dispatches
        has to check then if such supplier is available at this frame property.
        If value of this property is <NULL/> he must call <member>XDispatch::dispatch()</member>
        on the original dispatch object. If it's a valid value he must use the supplier
        by calling his method <member>XDispatchRecorderSupplier::dispatchAndRecord()</member>
        with the original dispatch object as argument.
        </p>

        <p>
        Note:<br>
        It's not recommended to cache an already getted supplier. Because there exist
        no possibility to check for enabled/disabled recording then.
        </p>

	@since OpenOffice 1.1.2
     */
    [optional, property] XDispatchRecorderSupplier RecorderSupplier;

    //-------------------------------------------------------------------------
    /** provides access to the <type>LayoutManager</type> of the frame.
    */
    [optional, property] com::sun::star::uno::XInterface LayoutManager;
};

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

}; }; }; };

#endif