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

   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
  49 module 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  */
  57 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