slideshow/source/inc/doctreenodesupplier.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_DOCTREENODESUPPLIER_HXX
  21 #define INCLUDED_SLIDESHOW_SOURCE_INC_DOCTREENODESUPPLIER_HXX
  22
  23 #include "doctreenode.hxx"
  24
  25
  26 /* Definition of DocTreeNodeSupplier interface */
  27
  28 namespace slideshow::internal
  29     {
  30         /** Interface to retrieve DocTreeNodes from subsettable
  31             shapes.
  32
  33             Shapes which implement the AttributableShape interface
  34             also provides this interface, providing methods to
  35             retrieve specific DocTreeNode objects from the shape. The
  36             methods mainly distinguish various ways on how to specify
  37             the actual DocTreeNode to return.
  38
  39             If a requested DocTreeNode is not available when one of
  40             the methods below is called, an empty DocTreeNode will be
  41             returned (the predicate DocTreeNode::isEmpty() will return
  42             true). If, on the other hand, the shape cannot determine,
  43             for internal reasons, the internal tree node structure,
  44             all those methods will throw an
  45             ShapeLoadFailedException. This is, in fact, a delayed error
  46             that could also have been reported during shape
  47             construction, but might be postponed until the missing
  48             information is actually requested.
  49          */
  50         class DocTreeNodeSupplier
  51         {
  52         public:
  53             /** Query number of tree nodes of the given type this
  54                 shape contains.
  55
  56                 The value returned by this method minus one is the
  57                 maximum value permissible at the getTreeNode()
  58                 method, for the given node type.
  59
  60                 @throws ShapeLoadFailedException, if tree node structure
  61                 cannot be determined.
  62              */
  63             virtual sal_Int32 getNumberOfTreeNodes( DocTreeNode::NodeType eNodeType ) const = 0; // throw ShapeLoadFailedException;
  64
  65             /** Create DocTreeNode from shape.
  66
  67                 This method creates a DocTreeNode from a shape, a
  68                 given node type and a running index into the shape's
  69                 DocTreeNodes of the given type.
  70
  71                 @param nNodeIndex
  72                 Starting with 0, every DocTreeNode of the shape that
  73                 has type eNodeType is indexed. The DocTreeNode whose
  74                 index equals nNodeIndex will be returned.
  75
  76                 @param eNodeType
  77                 Type of the node to return
  78
  79                 @return the DocTreeNode found, or the empty
  80                 DocTreeNode, if nothing was found.
  81
  82                 @throws ShapeLoadFailedException, if tree node structure
  83                 cannot be determined.
  84             */
  85             virtual DocTreeNode getTreeNode( sal_Int32              nNodeIndex,
  86                                              DocTreeNode::NodeType  eNodeType ) const = 0; // throw ShapeLoadFailedException;
  87
  88             /** Query number of tree nodes of the given type this
  89                 subset contains.
  90
  91                 The value returned by this method minus one is the
  92                 maximum value permissible at the
  93                 getSubsetTreeNode() method, for the given node
  94                 type.
  95
  96                 @param rParentNode
  97                 The parent node, below which the number of tree nodes
  98                 of the given type shall be counted.
  99
 100                 @param eNodeType
 101                 Node type to count.
 102
 103                 @throws ShapeLoadFailedException, if tree node structure
 104                 cannot be determined.
 105              */
 106             virtual sal_Int32 getNumberOfSubsetTreeNodes( const DocTreeNode&    rParentNode,
 107                                                           DocTreeNode::NodeType eNodeType ) const = 0; // throw ShapeLoadFailedException;
 108
 109             /** Create DocTreeNode from shape subset.
 110
 111                 This method creates a DocTreeNode from a shape, a
 112                 parent tree node, a given node type and a running
 113                 index into the shape's DocTreeNodes of the given type.
 114
 115                 @param rParentNode
 116                 Parent node, below which the tree node with the given
 117                 type shall be selected.
 118
 119                 @param nNodeIndex
 120                 Starting with 0, every DocTreeNode of the shape that
 121                 has type eNodeType is indexed. The DocTreeNode whose
 122                 index equals nNodeIndex will be returned.
 123
 124                 @param eNodeType
 125                 Type of the node to return
 126
 127                 @return the DocTreeNode found, or the empty
 128                 DocTreeNode, if nothing was found.
 129
 130                 @throws ShapeLoadFailedException, if tree node structure
 131                 cannot be determined.
 132             */
 133             virtual DocTreeNode getSubsetTreeNode( const DocTreeNode&       rParentNode,
 134                                                    sal_Int32                nNodeIndex,
 135                                                    DocTreeNode::NodeType    eNodeType ) const = 0; // throw ShapeLoadFailedException;
 136
 137         protected:
 138             ~DocTreeNodeSupplier() {}
 139         };
 140
 141 }
 142
 143 #endif // INCLUDED_SLIDESHOW_SOURCE_INC_DOCTREENODESUPPLIER_HXX
 144
 145 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */