sd/inc/OutlinerIterator.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_SD_INC_OUTLINERITERATOR_HXX
  21 #define INCLUDED_SD_INC_OUTLINERITERATOR_HXX
  22
  23 #include <svx/svdobj.hxx>
  24
  25 #include "pres.hxx"
  26 #include "sal/types.h"
  27 #include <vector>
  28 #include <boost/shared_ptr.hpp>
  29
  30 class SdDrawDocument;
  31
  32 namespace sd {
  33
  34 class ViewShell;
  35 class Outliner;
  36
  37 namespace outliner {
  38
  39 class IteratorImplBase;
  40 class IteratorPosition;
  41
  42 /** Use this enum to specify the initial location of the object pointed to by
  43     a newly created iterator.  The values are
  44     <ul><li><const>BEGIN</const> for the first object with reference to
  45     iteration direction.</li>
  46     <li>END for one past the last valid object or, if the iterator is a
  47     backward iterator, the object in front of the first valid one.</li>
  48     <li>CURRENT for the current object.  Because there is only a current
  49     page this usually is taken to be the first/last object on the current
  50     page.</li></ul>
  51 */
  52 enum IteratorLocation {BEGIN,END,CURRENT};
  53
  54 /** Use this enum to specify the type of iterator when creating a new
  55     iterator:
  56     <ul><li>SELECTION for iteration over all objects that belong to the
  57     current mark list.</li>
  58     <li>SINGLE_VIEW for iteration over all objects in the current view.</li>
  59     <li>DOCUMENT for iteration over all object in all relevant
  60     views.</li></ul>
  61 */
  62 enum IteratorType {SELECTION,SINGLE_VIEW,DOCUMENT};
  63
  64 /** This iterator can be used to iterate over all <type>SdrObject</type>
  65     objects of one of three set denoted by the <type>IteratorType</type>:
  66     <ul><li>All objects of the current mark list (selection)
  67     (type==SELECTION).</li>
  68     <li>All objects in the current view (type==SINGLE_VIEW).</li>
  69     <li>All objects in all views (type=DOCUMENT).</li></ul>
  70
  71     <p>Note that the iterator does not change pages or views.  It is the
  72     task of the user of the iterator to take the information provided by the
  73     <type>IteratorPosition</type> as returned by the
  74     <member>operator*()</member> method and set view, visible page, and
  75     selection/edit mode markers to reflect this position.</p>
  76
  77     <p>A simple forward iteration from the first to the last object would
  78     instantiate the iterator with
  79     <code>Iterator(pDocument,pViewShell,true,BEGIN)</code> for some document
  80     and view shell.  This iterator can then be compared against
  81     <code>Iterator(pDocument,pViewShell,true,END)</code>.  On equality the
  82     iteration should be stopped without evaluating the iterator: The position
  83     of an end iterator is not valid.</p>
  84 */
  85 class Iterator
  86 {
  87 public:
  88     Iterator();
  89
  90     /** The copy constructor creates a new iterator by copying the
  91         implementation object.
  92     */
  93     Iterator (const Iterator& rIterator);
  94
  95     /** Create a new iterator with the implementation object being the
  96         provided one.
  97         @param pObject
  98             A copy of this object will become the implementation object.
  99     */
 100     explicit Iterator (IteratorImplBase* pObject);
 101
 102     ~Iterator();
 103
 104     /** Assign the iterator from the given one.  The implementation object
 105         of this iterator will be a copy of the given iterator.
 106         @param rIterator
 107             The iterator which to assign from.
 108     */
 109     Iterator& operator= (const Iterator& rIterator);
 110     /** Return the current position of the iterator.
 111         @return
 112             Returns a reference to the current position.  Therefore this
 113             method is not thread safe.  The reason for this behaviour is, of
 114             course, to omit the copying of the returned position.
 115     */
 116     const IteratorPosition& operator* () const;
 117     /** The prefix increment operator returns the iterator pointing to the
 118         next object.  When in doubt prefer this operator over the postfix
 119         increment operator.
 120         @return
 121             Returns a reference to this iterator pointing to the next object.
 122     */
 123     Iterator& operator++ ();
 124     /** The postfix increment operator returns the iterator still pointing
 125         to the current object.  Only the next call to
 126         <member>operator*()</member> will return the next object.  When in
 127         doubt rather use the prefix increment operator.
 128         @param dummy
 129             A dummy operator used by the compiler.
 130         @return
 131             Returns a copy of the iterator as it where before the operator
 132             was called.
 133     */
 134     Iterator operator++ (int);
 135     /** Test equality of two iterators.  Two iterators are taken to be equal
 136         when they point are of the same type (their implementation objects
 137         are instances of the same class) and point to the same object.
 138         @param rIterator
 139             The iterator to test equality with.
 140         @return
 141             Returns <TRUE/> when both iterators point to the same object.
 142     */
 143     bool operator== (const Iterator& rIterator);
 144     /** Test whether two iterators point to different objects.  This is just
 145         the negation of the result of the equality operator.
 146         @param rIterator
 147             The iterator to test inequality with.
 148         @return
 149             Returns <TRUE/> when both iterators point to the different objects.
 150     */
 151     bool operator!= (const Iterator& rIterator);
 152     /** Reverse the direction of iteration.  The position of the iterator is
 153         not changed.  Thus calling this method twice returns to the old state.
 154     */
 155     void Reverse();
 156
 157 private:
 158     /// The implementation object to which most of the methods are forwarded.
 159     IteratorImplBase* mpIterator;
 160 };
 161
 162 /** This class wraps the <type>Outliner</type> class and represents it as
 163     a container of <type>SdrObject</type> objects.  Its main purpose is to
 164     provide iterators for certain sub-sets of those objects.  These sub-sets
 165     are a) the set of the currently selected objects, b) all objects in the
 166     current view, and c) all objects in all views.
 167
 168     <p>The direction of the returned iterators depends on the underlying
 169     <type>Outliner</type> object and is usually set in the search
 170     dialog.</p>
 171 */
 172 class OutlinerContainer
 173 {
 174 public:
 175     /** Create a new wrapper object for the given outliner.
 176         @param pOutliner
 177             The outliner that is represented by the new object as
 178             <type>SdrObject</type> container.
 179     */
 180     OutlinerContainer (::sd::Outliner* pOutliner);
 181
 182     /** Return an iterator that points to the first object of one of the
 183         sets described above.  This takes also into account the direction of
 184         iteration.
 185         @return
 186             The returned iterator points either to the first (forward
 187             search) or to the last object (backward search) of the set.
 188     */
 189     Iterator begin();
 190
 191     /** Return an iterator that marks the end of the iteration.  This takes
 192         also into account the direction of iteration. The object pointed to
 193         is not valid.
 194         @return
 195             The returned iterator points either to that object past the last
 196             one (forward search) or to the one in front of the first
 197             (backward search).
 198     */
 199     Iterator end();
 200
 201     /** Return an iterator that points to the current object of one of the
 202         sets described above.  This takes also into account the direction of
 203         iteration.
 204         @return
 205             The returned iterator points either to the first (forward
 206             search) or to the last object (backward search) of the set of
 207             selected objects or of the current page if the search set spans
 208             more than one page.
 209     */
 210     Iterator current();
 211
 212 private:
 213     /// The wrapped outliner that is represented as object container.
 214     ::sd::Outliner* mpOutliner;
 215
 216     /** Create an iterator.  The object pointed to depends on the search
 217         direction retrieved from the outliner object
 218         <member>mpOutliner</member> and the given location.
 219         @param aLocation
 220             This specifies whether the returned iterator points to the
 221             first, (one past the) last, or current object.
 222         @return
 223             Returns an iterator as constructed by
 224             <member>CreateSelectionIterator()</member>,
 225      */
 226     Iterator CreateIterator (IteratorLocation aLocation);
 227
 228     /** Create an iterator that iterates over all currently selected
 229         <type>SdrObjects</type> objects of the <member>mpOutliner</member>
 230         outliner.
 231         @param rObjectList
 232             List of currently selected objects.  This list is necessary
 233             so that the selection can be changed without affecting the
 234             iterator.
 235         @param pDocument
 236             The document to which the objects belong.
 237         @param pViewShell
 238             The view shell which displays the objects.
 239         @param bDirectionIsForward
 240             The direction of iteration.  It defaults to forward.
 241         @param aLocation
 242             This specifies at which object the iterator points initially.
 243     */
 244     static Iterator CreateSelectionIterator (
 245         const ::std::vector<SdrObjectWeakRef>& rObjectList,
 246         SdDrawDocument* pDocument,
 247         const ::boost::shared_ptr<ViewShell>& rpViewShell,
 248         bool bDirectionIsForward=true,
 249         IteratorLocation aLocation=BEGIN);
 250
 251     /** Create an iterator that iterates over all <type>SdrObjects</type>
 252         objects of the <member>mpOutliner</member> outliner.
 253         @param pDocument
 254             The document to which the objects belong.
 255         @param pViewShell
 256             The view shell which displays the objects.
 257         @param bDirectionIsForward
 258             The direction of iteration.  It defaults to forward.
 259         @param aLocation
 260             This specifies at which object the iterator points initially.
 261     */
 262     static Iterator CreateDocumentIterator (
 263         SdDrawDocument* pDocument,
 264         const ::boost::shared_ptr<ViewShell>& rpViewShell,
 265         bool bDirectionIsForward=true,
 266         IteratorLocation aLocation=BEGIN);
 267
 268     /** Return the index of a page that contains an object that a new
 269         iterator shall point to.  This page index depends primarily on the
 270         location, iteration direction, as well as on edit mode and page
 271         kind.
 272         @param pDocument
 273             The document to which the page belongs.
 274         @param pViewShell
 275             The view shell which displays the page.
 276         @param ePageKind
 277             Specifies the view the page belongs to.
 278         @param eEditMode
 279             Specifies whether the page is a master page.
 280         @param bDirectionIsForward
 281             The direction of iteration.
 282         @param aLocation
 283             This specifies at which object the iterator points initially.
 284     */
 285     static sal_Int32 GetPageIndex (
 286         SdDrawDocument* pDocument,
 287         const ::boost::shared_ptr<ViewShell>& rpViewShell,
 288         PageKind ePageKind,
 289         EditMode eEditMode,
 290         bool bDirectionIsForward,
 291         IteratorLocation aLocation);
 292
 293     // Do not allow default constructor and copying of outliner containers.
 294     OutlinerContainer (const OutlinerContainer&) {};
 295     OutlinerContainer() {};
 296     OutlinerContainer& operator= (const OutlinerContainer&) {return *this;};
 297 };
 298
 299 /** Data collection specifying a <type>SdrObject</type> and its position in
 300     a document and view.
 301 */
 302 class IteratorPosition
 303 {
 304 public:
 305     /** Create a new object with all data members set to default values.
 306         These values should not be accessed.  The only use of the object as
 307         it is as a marker in comparisons.
 308     */
 309     IteratorPosition();
 310     /** Create a new object with all data members set from the given
 311         position.
 312         @param aPosition
 313             The position object from which to take the values that are
 314             assigned to the data members of this object.
 315     */
 316     IteratorPosition (const IteratorPosition& aPosition);
 317
 318     /// The destructor is a no-op at the moment.
 319     ~IteratorPosition();
 320     /** Assign the content of the given position to this one.
 321         @param aPosition
 322             This is the position object from which to take the values of all
 323             data members.
 324         @return
 325             Returns a reference to this object.
 326     */
 327     IteratorPosition& operator= (const IteratorPosition& aPosition);
 328     /** Compare two positions for equality.
 329         @return
 330             <TRUE/> is returned only when all data members have the same
 331             values in both position objects.
 332     */
 333     bool operator== (const IteratorPosition& aPosition) const;
 334
 335     /// Pointer to the actual <type>SdrObject</type> object.
 336     SdrObjectWeakRef mxObject;
 337
 338     /// Number of the actual SdrText from the current <type>SdrObject</type>
 339     sal_Int32 mnText;
 340
 341     /// The index of a page where the object is located on.
 342     sal_Int32 mnPageIndex;
 343     /// Page kind of the view.
 344     PageKind mePageKind;
 345     /// Edit mode of the view.
 346     EditMode meEditMode;
 347 };
 348
 349 } } // end of namespace ::sd::outliner
 350
 351 #endif // _ INCLUDED_SD_INC_OUTLINERITERATOR_HXX
 352
 353 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */