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_XAnimatedSprite_idl__
28#define __com_sun_star_rendering_XAnimatedSprite_idl__
29
30#ifndef __com_sun_star_uno_XInterface_idl__
31#include <com/sun/star/uno/XInterface.idl>
32#endif
33#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
34#include <com/sun/star/lang/IllegalArgumentException.idl>
35#endif
36#ifndef __com_sun_star_geometry_RealPoint2D_idl__
37#include <com/sun/star/geometry/RealPoint2D.idl>
38#endif
39#ifndef __com_sun_star_rendering_ViewState_idl__
40#include <com/sun/star/rendering/ViewState.idl>
41#endif
42#ifndef __com_sun_star_rendering_RenderState_idl__
43#include <com/sun/star/rendering/RenderState.idl>
44#endif
45#ifndef __com_sun_star_rendering_XSprite_idl__
46#include <com/sun/star/rendering/XSprite.idl>
47#endif
48
49
50module com { module sun { module star { module rendering {
51
52/** This interface can be used to control an animated sprite object.<p>
53
54    This interface can be used to control an animated sprite object on
55    an XSpriteCanvas. Sprites are moving, animated objects.<p>
56
57    @since OOo 2.0
58 */
59published interface XAnimatedSprite : XSprite
60{
61    /**	Start animation sequence of this sprite.<p>
62
63        The speed of the animation is given in cycles per second
64        (where a cycle is defined as one full animation run, i.e. the
65        full [0,1] range of the <member>XAnimation::render</member>'s
66        t parameter, or a full sequence of sprite bitmaps drawn). Once
67        an animation is running, the associated
68        <type>XSpriteCanvas</type> handles screen updates
69        automatically. That means, changes to position or alpha are
70        reflected on screen automatically. Please note further that
71        sprite visibility and animation are unrelated, i.e. a hidden
72        sprite can have a running animation, which then displays in
73        the middle of the animation sequence, when a show() is called
74        later on.<p>
75
76        @param nSpeed
77        The speed of the animation in cycles per second (where a cycle
78        is defined as one full animation run, i.e. the full [0,1]
79        range of the <member>XAnimation::render</member>'s t
80        parameter, or a full sequence of sprite bitmaps drawn).
81     */
82    void startAnimation( [in] double nSpeed );
83
84    //-------------------------------------------------------------------------
85
86    /** Stop the animation sequence.<p>
87
88        A subsequent <member>XAnimatedSprite::startAnimation</member>
89        will commence the sequence at the point where it was stopped
90        with here. Once an animation is stopped, the associated
91        <type>XSpriteCanvas</type> does not update changed sprites
92        anymore.<p>
93    */
94    void stopAnimation();
95
96    //-------------------------------------------------------------------------
97
98    /** Reset the animation sequence to start with the first frame.<p>
99
100        If the animation is currently running, the next frame that is
101        drawn after this method has finished, will be the first
102        one. Please note that if an animation is not started, the
103        associated <type>XSpriteCanvas</type> does not update changed
104        sprites automatically.<p>
105     */
106    void resetAnimation();
107
108    //-------------------------------------------------------------------------
109
110    /** Issue an additional render call to this sprite's
111        animation.<p>
112
113        This method has no effect when called for a bitmap-sequence
114        sprite. Please note that if an animation is not started, the
115        associated <type>XSpriteCanvas</type> does not update changed
116        sprites automatically, but has to be told to do so via
117        <member>XSpriteCanvas::updateScreen()</member>.<p>
118     */
119    void updateAnimation();
120
121    //-------------------------------------------------------------------------
122
123    /** Changes the view state in place for this sprite's
124        animation.<p>
125
126        The state given here is used when calling the
127        <member>XAnimation::render()</member> method, or when drawing
128        the sprite's bitmaps, respectively. There's no need to call
129        <member>XSpriteCanvas::updateAnimation()</member> after this
130        method, as it automatically rerenders, if necessary. Please
131        note that if an animation is not started, the associated
132        <type>XSpriteCanvas</type> does not update changed sprites
133        automatically, but has to be told to do so via
134        <member>XSpriteCanvas::updateScreen()</member>.<p>
135
136        @param aViewState
137        The state given here is used when calling the
138        <member>XAnimation::render()</member> method, or when drawing
139        the sprite's bitmaps, respectively.
140
141        @throws <type>com::sun::star::lang::IllegalArgumentException</type>
142        if the view transformation matrix is singular.
143    */
144    void setViewState( [in] ViewState aViewState )
145        raises (com::sun::star::lang::IllegalArgumentException);
146
147    //-------------------------------------------------------------------------
148
149    /** Changes all of the sprite's attributes at one atomic
150        instance.<p>
151
152        This is useful at times where one does not want multiple
153        redraws for every state change.<p>
154
155        Please note that if an animation is not started, the
156        associated <type>XSpriteCanvas</type> does not update changed
157        sprites automatically, but has to be told to do so via
158        <member>XSpriteCanvas::updateScreen()</member>.<p>
159
160        @param aNewPos
161        New left,top output position of the sprite. This position gets
162        transformed by the view and render state.
163
164        @param aViewState
165        New view state of the sprite, and part of the transformation
166        that is applied to aNewPos. The view transformation matrix
167        must not be singular.
168
169        @param aRenderState
170        New render state of the sprite, and part of the transformation
171        that is applied to aNewPos. The render transformation matrix
172        must not be singular.
173
174        @param nAlpha
175        New alpha value of the sprite. This value must be within the
176        [0,1] range.
177
178        @param bUpdateAnimation
179        Whether this method should implicitely call
180        <member>XSpriteCanvas::updateAnimation</member> or not.
181
182        @throws <type>com::sun::star::lang::IllegalArgumentException</type>
183        if one of the passed parameters does not lie in the specified,
184        permissible range.
185     */
186    void setAll( [in] ::com::sun::star::geometry::RealPoint2D	aNewPos,
187                 [in] ViewState                                         aViewState,
188                 [in] RenderState                                       aRenderState,
189                 [in] double                                            nAlpha,
190                 [in] boolean											bUpdateAnimation )
191        raises (com::sun::star::lang::IllegalArgumentException);
192};
193
194}; }; }; };
195
196#endif
197