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