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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #ifndef __com_sun_star_rendering_XAnimatedSprite_idl__
  20 #define __com_sun_star_rendering_XAnimatedSprite_idl__
  21
  22 #include <com/sun/star/uno/XInterface.idl>
  23 #include <com/sun/star/lang/IllegalArgumentException.idl>
  24 #include <com/sun/star/geometry/RealPoint2D.idl>
  25 #include <com/sun/star/rendering/ViewState.idl>
  26 #include <com/sun/star/rendering/RenderState.idl>
  27 #include <com/sun/star/rendering/XSprite.idl>
  28
  29
  30 module com { module sun { module star { module rendering {
  31
  32 /** This interface can be used to control an animated sprite object.<p>
  33
  34     This interface can be used to control an animated sprite object on
  35     an XSpriteCanvas. Sprites are moving, animated objects.<p>
  36
  37     @since OOo 2.0
  38  */
  39 interface XAnimatedSprite : XSprite
  40 {
  41     /** Start animation sequence of this sprite.<p>
  42
  43         The speed of the animation is given in cycles per second
  44         (where a cycle is defined as one full animation run, i.e. the
  45         full [0,1] range of the XAnimation::render()'s
  46         t parameter, or a full sequence of sprite bitmaps drawn). Once
  47         an animation is running, the associated
  48         XSpriteCanvas handles screen updates
  49         automatically. That means, changes to position or alpha are
  50         reflected on screen automatically. Please note further that
  51         sprite visibility and animation are unrelated, i.e. a hidden
  52         sprite can have a running animation, which then displays in
  53         the middle of the animation sequence, when a show() is called
  54         later on.<p>
  55
  56         @param nSpeed
  57         The speed of the animation in cycles per second (where a cycle
  58         is defined as one full animation run, i.e. the full [0,1]
  59         range of the XAnimation::render()'s t
  60         parameter, or a full sequence of sprite bitmaps drawn).
  61      */
  62     void startAnimation( [in] double nSpeed );
  63
  64
  65     /** Stop the animation sequence.<p>
  66
  67         A subsequent XAnimatedSprite::startAnimation()
  68         will commence the sequence at the point where it was stopped
  69         with here. Once an animation is stopped, the associated
  70         XSpriteCanvas does not update changed sprites
  71         anymore.<p>
  72     */
  73     void stopAnimation();
  74
  75
  76     /** Reset the animation sequence to start with the first frame.<p>
  77
  78         If the animation is currently running, the next frame that is
  79         drawn after this method has finished, will be the first
  80         one. Please note that if an animation is not started, the
  81         associated XSpriteCanvas does not update changed
  82         sprites automatically.<p>
  83      */
  84     void resetAnimation();
  85
  86
  87     /** Issue an additional render call to this sprite's
  88         animation.<p>
  89
  90         This method has no effect when called for a bitmap-sequence
  91         sprite. Please note that if an animation is not started, the
  92         associated XSpriteCanvas does not update changed
  93         sprites automatically, but has to be told to do so via
  94         XSpriteCanvas::updateScreen().<p>
  95      */
  96     void updateAnimation();
  97
  98
  99     /** Changes the view state in place for this sprite's
 100         animation.<p>
 101
 102         The state given here is used when calling the
 103         XAnimation::render() method, or when drawing
 104         the sprite's bitmaps, respectively. There's no need to call
 105         XSpriteCanvas::updateAnimation() after this
 106         method, as it automatically rerenders, if necessary. Please
 107         note that if an animation is not started, the associated
 108         XSpriteCanvas does not update changed sprites
 109         automatically, but has to be told to do so via
 110         XSpriteCanvas::updateScreen().<p>
 111
 112         @param aViewState
 113         The state given here is used when calling the
 114         XAnimation::render() method, or when drawing
 115         the sprite's bitmaps, respectively.
 116
 117         @throws com::sun::star::lang::IllegalArgumentException
 118         if the view transformation matrix is singular.
 119     */
 120     void setViewState( [in] ViewState aViewState )
 121         raises (com::sun::star::lang::IllegalArgumentException);
 122
 123
 124     /** Changes all of the sprite's attributes at one atomic
 125         instance.<p>
 126
 127         This is useful at times where one does not want multiple
 128         redraws for every state change.<p>
 129
 130         Please note that if an animation is not started, the
 131         associated XSpriteCanvas does not update changed
 132         sprites automatically, but has to be told to do so via
 133         XSpriteCanvas::updateScreen().<p>
 134
 135         @param aNewPos
 136         New left,top output position of the sprite. This position gets
 137         transformed by the view and render state.
 138
 139         @param aViewState
 140         New view state of the sprite, and part of the transformation
 141         that is applied to aNewPos. The view transformation matrix
 142         must not be singular.
 143
 144         @param aRenderState
 145         New render state of the sprite, and part of the transformation
 146         that is applied to aNewPos. The render transformation matrix
 147         must not be singular.
 148
 149         @param nAlpha
 150         New alpha value of the sprite. This value must be within the
 151         [0,1] range.
 152
 153         @param bUpdateAnimation
 154         Whether this method should implicitly call
 155         XSpriteCanvas::updateAnimation() or not.
 156
 157         @throws com::sun::star::lang::IllegalArgumentException
 158         if one of the passed parameters does not lie in the specified,
 159         permissible range.
 160      */
 161     void setAll( [in] ::com::sun::star::geometry::RealPoint2D   aNewPos,
 162                  [in] ViewState                                         aViewState,
 163                  [in] RenderState                                       aRenderState,
 164                  [in] double                                            nAlpha,
 165                  [in] boolean                                           bUpdateAnimation )
 166         raises (com::sun::star::lang::IllegalArgumentException);
 167 };
 168
 169 }; }; }; };
 170
 171 #endif
 172
 173 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */