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