xref: /aoo42x/main/offapi/com/sun/star/rendering/XSpriteCanvas.idl (revision d1766043)

/**************************************************************
 *
 * 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_rendering_XSpriteCanvas_idl__
#define __com_sun_star_rendering_XSpriteCanvas_idl__

#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
#include <com/sun/star/lang/IllegalArgumentException.idl>
#endif
#ifndef __com_sun_star_rendering_XBitmapCanvas_idl__
#include <com/sun/star/rendering/XBitmapCanvas.idl>
#endif
#ifndef __com_sun_star_rendering_XAnimation_idl__
#include <com/sun/star/rendering/XAnimation.idl>
#endif
#ifndef __com_sun_star_rendering_VolatileContentDestroyedException_idl__
#include <com/sun/star/rendering/VolatileContentDestroyedException.idl>
#endif

module com { module sun { module star { module rendering {

published interface XSprite;
published interface XAnimatedSprite;
published interface XCustomSprite;

/** Specialization of a XBitmapCanvas, where moving, animated objects
    (called sprites) are supported.<p>

    @attention The screen output of canvas drawing operations is
    undefined, unless XSpriteCanvas::updateScreen() is called. This is
    because a sprite canvas might choose to employ double buffering to
    reduce animation flicker, and cannot know the instant suitable to
    display the newly rendered canvas content. When using external
    double-buffering via XBufferController on a sprite canvas, the
    implementation takes care of this issue, and in this case is able
    to render correctly even without explicit updateScreen() calls
    (because there's a defined moment in time where content display
    can happen, namely the XBufferController::showBuffer()) call. If
    you don't need sprite functionality, and don't want the
    updateScreen hassle, simply use the XBitmapCanvas.
 */
published interface XSpriteCanvas : XBitmapCanvas
{
    /** Create a sprite object from the specified animation
        sequence. A sprite is a back-buffered object with its own,
        independent animation.
     */
    XAnimatedSprite	createSpriteFromAnimation( [in] XAnimation animation )
        raises (com::sun::star::lang::IllegalArgumentException);

    /** Create a sprite object from the specified animation
        sequence.

        A sprite is a back-buffered object with its own,
        independent animation.

        @param animationBitmaps
        Sequence of bitmaps. The bitmaps don't need to have the same
        size, but they are all rendered with their left, top edges
        aligned.

        @param interpolationMode
        Value of <type>InterpolationMode</type>, to determine whether
        and how to interpolate between the provided bitmaps, if
        animation runs fast enough.

        @throws <type>VolatileContentDestroyedException</type>
        if at least one of the bitmap is volatile, and its content has been destroyed by the system.
     */
    XAnimatedSprite	createSpriteFromBitmaps( [in] sequence<XBitmap> animationBitmaps, [in] byte interpolationMode )
        raises (com::sun::star::lang::IllegalArgumentException,
                VolatileContentDestroyedException);

    /** Create a custom, user-handles-it-all sprite object.

        A sprite is a back-buffered object with its own, independent
        animation.

        @param spriteSize
        The required size of the sprite in device
        coordinates. Everything that is rendered outside this area
        might be clipped on output. Both components of the size must
        be greater than zero.

        @return an interface to a custom sprite object.
     */
    XCustomSprite createCustomSprite( [in] ::com::sun::star::geometry::RealSize2D spriteSize )
        raises (com::sun::star::lang::IllegalArgumentException);

    /** Create a cloned version of an already existing sprite
        object.

        The cloned sprite always shows the same content as its
        original. Furthermore, cloned copies of a hidden original are
        never visible, although cloned copies of a visible original
        can of course be invisible.

        @param original
        The original sprite to copy the content from. This sprite must
        have been created by the same XSpriteCanvas instance as this
        method is called on. Other sprite instances will generate an
        IllegalArgumentException.

        @return an interface to a sprite object.
     */
    XSprite createClonedSprite( [in] XSprite original )
        raises (com::sun::star::lang::IllegalArgumentException);

    /** Tells the sprite canvas to now update the screen
        representation.

        Required to display rendered changes to the canvas, and
        updates to stopped animations and XCustomSprites in
        general. This method will return only after the screen update
        is done, or earlier if an error happened.<p>

        If double buffering is enabled via XBufferController, no
        explicit call of updateScreen() is necessary, since the
        XBufferController methods will automatically notify all
        associated XSpriteCanvas instances.<p>

        @param bUpdateAll
        When <TRUE/>, update the whole screen. When <FALSE/>,
        implementation is permitted to restrict update to areas the
        canvas itself changed (e.g. because of render operations, or
        changes on the sprites). The former is useful for updates
        after window expose events. the latter for animation display.

        @return <TRUE/>, if the screen update was successfully
        performed
     */
    boolean updateScreen( [in] boolean bUpdateAll );
};

}; }; }; };

#endif