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