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