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_XSprite_idl__
24#define __com_sun_star_rendering_XSprite_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_geometry_AffineMatrix2D_idl__
36#include <com/sun/star/geometry/AffineMatrix2D.idl>
37#endif
38#ifndef __com_sun_star_rendering_ViewState_idl__
39#include <com/sun/star/rendering/ViewState.idl>
40#endif
41#ifndef __com_sun_star_rendering_RenderState_idl__
42#include <com/sun/star/rendering/RenderState.idl>
43#endif
44
45module com { module sun { module star { module rendering {
46
47/** Interface to control a sprite object.<p>
48
49    This is the basic interface to control a sprite object on a
50    <type>XSpriteCanvas</type>. Sprites are moving, back-buffered
51    objects.<p>
52 */
53published interface XSprite : ::com::sun::star::uno::XInterface
54{
55    /** Set overall transparency of the sprite.<p>
56
57        This method is useful for e.g. fading in/out of animations.<p>
58
59        Please note that if this sprite is not animated, the
60        associated <type>XSpriteCanvas</type> does not update changed
61        sprites automatically, but has to be told to do so via
62        <member>XSpriteCanvas::updateScreen()</member>.<p>
63
64        @param nAlpha
65        New global alpha value to composite this sprite with the
66        background. Valid range is [0,1].
67
68        @throws <type>com::sun::star::lang::IllegalArgumentException</type>
69        if nAlpha is not within the permissible range.
70     */
71    void setAlpha( [in] double nAlpha )
72        raises (com::sun::star::lang::IllegalArgumentException);
73
74    //-------------------------------------------------------------------------
75
76    /** Move sprite to the specified position.<p>
77
78        The position specified here is first transformed by the
79        combined view and render transformation. The resulting
80        position is then used as the output position (also in device
81        coordinates) of the rendered sprite content.<p>
82
83        Please note that if this sprite is not animated, the
84        associated <type>XSpriteCanva</type> does not update changed sprites
85        automatically, but has to be told to do so via
86        <member>XSpriteCanvas::updateScreen()</member>.<p>
87
88        @param aNewPos
89        The new position, in user coordinate space, to move the sprite to.
90
91        @param aViewState
92        The viewstate to be used when interpreting aNewPos.
93
94        @param aRenderState
95        The renderstate to be used when interpreting aNewPos.
96
97        @throws <type>com::sun::star::lang::IllegalArgumentException</type>
98        if one of the view and renderstate parameters are outside the
99        specified range.
100     */
101    void move( [in] ::com::sun::star::geometry::RealPoint2D aNewPos, [in] ViewState aViewState, [in] RenderState aRenderState )
102        raises (com::sun::star::lang::IllegalArgumentException);
103
104    //-------------------------------------------------------------------------
105
106    /** Apply a local transformation to the sprite.<p>
107
108        The given transformation matrix locally transforms the sprite
109        shape. If this transformation contains translational
110        components, be aware that sprite content moved beyond the
111        sprite area (a box from (0,0) to (spriteWidth,spriteHeight))
112        might (but need not) be clipped. Use
113        <member>XSprite::move</member> to change the sprite location
114        on screen. The canvas implementations are free, if they have a
115        cached representation of the sprite at hand, to transform only
116        this cached representation (e.g. a bitmap), instead of
117        re-rendering the sprite from first principles. This is usually
118        the case for an implementation of a <type>XCustomSprite</type>
119        interface, since it typically has no other cached pictorial
120        information at hand.<p>
121
122        Please note that if this sprite is not animated, the
123        associated <type>XSpriteCanvas</type> does not update changed
124        sprites automatically, but has to be told to do so via
125        <member>XSpriteCanvas::updateScreen()</member>.<p>
126
127        @param aTransformation
128        The transformation to apply to the sprite shape.
129
130        @throws <type>com::sun::star::lang::IllegalArgumentException</type>
131        if the given transformation matrix is singular.
132     */
133    void transform( [in] com::sun::star::geometry::AffineMatrix2D aTransformation )
134        raises (com::sun::star::lang::IllegalArgumentException);
135
136    //-------------------------------------------------------------------------
137
138    /** Apply a clipping to the shape output.<p>
139
140        The given clip poly-polygon is always interpreted in device
141        coordinate space. As the sprite has its own local coordinate
142        system, with its origin on screen being equal to its current
143        position, the clip poly-polygon's origin will always coincide
144        with the sprite's origin. Furthermore, if any sprite
145        transformation is set via transform(), the clip is subject to
146        this transformation, too. The implementation is free, if it
147        has a cached representation of the sprite at hand, to
148        clip-output only this cached representation (e.g. a bitmap),
149        instead of re-rendering the sprite from first principles. This
150        is usually the case for an implementation of a
151        <type>XCustomSprite</type> interface, since it typically has
152        no other cached pictorial information at hand.<p>
153
154        Please note that if this sprite is not animated, the
155        associated <type>XSpriteCanvas</type> does not update changed
156        sprites automatically, but has to be told to do so via
157        <member>XSpriteCanvas::updateScreen()</member>.<p>
158
159        Specifying an empty interface denotes no clipping,
160        i.e. everything contained in the sprite will be visible
161        (subject to device-dependent constraints, of
162        course). Specifying an empty XPolyPolygon2D, i.e. a
163        poly-polygon containing zero polygons, or an XPolyPolygon2D
164        with any number of empty sub-polygons, denotes the NULL
165        clip. That means, nothing from the sprite will be visible.<p>
166
167        @param aClip
168        The clip poly-polygon to apply.
169     */
170    void clip( [in] XPolyPolygon2D aClip );
171
172    //-------------------------------------------------------------------------
173
174    /** Set sprite priority.<p>
175
176        The sprite priority determines the order of rendering relative
177        to all other sprites of the associated canvas. The higher the
178        priority, the later will the sprite be rendered, or, in other
179        words, the closer to the screen surface the sprite is shown.<p>
180
181        @param nPriority
182        New sprite priority value to serve as the sort key when
183        determining sprite rendering order. Avoid NaNs and other
184        irregular floating point values here, the order position for
185        sprites with such a priority value is undefined.
186     */
187    void setPriority( [in] double nPriority );
188
189    //-------------------------------------------------------------------------
190
191    /** Make the sprite visible.<p>
192
193        This method makes the sprite visible on the canvas it was
194        created on.<p>
195     */
196    void show();
197
198    //-------------------------------------------------------------------------
199
200    /** Make the sprite invisible.<p>
201
202        This method makes the sprite invisible.<p>
203     */
204    void hide();
205
206};
207
208}; }; }; };
209
210#endif
211