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