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