sd/inc/OutlinerIterator.hxx

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