offapi/com/sun/star/rendering/XAnimatedSprite.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: XAnimatedSprite.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_XAnimatedSprite_idl__
  31 #define __com_sun_star_rendering_XAnimatedSprite_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_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 #ifndef __com_sun_star_rendering_XSprite_idl__
  49 #include <com/sun/star/rendering/XSprite.idl>
  50 #endif
  51
  52
  53 module com { module sun { module star { module rendering {
  54
  55 /** This interface can be used to control an animated sprite object.<p>
  56
  57     This interface can be used to control an animated sprite object on
  58     an XSpriteCanvas. Sprites are moving, animated objects.<p>
  59
  60     @since OOo 2.0.0
  61  */
  62 interface XAnimatedSprite : XSprite
  63 {
  64     /** Start animation sequence of this sprite.<p>
  65
  66         The speed of the animation is given in cycles per second
  67         (where a cycle is defined as one full animation run, i.e. the
  68         full [0,1] range of the <member>XAnimation::render</member>'s
  69         t parameter, or a full sequence of sprite bitmaps drawn). Once
  70         an animation is running, the associated
  71         <type>XSpriteCanvas</type> handles screen updates
  72         automatically. That means, changes to position or alpha are
  73         reflected on screen automatically. Please note further that
  74         sprite visibility and animation are unrelated, i.e. a hidden
  75         sprite can have a running animation, which then displays in
  76         the middle of the animation sequence, when a show() is called
  77         later on.<p>
  78
  79         @param nSpeed
  80         The speed of the animation in cycles per second (where a cycle
  81         is defined as one full animation run, i.e. the full [0,1]
  82         range of the <member>XAnimation::render</member>'s t
  83         parameter, or a full sequence of sprite bitmaps drawn).
  84      */
  85     void startAnimation( [in] double nSpeed );
  86
  87     //-------------------------------------------------------------------------
  88
  89     /** Stop the animation sequence.<p>
  90
  91         A subsequent <member>XAnimatedSprite::startAnimation</member>
  92         will commence the sequence at the point where it was stopped
  93         with here. Once an animation is stopped, the associated
  94         <type>XSpriteCanvas</type> does not update changed sprites
  95         anymore.<p>
  96     */
  97     void stopAnimation();
  98
  99     //-------------------------------------------------------------------------
 100
 101     /** Reset the animation sequence to start with the first frame.<p>
 102
 103         If the animation is currently running, the next frame that is
 104         drawn after this method has finished, will be the first
 105         one. Please note that if an animation is not started, the
 106         associated <type>XSpriteCanvas</type> does not update changed
 107         sprites automatically.<p>
 108      */
 109     void resetAnimation();
 110
 111     //-------------------------------------------------------------------------
 112
 113     /** Issue an additional render call to this sprite's
 114         animation.<p>
 115
 116         This method has no effect when called for a bitmap-sequence
 117         sprite. Please note that if an animation is not started, the
 118         associated <type>XSpriteCanvas</type> does not update changed
 119         sprites automatically, but has to be told to do so via
 120         <member>XSpriteCanvas::updateScreen()</member>.<p>
 121      */
 122     void updateAnimation();
 123
 124     //-------------------------------------------------------------------------
 125
 126     /** Changes the view state in place for this sprite's
 127         animation.<p>
 128
 129         The state given here is used when calling the
 130         <member>XAnimation::render()</member> method, or when drawing
 131         the sprite's bitmaps, respectively. There's no need to call
 132         <member>XSpriteCanvas::updateAnimation()</member> after this
 133         method, as it automatically rerenders, if necessary. Please
 134         note that if an animation is not started, the associated
 135         <type>XSpriteCanvas</type> does not update changed sprites
 136         automatically, but has to be told to do so via
 137         <member>XSpriteCanvas::updateScreen()</member>.<p>
 138
 139         @param aViewState
 140         The state given here is used when calling the
 141         <member>XAnimation::render()</member> method, or when drawing
 142         the sprite's bitmaps, respectively.
 143
 144         @throws <type>com::sun::star::lang::IllegalArgumentException</type>
 145         if the view transformation matrix is singular.
 146     */
 147     void setViewState( [in] ViewState aViewState )
 148         raises (com::sun::star::lang::IllegalArgumentException);
 149
 150     //-------------------------------------------------------------------------
 151
 152     /** Changes all of the sprite's attributes at one atomic
 153         instance.<p>
 154
 155         This is useful at times where one does not want multiple
 156         redraws for every state change.<p>
 157
 158         Please note that if an animation is not started, 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         @param aNewPos
 164         New left,top output position of the sprite. This position gets
 165         transformed by the view and render state.
 166
 167         @param aViewState
 168         New view state of the sprite, and part of the transformation
 169         that is applied to aNewPos. The view transformation matrix
 170         must not be singular.
 171
 172         @param aRenderState
 173         New render state of the sprite, and part of the transformation
 174         that is applied to aNewPos. The render transformation matrix
 175         must not be singular.
 176
 177         @param nAlpha
 178         New alpha value of the sprite. This value must be within the
 179         [0,1] range.
 180
 181         @param bUpdateAnimation
 182         Whether this method should implicitely call
 183         <member>XSpriteCanvas::updateAnimation</member> or not.
 184
 185         @throws <type>com::sun::star::lang::IllegalArgumentException</type>
 186         if one of the passed parameters does not lie in the specified,
 187         permissible range.
 188      */
 189     void setAll( [in] ::com::sun::star::geometry::RealPoint2D   aNewPos,
 190                  [in] ViewState                                                                                 aViewState,
 191                  [in] RenderState                                                                               aRenderState,
 192                  [in] double                                                                                    nAlpha,
 193                  [in] boolean                                                                                   bUpdateAnimation )
 194         raises (com::sun::star::lang::IllegalArgumentException);
 195 };
 196
 197 }; }; }; };
 198
 199 #endif