/**************************************************************
 * 
 * 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_drawing_XPresenterHelper_idl__
#define __com_sun_star_drawing_XPresenterHelper_idl__

#ifndef __com_sun_star_awt_XWindow_idl__
#include <com/sun/star/awt/XWindow.idl>
#endif
#ifndef __com_sun_star_rendering_XCanvas_idl__
#include <com/sun/star/rendering/XCanvas.idl>
#endif
#ifndef __com_sun_star_rendering_XSpriteCanvas_idl__
#include <com/sun/star/rendering/XSpriteCanvas.idl>
#endif
#ifndef __com_sun_star_awt_Rectangle_idl__
#include <com/sun/star/awt/Rectangle.idl>
#endif
#ifndef __com_sun_star_drawing_CanvasFeature_idl__
#include <com/sun/star/drawing/CanvasFeature.idl>
#endif

module com { module sun { module star { module drawing {

/** This interface is a collection of functions that are necessary to
    implement larger parts of the presenter screen as extension.  The
    methods of this interface give access to services that can, at the
    moment, only implemented in the Office core, not in an extension.

    <p>With time some, maybe all, methods can moved to other, better suited,
    interfaces.</p>
*/
interface XPresenterHelper
{
    /** Create a new window as child window of the given parent window.
        @param xParentWindow
            The parent window of the new window.
        @param bCreateSystemChildWindow
            When <TRUE/> then the new window will be a system window that,
            in the context of the presenter screen, can not be painted over
            by other windows that lie behind it.
        @param bInitiallyVisible
            When <TRUE/> the new window will be visible from the start,
            i.e. a window listener will not receive a windowShown signal.
        @param bEnableChildTransparentMode
            When <TRUE/> the parent window is painted behind its child
            windows. This is one half of allowing child windows to be
            transparent.
        @param bEnableParentClip
            When <TRUE/> then the parent window is not clipped where its
            child windows are painted.  This is the other half of allowing
            child windows to be transparent.
    */
    ::com::sun::star::awt::XWindow createWindow (
        [in] ::com::sun::star::awt::XWindow xParentWindow,
        [in] boolean bCreateSystemChildWindow,
        [in] boolean bInitiallyVisible,
        [in] boolean bEnableChildTransparentMode,
        [in] boolean bEnableParentClip);

    /** Create a new canvas for the given window.  The new canvas is a
        wrapper around the given shared canvas.  The wrapper only modifies
        the origin in all output and clipping methods.
        @param xUpdateCanvas
            This canvas is used to call updateScreen() on.  May be <NULL/>
        @param xUpdateWindow
            The window that belongs to the update canvas.  May also be
            <NULL/> (is expected to b <NULL/> whenever xUpdateCanvas is.)
        @param xSharedCanvas
            The canvas that is shared by the wrapper.
        @param xSharedWindow
            The window of the shared canvas.  This is used to determine the
            proper offset.
        @param xWindow
            The canvas is created for this window.  Must not be <NULL/>
    */
    ::com::sun::star::rendering::XCanvas createSharedCanvas (
        [in] ::com::sun::star::rendering::XSpriteCanvas xUpdateCanvas,
        [in] ::com::sun::star::awt::XWindow xUpdateWindow,
        [in] ::com::sun::star::rendering::XCanvas xSharedCanvas,
        [in] ::com::sun::star::awt::XWindow xSharedWindow,
        [in] ::com::sun::star::awt::XWindow xWindow);

    /** Create a new canvas for the given window.
        @param xWindow
            The canvas is created for this window.  Must not be <NULL/>
        @param nRequestedCanvasFeatureList
            List of requested features that the new canvas should (has to)
            provide.  Use only values from the <type>CanvasFeature</type>
            constants group.
        @param sOptionalCanvasServiceName
            When an explicit service name is given then a new object of this
            service is created.  This service name lets the caller select a
            specific canvas implementation, e.g. with or without hardware
            acceleration. 
    */
    ::com::sun::star::rendering::XCanvas createCanvas (
        [in] ::com::sun::star::awt::XWindow xWindow,
        [in] short nRequestedCanvasFeatureList,
        [in] string sOptionalCanvasServiceName);

    /** Move the specified window to the top of its stacking order.  As a
        result the window will be painted over all its overlapping
        siblings.
        @param xWindow
            This window will be moved to the top of its stacking order.
    */
    void toTop (
        [in] ::com::sun::star::awt::XWindow xWindow);

    /** Load a bitmap from a file or other accessible resource that can be
        located via a URL.
        @param sURL
            The URL of the bitmap.  For a file URL the bitmap is loaded from
            the specified file.
        @param xCanvas
            The bitmap is created to be compatible, and possibly optimized,
            for this canvas.
    */
    ::com::sun::star::rendering::XBitmap loadBitmap (
        [in] string sURL,
        [in] ::com::sun::star::rendering::XCanvas xCanvas);

    /** Capture the mouse so that no other window will receive mouse events.
        Note that this is a potentially dangerous method.  Not calling
        releaseMouse eventually can lead to an unresponsive application.
        @param xWindow
            The window for which mouse events will be notified even when the
            mouse pointer moves outside the window or over other windows.
    */
    void captureMouse (
        [in] ::com::sun::star::awt::XWindow xWindow);

    /** Release a previously captured mouse.
        @param xWindow
            The window from which the mouse will be released.
    */
    void releaseMouse (
        [in] ::com::sun::star::awt::XWindow xWindow);

    /** Return the bounding box of the given child window relative to the
        direct or indirect parent window.
    */
    com::sun::star::awt::Rectangle getWindowExtentsRelative (
        [in] ::com::sun::star::awt::XWindow xChildWindow,
        [in] ::com::sun::star::awt::XWindow xParentWindow);
};


}; }; }; }; // ::com::sun::star::drawing

#endif