offapi/com/sun/star/rendering/XSpriteCanvas.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: XSpriteCanvas.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_XSpriteCanvas_idl__
  31 #define __com_sun_star_rendering_XSpriteCanvas_idl__
  32
  33 #ifndef __com_sun_star_lang_IllegalArgumentException_idl__
  34 #include <com/sun/star/lang/IllegalArgumentException.idl>
  35 #endif
  36 #ifndef __com_sun_star_rendering_XBitmapCanvas_idl__
  37 #include <com/sun/star/rendering/XBitmapCanvas.idl>
  38 #endif
  39 #ifndef __com_sun_star_rendering_XAnimation_idl__
  40 #include <com/sun/star/rendering/XAnimation.idl>
  41 #endif
  42 #ifndef __com_sun_star_rendering_VolatileContentDestroyedException_idl__
  43 #include <com/sun/star/rendering/VolatileContentDestroyedException.idl>
  44 #endif
  45
  46 module com { module sun { module star { module rendering {
  47
  48 interface XSprite;
  49 interface XAnimatedSprite;
  50 interface XCustomSprite;
  51
  52 /** Specialization of a XBitmapCanvas, where moving, animated objects
  53     (called sprites) are supported.<p>
  54
  55     @attention The screen output of canvas drawing operations is
  56     undefined, unless XSpriteCanvas::updateScreen() is called. This is
  57     because a sprite canvas might choose to employ double buffering to
  58     reduce animation flicker, and cannot know the instant suitable to
  59     display the newly rendered canvas content. When using external
  60     double-buffering via XBufferController on a sprite canvas, the
  61     implementation takes care of this issue, and in this case is able
  62     to render correctly even without explicit updateScreen() calls
  63     (because there's a defined moment in time where content display
  64     can happen, namely the XBufferController::showBuffer()) call. If
  65     you don't need sprite functionality, and don't want the
  66     updateScreen hassle, simply use the XBitmapCanvas.
  67  */
  68 interface XSpriteCanvas : XBitmapCanvas
  69 {
  70     /** Create a sprite object from the specified animation
  71         sequence. A sprite is a back-buffered object with its own,
  72         independent animation.
  73      */
  74     XAnimatedSprite     createSpriteFromAnimation( [in] XAnimation animation )
  75         raises (com::sun::star::lang::IllegalArgumentException);
  76
  77     /** Create a sprite object from the specified animation
  78         sequence.
  79
  80         A sprite is a back-buffered object with its own,
  81         independent animation.
  82
  83         @param animationBitmaps
  84         Sequence of bitmaps. The bitmaps don't need to have the same
  85         size, but they are all rendered with their left, top edges
  86         aligned.
  87
  88         @param interpolationMode
  89         Value of <type>InterpolationMode</type>, to determine whether
  90         and how to interpolate between the provided bitmaps, if
  91         animation runs fast enough.
  92
  93         @throws <type>VolatileContentDestroyedException</type>
  94         if at least one of the bitmap is volatile, and its content has been destroyed by the system.
  95      */
  96     XAnimatedSprite     createSpriteFromBitmaps( [in] sequence<XBitmap> animationBitmaps, [in] byte interpolationMode )
  97         raises (com::sun::star::lang::IllegalArgumentException,
  98                 VolatileContentDestroyedException);
  99
 100     /** Create a custom, user-handles-it-all sprite object.
 101
 102         A sprite is a back-buffered object with its own, independent
 103         animation.
 104
 105         @param spriteSize
 106         The required size of the sprite in device
 107         coordinates. Everything that is rendered outside this area
 108         might be clipped on output. Both components of the size must
 109         be greater than zero.
 110
 111         @return an interface to a custom sprite object.
 112      */
 113     XCustomSprite createCustomSprite( [in] ::com::sun::star::geometry::RealSize2D spriteSize )
 114         raises (com::sun::star::lang::IllegalArgumentException);
 115
 116     /** Create a cloned version of an already existing sprite
 117         object.
 118
 119         The cloned sprite always shows the same content as its
 120         original. Furthermore, cloned copies of a hidden original are
 121         never visible, although cloned copies of a visible original
 122         can of course be invisible.
 123
 124         @param original
 125         The original sprite to copy the content from. This sprite must
 126         have been created by the same XSpriteCanvas instance as this
 127         method is called on. Other sprite instances will generate an
 128         IllegalArgumentException.
 129
 130         @return an interface to a sprite object.
 131      */
 132     XSprite createClonedSprite( [in] XSprite original )
 133         raises (com::sun::star::lang::IllegalArgumentException);
 134
 135     /** Tells the sprite canvas to now update the screen
 136          representation.
 137
 138         Required to display rendered changes to the canvas, and
 139         updates to stopped animations and XCustomSprites in
 140         general. This method will return only after the screen update
 141         is done, or earlier if an error happened.<p>
 142
 143         If double buffering is enabled via XBufferController, no
 144         explicit call of updateScreen() is necessary, since the
 145         XBufferController methods will automatically notify all
 146         associated XSpriteCanvas instances.<p>
 147
 148         @param bUpdateAll
 149         When <TRUE/>, update the whole screen. When <FALSE/>,
 150         implementation is permitted to restrict update to areas the
 151         canvas itself changed (e.g. because of render operations, or
 152         changes on the sprites). The former is useful for updates
 153         after window expose events. the latter for animation display.
 154
 155         @return <TRUE/>, if the screen update was successfully
 156         performed
 157      */
 158     boolean updateScreen( [in] boolean bUpdateAll );
 159 };
 160
 161 }; }; }; };
 162
 163 #endif