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 371