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