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