offapi/com/sun/star/rendering/XSprite.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_XSprite_idl__
  20 #define __com_sun_star_rendering_XSprite_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/geometry/AffineMatrix2D.idl>
  26 #include <com/sun/star/rendering/ViewState.idl>
  27 #include <com/sun/star/rendering/RenderState.idl>
  28
  29 module com { module sun { module star { module rendering {
  30
  31 /** Interface to control a sprite object.<p>
  32
  33     This is the basic interface to control a sprite object on a
  34     XSpriteCanvas. Sprites are moving, back-buffered
  35     objects.<p>
  36  */
  37 interface XSprite : ::com::sun::star::uno::XInterface
  38 {
  39     /** Set overall transparency of the sprite.<p>
  40
  41         This method is useful for e.g. fading in/out of animations.<p>
  42
  43         Please note that if this sprite is not animated, the
  44         associated XSpriteCanvas does not update changed
  45         sprites automatically, but has to be told to do so via
  46         XSpriteCanvas::updateScreen().<p>
  47
  48         @param nAlpha
  49         New global alpha value to composite this sprite with the
  50         background. Valid range is [0,1].
  51
  52         @throws com::sun::star::lang::IllegalArgumentException
  53         if nAlpha is not within the permissible range.
  54      */
  55     void setAlpha( [in] double nAlpha )
  56         raises (com::sun::star::lang::IllegalArgumentException);
  57
  58
  59     /** Move sprite to the specified position.<p>
  60
  61         The position specified here is first transformed by the
  62         combined view and render transformation. The resulting
  63         position is then used as the output position (also in device
  64         coordinates) of the rendered sprite content.<p>
  65
  66         Please note that if this sprite is not animated, the
  67         associated XSpriteCanva does not update changed sprites
  68         automatically, but has to be told to do so via
  69         XSpriteCanvas::updateScreen().<p>
  70
  71         @param aNewPos
  72         The new position, in user coordinate space, to move the sprite to.
  73
  74         @param aViewState
  75         The view state to be used when interpreting aNewPos.
  76
  77         @param aRenderState
  78         The render state to be used when interpreting aNewPos.
  79
  80         @throws com::sun::star::lang::IllegalArgumentException
  81         if one of the view and render state parameters are outside the
  82         specified range.
  83      */
  84     void move( [in] ::com::sun::star::geometry::RealPoint2D aNewPos, [in] ViewState aViewState, [in] RenderState aRenderState )
  85         raises (com::sun::star::lang::IllegalArgumentException);
  86
  87
  88     /** Apply a local transformation to the sprite.<p>
  89
  90         The given transformation matrix locally transforms the sprite
  91         shape. If this transformation contains translational
  92         components, be aware that sprite content moved beyond the
  93         sprite area (a box from (0,0) to (spriteWidth,spriteHeight))
  94         might (but need not) be clipped. Use
  95         XSprite::move() to change the sprite location
  96         on screen. The canvas implementations are free, if they have a
  97         cached representation of the sprite at hand, to transform only
  98         this cached representation (e.g. a bitmap), instead of
  99         re-rendering the sprite from first principles. This is usually
 100         the case for an implementation of a XCustomSprite
 101         interface, since it typically has no other cached pictorial
 102         information at hand.<p>
 103
 104         Please note that if this sprite is not animated, the
 105         associated XSpriteCanvas does not update changed
 106         sprites automatically, but has to be told to do so via
 107         XSpriteCanvas::updateScreen().<p>
 108
 109         @param aTransformation
 110         The transformation to apply to the sprite shape.
 111
 112         @throws com::sun::star::lang::IllegalArgumentException
 113         if the given transformation matrix is singular.
 114      */
 115     void transform( [in] com::sun::star::geometry::AffineMatrix2D aTransformation )
 116         raises (com::sun::star::lang::IllegalArgumentException);
 117
 118
 119     /** Apply a clipping to the shape output.<p>
 120
 121         The given clip poly-polygon is always interpreted in device
 122         coordinate space. As the sprite has its own local coordinate
 123         system, with its origin on screen being equal to its current
 124         position, the clip poly-polygon's origin will always coincide
 125         with the sprite's origin. Furthermore, if any sprite
 126         transformation is set via transform(), the clip is subject to
 127         this transformation, too. The implementation is free, if it
 128         has a cached representation of the sprite at hand, to
 129         clip-output only this cached representation (e.g. a bitmap),
 130         instead of re-rendering the sprite from first principles. This
 131         is usually the case for an implementation of a
 132         XCustomSprite interface, since it typically has
 133         no other cached pictorial information at hand.<p>
 134
 135         Please note that if this sprite is not animated, the
 136         associated XSpriteCanvas does not update changed
 137         sprites automatically, but has to be told to do so via
 138         XSpriteCanvas::updateScreen().<p>
 139
 140         Specifying an empty interface denotes no clipping,
 141         i.e. everything contained in the sprite will be visible
 142         (subject to device-dependent constraints, of
 143         course). Specifying an empty XPolyPolygon2D, i.e. a
 144         poly-polygon containing zero polygons, or an XPolyPolygon2D
 145         with any number of empty sub-polygons, denotes the NULL
 146         clip. That means, nothing from the sprite will be visible.<p>
 147
 148         @param aClip
 149         The clip poly-polygon to apply.
 150      */
 151     void clip( [in] XPolyPolygon2D aClip );
 152
 153
 154     /** Set sprite priority.<p>
 155
 156         The sprite priority determines the order of rendering relative
 157         to all other sprites of the associated canvas. The higher the
 158         priority, the later will the sprite be rendered, or, in other
 159         words, the closer to the screen surface the sprite is shown.<p>
 160
 161         @param nPriority
 162         New sprite priority value to serve as the sort key when
 163         determining sprite rendering order. Avoid NaNs and other
 164         irregular floating point values here, the order position for
 165         sprites with such a priority value is undefined.
 166      */
 167     void setPriority( [in] double nPriority );
 168
 169
 170     /** Make the sprite visible.<p>
 171
 172         This method makes the sprite visible on the canvas it was
 173         created on.<p>
 174      */
 175     void show();
 176
 177
 178     /** Make the sprite invisible.<p>
 179
 180         This method makes the sprite invisible.<p>
 181      */
 182     void hide();
 183
 184 };
 185
 186 }; }; }; };
 187
 188 #endif
 189
 190 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */