slideshow/source/inc/attributableshape.hxx

   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: attributableshape.hxx,v $
  10  * $Revision: 1.9 $
  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
  31 #ifndef INCLUDED_SLIDESHOW_ATTRIBUTABLESHAPE_HXX
  32 #define INCLUDED_SLIDESHOW_ATTRIBUTABLESHAPE_HXX
  33
  34 #include <boost/shared_ptr.hpp>
  35
  36 #include "animatableshape.hxx"
  37 #include "shapeattributelayer.hxx"
  38 #include "doctreenodesupplier.hxx"
  39
  40 namespace slideshow
  41 {
  42     namespace internal
  43     {
  44         // forward declaration necessary, because methods use AttributableShapeSharedPtr
  45         class AttributableShape;
  46
  47         typedef ::boost::shared_ptr< AttributableShape > AttributableShapeSharedPtr;
  48
  49         /** Represents an animatable shape, that can have its
  50             attributes changed.
  51
  52             Over an animatable shape, this interface adds attribute
  53             modification methods. Furthermore, the shape can be
  54             queried for sub items, which in turn can be separated out
  55             into own AttributableShapes.
  56          */
  57         class AttributableShape : public AnimatableShape
  58         {
  59         public:
  60             // Attribute layer methods
  61             //------------------------------------------------------------------
  62
  63             /** Create a new shape attribute layer.
  64
  65                 This method creates a new layer for shape attributes,
  66                 which lies atop of all previous attribute layers. That
  67                 is most typically used when a new SMIL animation
  68                 starts (which according to the spec always lies atop
  69                 of all previous animations). Thus, subsequent calls to
  70                 this method generate a sandwich of attribute layers,
  71                 which in total define the shape's attributes.
  72
  73                 Please note that the attribute layers do <em>not</em>
  74                 contain the underlying XShape's attributes as
  75                 default. Instead, attributes not explicitely set by
  76                 animations remain in invalid state, allowing the
  77                 shape's paint method to determine whether they have to
  78                 override the underlying graphical shape
  79                 representation. XShape attributes must be passed
  80                 explicitely to animations which need them (e.g. 'by'
  81                 animations).
  82
  83                 @return the new layer
  84              */
  85             virtual ShapeAttributeLayerSharedPtr createAttributeLayer() = 0;
  86
  87             /** Revoke a previously generated attribute layer.
  88
  89                 This method revokes a previously generated attribute
  90                 layer, and removes the effect of that layer from this
  91                 shape. The layer need not be the current toplevel
  92                 layer, it can also be revoked from in between.
  93
  94                 @param rLayer
  95                 Layer to revoke. Must have been generated by
  96                 createAttributeLayer() at the same Shape.
  97
  98                 @return true, if layer was successfully removed, false
  99                 otherwise (e.g. if the given layer was not generated
 100                 for this shape).
 101              */
 102             virtual bool revokeAttributeLayer( const ShapeAttributeLayerSharedPtr& rLayer ) = 0;
 103
 104             /** Get the topmost shape attribute layer (if any).
 105
 106                 This method returns the topmost layer for shape
 107                 attributes, i.e. the one which ultimately determines
 108                 the shape's look.
 109
 110                 Please note that the attribute layers do <em>not</em>
 111                 contain the underlying XShape's attributes as
 112                 default. Instead, attributes not explicitely set by
 113                 animations remain in invalid state, allowing the
 114                 shape's paint method to determine whether they have to
 115                 override the underlying graphical shape
 116                 representation. XShape attributes must be passed
 117                 explicitely to animations which need them (e.g. 'by'
 118                 animations).
 119
 120                 @return the topmost layer
 121              */
 122             virtual ShapeAttributeLayerSharedPtr getTopmostAttributeLayer() const = 0;
 123
 124
 125             /** Change default shape visibility
 126
 127                 This method hides or unhides a shape. Note that every
 128                 attribute layer generated for this shape is able to
 129                 override the setting given here, until it is revoked.
 130
 131                 @param bVisible
 132                 When true, shape will be visible, when false,
 133                 invisible (modulo attribute layer overrides).
 134              */
 135             virtual void setVisibility( bool bVisible ) = 0;
 136
 137             // Sub-item handling
 138             //------------------------------------------------------------------
 139
 140             /** Retrieve interface for DocTreeNode creation.
 141
 142                 This method provides the caller with a reference to
 143                 the DocTreeNodeSupplier interface, which can be used
 144                 to request specific tree nodes for this shape.
 145              */
 146             virtual const DocTreeNodeSupplier& getTreeNodeSupplier() const = 0;
 147             virtual DocTreeNodeSupplier&           getTreeNodeSupplier() = 0;
 148
 149             /** Query the subset this shape displays.
 150
 151                 This method returns a tree node denoting the subset
 152                 displayed by this shape. If this shape is not a subset
 153                 shape, an empty tree node should be returned. If this
 154                 shape is a subset, and itself has subsetted children,
 155                 this method might return more than the shape is
 156                 actually displaying (because a single DocTreeNode is
 157                 not able to model holes in the range).
 158              */
 159             virtual DocTreeNode getSubsetNode() const = 0;
 160
 161             /** Query a subset Shape, if already existent at this
 162                 object
 163
 164                 This method returns a clone of this Shape, which
 165                 renders only the selected subset of itself, but only
 166                 if such a subset has been explicitely created before.
 167
 168                 @param rTreeNode
 169                 A DocTreeNode instance queried from this Shape, which
 170                 specifies the subset of the Shape to render.
 171
 172                 @return a NULL Shape pointer, if no subset exists for
 173                 the given DocTreeNode.
 174             */
 175             virtual AttributableShapeSharedPtr getSubset( const DocTreeNode& rTreeNode ) const = 0;
 176
 177             /** Create a subset Shape
 178
 179                 This method creates a clone of this Shape, which
 180                 renders only the selected subset of itself. Multiple
 181                 createSubset() calls for the same DocTreeNode will all
 182                 share the same subset shape.
 183
 184                 The original shape (i.e. the one this method is called
 185                 on) will cease to display the selected subset
 186                 part. That is, together the shapes will display the
 187                 original content, but the content of all subset shapes
 188                 and their original shape will always be mutually
 189                 disjunct.
 190
 191                 After deregistering the subset shape a matching number
 192                 of times via revokeSubset(), the original shape will
 193                 resume displaying the subsetted part.
 194
 195                 @attention To maintain view integrity, this method
 196                 should only be called from the LayerManager
 197
 198                 @param o_rSubset
 199                 The requested Shape
 200
 201                 @param rTreeNode
 202                 A DocTreeNode instance queried from this Shape, which
 203                 specifies the subset of the Shape to render
 204
 205                 @return true, if the shape was newly created, and
 206                 false, if an already existing subset is returned.
 207             */
 208             virtual bool createSubset( AttributableShapeSharedPtr&      o_rSubset,
 209                                        const DocTreeNode&                       rTreeNode ) = 0;
 210
 211             /** Revoke a previously generated shape subset.
 212
 213                 After revoking a subset shape, the corresponding
 214                 subset part will become visible again on the original
 215                 shape.
 216
 217                 @attention To maintain view integrity, this method
 218                 should only be called from the LayerManager
 219
 220                 @param rShape
 221                 The subset to revoke
 222
 223                 @return true, if the last client called
 224                 revokeSubset().
 225              */
 226             virtual bool revokeSubset( const AttributableShapeSharedPtr& rShape ) = 0;
 227         };
 228     }
 229 }
 230
 231 #endif /* INCLUDED_SLIDESHOW_ATTRIBUTABLESHAPE_HXX */