offapi/com/sun/star/rendering/XSprite.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: XSprite.idl,v $
  10  * $Revision: 1.7 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef __com_sun_star_rendering_XSprite_idl__
  31 #define __com_sun_star_rendering_XSprite_idl__
  32
  33 #ifndef __com_sun_star_uno_XInterface_idl__
  34 #include <com/sun/star/uno/XInterface.idl>
  35 #endif
  36 #ifndef __com_sun_star_lang_IllegalArgumentException_idl__
  37 #include <com/sun/star/lang/IllegalArgumentException.idl>
  38 #endif
  39 #ifndef __com_sun_star_geometry_RealPoint2D_idl__
  40 #include <com/sun/star/geometry/RealPoint2D.idl>
  41 #endif
  42 #ifndef __com_sun_star_geometry_AffineMatrix2D_idl__
  43 #include <com/sun/star/geometry/AffineMatrix2D.idl>
  44 #endif
  45 #ifndef __com_sun_star_rendering_ViewState_idl__
  46 #include <com/sun/star/rendering/ViewState.idl>
  47 #endif
  48 #ifndef __com_sun_star_rendering_RenderState_idl__
  49 #include <com/sun/star/rendering/RenderState.idl>
  50 #endif
  51
  52 module com { module sun { module star { module rendering {
  53
  54 /** Interface to control a sprite object.<p>
  55
  56     This is the basic interface to control a sprite object on a
  57     <type>XSpriteCanvas</type>. Sprites are moving, back-buffered
  58     objects.<p>
  59  */
  60 interface XSprite : ::com::sun::star::uno::XInterface
  61 {
  62     /** Set overall transparency of the sprite.<p>
  63
  64         This method is useful for e.g. fading in/out of animations.<p>
  65
  66         Please note that if this sprite is not animated, the
  67         associated <type>XSpriteCanvas</type> does not update changed
  68         sprites automatically, but has to be told to do so via
  69         <member>XSpriteCanvas::updateScreen()</member>.<p>
  70
  71         @param nAlpha
  72         New global alpha value to composite this sprite with the
  73         background. Valid range is [0,1].
  74
  75         @throws <type>com::sun::star::lang::IllegalArgumentException</type>
  76         if nAlpha is not within the permissible range.
  77      */
  78     void setAlpha( [in] double nAlpha )
  79         raises (com::sun::star::lang::IllegalArgumentException);
  80
  81     //-------------------------------------------------------------------------
  82
  83     /** Move sprite to the specified position.<p>
  84
  85         The position specified here is first transformed by the
  86         combined view and render transformation. The resulting
  87         position is then used as the output position (also in device
  88         coordinates) of the rendered sprite content.<p>
  89
  90         Please note that if this sprite is not animated, the
  91         associated <type>XSpriteCanva</type> does not update changed sprites
  92         automatically, but has to be told to do so via
  93         <member>XSpriteCanvas::updateScreen()</member>.<p>
  94
  95         @param aNewPos
  96         The new position, in user coordinate space, to move the sprite to.
  97
  98         @param aViewState
  99         The viewstate to be used when interpreting aNewPos.
 100
 101         @param aRenderState
 102         The renderstate to be used when interpreting aNewPos.
 103
 104         @throws <type>com::sun::star::lang::IllegalArgumentException</type>
 105         if one of the view and renderstate parameters are outside the
 106         specified range.
 107      */
 108     void move( [in] ::com::sun::star::geometry::RealPoint2D aNewPos, [in] ViewState aViewState, [in] RenderState aRenderState )
 109         raises (com::sun::star::lang::IllegalArgumentException);
 110
 111     //-------------------------------------------------------------------------
 112
 113     /** Apply a local transformation to the sprite.<p>
 114
 115         The given transformation matrix locally transforms the sprite
 116         shape. If this transformation contains translational
 117         components, be aware that sprite content moved beyond the
 118         sprite area (a box from (0,0) to (spriteWidth,spriteHeight))
 119         might (but need not) be clipped. Use
 120         <member>XSprite::move</member> to change the sprite location
 121         on screen. The canvas implementations are free, if they have a
 122         cached representation of the sprite at hand, to transform only
 123         this cached representation (e.g. a bitmap), instead of
 124         re-rendering the sprite from first principles. This is usually
 125         the case for an implementation of a <type>XCustomSprite</type>
 126         interface, since it typically has no other cached pictorial
 127         information at hand.<p>
 128
 129         Please note that if this sprite is not animated, the
 130         associated <type>XSpriteCanvas</type> does not update changed
 131         sprites automatically, but has to be told to do so via
 132         <member>XSpriteCanvas::updateScreen()</member>.<p>
 133
 134         @param aTransformation
 135         The transformation to apply to the sprite shape.
 136
 137         @throws <type>com::sun::star::lang::IllegalArgumentException</type>
 138         if the given transformation matrix is singular.
 139      */
 140     void transform( [in] com::sun::star::geometry::AffineMatrix2D aTransformation )
 141         raises (com::sun::star::lang::IllegalArgumentException);
 142
 143     //-------------------------------------------------------------------------
 144
 145     /** Apply a clipping to the shape output.<p>
 146
 147         The given clip poly-polygon is always interpreted in device
 148         coordinate space. As the sprite has its own local coordinate
 149         system, with its origin on screen being equal to its current
 150         position, the clip poly-polygon's origin will always coincide
 151         with the sprite's origin. Furthermore, if any sprite
 152         transformation is set via transform(), the clip is subject to
 153         this transformation, too. The implementation is free, if it
 154         has a cached representation of the sprite at hand, to
 155         clip-output only this cached representation (e.g. a bitmap),
 156         instead of re-rendering the sprite from first principles. This
 157         is usually the case for an implementation of a
 158         <type>XCustomSprite</type> interface, since it typically has
 159         no other cached pictorial information at hand.<p>
 160
 161         Please note that if this sprite is not animated, the
 162         associated <type>XSpriteCanvas</type> does not update changed
 163         sprites automatically, but has to be told to do so via
 164         <member>XSpriteCanvas::updateScreen()</member>.<p>
 165
 166         Specifying an empty interface denotes no clipping,
 167         i.e. everything contained in the sprite will be visible
 168         (subject to device-dependent constraints, of
 169         course). Specifying an empty XPolyPolygon2D, i.e. a
 170         poly-polygon containing zero polygons, or an XPolyPolygon2D
 171         with any number of empty sub-polygons, denotes the NULL
 172         clip. That means, nothing from the sprite will be visible.<p>
 173
 174         @param aClip
 175         The clip poly-polygon to apply.
 176      */
 177     void clip( [in] XPolyPolygon2D aClip );
 178
 179     //-------------------------------------------------------------------------
 180
 181     /** Set sprite priority.<p>
 182
 183         The sprite priority determines the order of rendering relative
 184         to all other sprites of the associated canvas. The higher the
 185         priority, the later will the sprite be rendered, or, in other
 186         words, the closer to the screen surface the sprite is shown.<p>
 187
 188         @param nPriority
 189         New sprite priority value to serve as the sort key when
 190         determining sprite rendering order. Avoid NaNs and other
 191         irregular floating point values here, the order position for
 192         sprites with such a priority value is undefined.
 193      */
 194     void setPriority( [in] double nPriority );
 195
 196     //-------------------------------------------------------------------------
 197
 198     /** Make the sprite visible.<p>
 199
 200         This method makes the sprite visible on the canvas it was
 201         created on.<p>
 202      */
 203     void show();
 204
 205     //-------------------------------------------------------------------------
 206
 207     /** Make the sprite invisible.<p>
 208
 209         This method makes the sprite invisible.<p>
 210      */
 211     void hide();
 212
 213 };
 214
 215 }; }; }; };
 216
 217 #endif