slideshow/source/inc/attributableshape.hxx

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