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