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