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