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