1/*************************************************************************
2 *
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * Copyright 2000, 2010 Oracle and/or its affiliates.
6 *
7 * OpenOffice.org - a multi-platform office productivity suite
8 *
9 * This file is part of OpenOffice.org.
10 *
11 * OpenOffice.org is free software: you can redistribute it and/or modify
12 * it under the terms of the GNU Lesser General Public License version 3
13 * only, as published by the Free Software Foundation.
14 *
15 * OpenOffice.org is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18 * GNU Lesser General Public License version 3 for more details
19 * (a copy is included in the LICENSE file that accompanied this code).
20 *
21 * You should have received a copy of the GNU Lesser General Public License
22 * version 3 along with OpenOffice.org.  If not, see
23 * <http://www.openoffice.org/license.html>
24 * for a copy of the LGPLv3 License.
25 *
26 ************************************************************************/
27#ifndef __com_sun_star_rendering_XSpriteCanvas_idl__
28#define __com_sun_star_rendering_XSpriteCanvas_idl__
29
30#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
31#include <com/sun/star/lang/IllegalArgumentException.idl>
32#endif
33#ifndef __com_sun_star_rendering_XBitmapCanvas_idl__
34#include <com/sun/star/rendering/XBitmapCanvas.idl>
35#endif
36#ifndef __com_sun_star_rendering_XAnimation_idl__
37#include <com/sun/star/rendering/XAnimation.idl>
38#endif
39#ifndef __com_sun_star_rendering_VolatileContentDestroyedException_idl__
40#include <com/sun/star/rendering/VolatileContentDestroyedException.idl>
41#endif
42
43module com { module sun { module star { module rendering {
44
45published interface XSprite;
46published interface XAnimatedSprite;
47published interface XCustomSprite;
48
49/** Specialization of a XBitmapCanvas, where moving, animated objects
50    (called sprites) are supported.<p>
51
52    @attention The screen output of canvas drawing operations is
53    undefined, unless XSpriteCanvas::updateScreen() is called. This is
54    because a sprite canvas might choose to employ double buffering to
55    reduce animation flicker, and cannot know the instant suitable to
56    display the newly rendered canvas content. When using external
57    double-buffering via XBufferController on a sprite canvas, the
58    implementation takes care of this issue, and in this case is able
59    to render correctly even without explicit updateScreen() calls
60    (because there's a defined moment in time where content display
61    can happen, namely the XBufferController::showBuffer()) call. If
62    you don't need sprite functionality, and don't want the
63    updateScreen hassle, simply use the XBitmapCanvas.
64 */
65published interface XSpriteCanvas : XBitmapCanvas
66{
67    /** Create a sprite object from the specified animation
68        sequence. A sprite is a back-buffered object with its own,
69        independent animation.
70     */
71    XAnimatedSprite	createSpriteFromAnimation( [in] XAnimation animation )
72        raises (com::sun::star::lang::IllegalArgumentException);
73
74    /** Create a sprite object from the specified animation
75        sequence.
76
77        A sprite is a back-buffered object with its own,
78        independent animation.
79
80        @param animationBitmaps
81        Sequence of bitmaps. The bitmaps don't need to have the same
82        size, but they are all rendered with their left, top edges
83        aligned.
84
85        @param interpolationMode
86        Value of <type>InterpolationMode</type>, to determine whether
87        and how to interpolate between the provided bitmaps, if
88        animation runs fast enough.
89
90        @throws <type>VolatileContentDestroyedException</type>
91        if at least one of the bitmap is volatile, and its content has been destroyed by the system.
92     */
93    XAnimatedSprite	createSpriteFromBitmaps( [in] sequence<XBitmap> animationBitmaps, [in] byte interpolationMode )
94        raises (com::sun::star::lang::IllegalArgumentException,
95                VolatileContentDestroyedException);
96
97    /** Create a custom, user-handles-it-all sprite object.
98
99        A sprite is a back-buffered object with its own, independent
100        animation.
101
102        @param spriteSize
103        The required size of the sprite in device
104        coordinates. Everything that is rendered outside this area
105        might be clipped on output. Both components of the size must
106        be greater than zero.
107
108        @return an interface to a custom sprite object.
109     */
110    XCustomSprite createCustomSprite( [in] ::com::sun::star::geometry::RealSize2D spriteSize )
111        raises (com::sun::star::lang::IllegalArgumentException);
112
113    /** Create a cloned version of an already existing sprite
114        object.
115
116        The cloned sprite always shows the same content as its
117        original. Furthermore, cloned copies of a hidden original are
118        never visible, although cloned copies of a visible original
119        can of course be invisible.
120
121        @param original
122        The original sprite to copy the content from. This sprite must
123        have been created by the same XSpriteCanvas instance as this
124        method is called on. Other sprite instances will generate an
125        IllegalArgumentException.
126
127        @return an interface to a sprite object.
128     */
129    XSprite createClonedSprite( [in] XSprite original )
130        raises (com::sun::star::lang::IllegalArgumentException);
131
132    /** Tells the sprite canvas to now update the screen
133        representation.
134
135        Required to display rendered changes to the canvas, and
136        updates to stopped animations and XCustomSprites in
137        general. This method will return only after the screen update
138        is done, or earlier if an error happened.<p>
139
140        If double buffering is enabled via XBufferController, no
141        explicit call of updateScreen() is necessary, since the
142        XBufferController methods will automatically notify all
143        associated XSpriteCanvas instances.<p>
144
145        @param bUpdateAll
146        When <TRUE/>, update the whole screen. When <FALSE/>,
147        implementation is permitted to restrict update to areas the
148        canvas itself changed (e.g. because of render operations, or
149        changes on the sprites). The former is useful for updates
150        after window expose events. the latter for animation display.
151
152        @return <TRUE/>, if the screen update was successfully
153        performed
154     */
155    boolean updateScreen( [in] boolean bUpdateAll );
156};
157
158}; }; }; };
159
160#endif
161