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