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