slideshow/source/inc/doctreenodesupplier.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: doctreenodesupplier.hxx,v $
  10  * $Revision: 1.6 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef INCLUDED_SLIDESHOW_DOCTREENODESUPPLIER_HXX
  32 #define INCLUDED_SLIDESHOW_DOCTREENODESUPPLIER_HXX
  33
  34 #include "doctreenode.hxx"
  35
  36
  37 /* Definition of DocTreeNodeSupplier interface */
  38
  39 namespace slideshow
  40 {
  41     namespace internal
  42     {
  43         /** Interface to retrieve DocTreeNodes from subsettable
  44             shapes.
  45
  46             Shapes which implement the AttributableShape interface
  47             also provides this interface, providing methods to
  48             retrieve specific DocTreeNode objects from the shape. The
  49             methods mainly distinguish various ways on how to specify
  50             the actual DocTreeNode to return.
  51
  52             If a requested DocTreeNode is not available when one of
  53             the methods below is called, an empty DocTreeNode will be
  54             returned (the predicate DocTreeNode::isEmpty() will return
  55             true). If, on the other hand, the shape cannot determine,
  56             for internal reasons, the internal tree node structure,
  57             all those methods will throw an
  58             ShapeLoadFailedException. This is, in fact, a delayed error
  59             that could also have been reported during shape
  60             construction, but might be postponed until the missing
  61             information is actually requested.
  62          */
  63         class DocTreeNodeSupplier
  64         {
  65         public:
  66             /** Query number of tree nodes of the given type this
  67                 shape contains.
  68
  69                 The value returned by this method minus one is the
  70                 maximum value permissible at the getTreeNode()
  71                 method, for the given node type.
  72
  73                 @throws ShapeLoadFailedException, if tree node structure
  74                 cannot be determined.
  75              */
  76             virtual sal_Int32 getNumberOfTreeNodes( DocTreeNode::NodeType eNodeType ) const = 0; // throw ShapeLoadFailedException;
  77
  78             /** Create DocTreeNode from shape.
  79
  80                 This method creates a DocTreeNode from a shape, a
  81                 given node type and a running index into the shape's
  82                 DocTreeNodes of the given type.
  83
  84                 @param nNodeIndex
  85                 Starting with 0, every DocTreeNode of the shape that
  86                 has type eNodeType is indexed. The DocTreeNode whose
  87                 index equals nNodeIndex will be returned.
  88
  89                 @param eNodeType
  90                 Type of the node to return
  91
  92                 @return the DocTreeNode found, or the empty
  93                 DocTreeNode, if nothing was found.
  94
  95                 @throws ShapeLoadFailedException, if tree node structure
  96                 cannot be determined.
  97             */
  98             virtual DocTreeNode getTreeNode( sal_Int32                          nNodeIndex,
  99                                              DocTreeNode::NodeType      eNodeType ) const = 0; // throw ShapeLoadFailedException;
 100
 101             /** Query number of tree nodes of the given type this
 102                 subset contains.
 103
 104                 The value returned by this method minus one is the
 105                 maximum value permissible at the
 106                 getSubsetTreeNode() method, for the given node
 107                 type.
 108
 109                 @param rParentNode
 110                 The parent node, below which the number of tree nodes
 111                 of the given type shall be counted.
 112
 113                 @param eNodeType
 114                 Node type to count.
 115
 116                 @throws ShapeLoadFailedException, if tree node structure
 117                 cannot be determined.
 118              */
 119             virtual sal_Int32 getNumberOfSubsetTreeNodes( const DocTreeNode&    rParentNode,
 120                                                           DocTreeNode::NodeType eNodeType ) const = 0; // throw ShapeLoadFailedException;
 121
 122             /** Create DocTreeNode from shape subset.
 123
 124                 This method creates a DocTreeNode from a shape, a
 125                 parent tree node, a given node type and a running
 126                 index into the shape's DocTreeNodes of the given type.
 127
 128                 @param rParentNode
 129                 Parent node, below which the tree node with the given
 130                 type shall be selected.
 131
 132                 @param nNodeIndex
 133                 Starting with 0, every DocTreeNode of the shape that
 134                 has type eNodeType is indexed. The DocTreeNode whose
 135                 index equals nNodeIndex will be returned.
 136
 137                 @param eNodeType
 138                 Type of the node to return
 139
 140                 @return the DocTreeNode found, or the empty
 141                 DocTreeNode, if nothing was found.
 142
 143                 @throws ShapeLoadFailedException, if tree node structure
 144                 cannot be determined.
 145             */
 146             virtual DocTreeNode getSubsetTreeNode( const DocTreeNode&           rParentNode,
 147                                                    sal_Int32                            nNodeIndex,
 148                                                    DocTreeNode::NodeType        eNodeType ) const = 0; // throw ShapeLoadFailedException;
 149         };
 150
 151     }
 152 }
 153
 154 #endif /* INCLUDED_SLIDESHOW_DOCTREENODESUPPLIER_HXX */