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 explicitly 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                 explicitly 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 explicitly 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                 explicitly 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 explicitly 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