1 /*************************************************************************
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
5 * Copyright 2008 by Sun Microsystems, Inc.
7 * OpenOffice.org - a multi-platform office productivity suite
9 * $RCSfile: OutlinerIterator.hxx,v $
12 * This file is part of OpenOffice.org.
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.
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).
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.
29 ************************************************************************/
31 #ifndef SD_OUTLINER_ITERATOR_HXX
32 #define SD_OUTLINER_ITERATOR_HXX
34 #include <svx/svdobj.hxx>
37 #include "sal/types.h"
39 #include <boost/shared_ptr.hpp>
51 class IteratorImplBase
;
52 class IteratorPosition
;
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
64 enum IteratorLocation
{BEGIN
,END
,CURRENT
};
66 /** Use this enum to specify the type of iterator when creating a new
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
74 enum IteratorType
{SELECTION
,SINGLE_VIEW
,DOCUMENT
};
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>
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>
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>
103 /** The copy constructor creates a new iterator by copying the
104 implementation object.
106 Iterator (const Iterator
& rIterator
);
108 /** Create a new iterator with the implementation object being the
111 A copy of this object will become the implementation object.
113 explicit Iterator (IteratorImplBase
* pObject
);
115 /** Create a new iterator with the implementation object being the copy
118 A copy of this object will become the implementation object.
120 explicit Iterator (const IteratorImplBase
& rObject
);
124 /** Assign the iterator from the given one. The implementation object
125 of this iterator will be a copy of the given iterator.
127 The iterator which to assign from.
129 Iterator
& operator= (const Iterator
& rIterator
);
130 /** Return the current position of the iterator.
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.
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
141 Returns a reference to this iterator pointing to the next object.
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.
149 A dummy operator used by the compiler.
151 Returns a copy of the iterator as it where before the operator
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.
159 The iterator to test equality with.
161 Returns <TRUE/> when both iterators point to the same object.
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.
167 The iterator to test inequality with.
169 Returns <TRUE/> when both iterators point to the different objects.
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.
178 /// The implementation object to which most of the methods are forwarded.
179 IteratorImplBase
* mpIterator
;
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.
191 <p>The direction of the returned iterators depends on the underlying
192 <type>Outliner</type> object and is usually set in the search
195 class OutlinerContainer
198 /** Create a new wraper object for the given outliner.
200 The outliner that is represented by the new object as
201 <type>SdrObject</type> container.
203 OutlinerContainer (::sd::Outliner
* pOutliner
);
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
209 The returned iterator points either to the first (forward
210 search) or to the last object (backward search) of the set.
212 Iterator
begin (void);
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
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
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
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
233 Iterator
current (void);
236 /// The wrapped outliner that is represented as object container.
237 ::sd::Outliner
* mpOutliner
;
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.
243 This specifies whether the returned iterator points to the
244 first, (one past the) last, or current object.
246 Returns an iterator as constructed by one of the
247 <member>CreateSelectionIterator()</member>,
248 <member>CreateViewIterator()</member>, or <member>CreateDocumentIterator()</member>.
250 Iterator
CreateIterator (IteratorLocation aLocation
);
252 /** Create an iterator that iterates over all currently selected
253 <type>SdrObjects</type> objects of the <member>mpOutliner</member>
256 List of currently selected objects. This list is necessary
257 so that the selection can be changed without affecting the
260 The document to which the objects belong.
262 The view shell which displays the objects.
263 @param bDirectionIsForward
264 The direction of iteration. It defaults to forward.
266 This specifies at which object the iterator points initially.
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
);
275 /** Create an iterator that iterates over all <type>SdrObjects</type>
276 objects of the <member>mpOutliner</member> outliner that belong to
279 The document to which the objects belong.
281 The view shell which displays the objects.
282 @param bDirectionIsForward
283 The direction of iteration. It defaults to forward.
285 This specifies at which object the iterator points initially.
287 Iterator
CreateViewIterator (
288 SdDrawDocument
* pDocument
,
289 const boost::shared_ptr
<ViewShell
>& rpViewShell
,
290 bool bDirectionIsForward
=true,
291 IteratorLocation aLocation
=BEGIN
);
293 /** Create an iterator that iterates over all <type>SdrObjects</type>
294 objects of the <member>mpOutliner</member> outliner.
296 The document to which the objects belong.
298 The view shell which displays the objects.
299 @param bDirectionIsForward
300 The direction of iteration. It defaults to forward.
302 This specifies at which object the iterator points initially.
304 Iterator
CreateDocumentIterator (
305 SdDrawDocument
* pDocument
,
306 const ::boost::shared_ptr
<ViewShell
>& rpViewShell
,
307 bool bDirectionIsForward
=true,
308 IteratorLocation aLocation
=BEGIN
);
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
315 The document to which the page belongs.
317 The view shell which displays the page.
319 Specifies the view the page belongs to.
321 Specifies whether the page is a master page.
322 @param bDirectionIsForward
323 The direction of iteration.
325 This specifies at which object the iterator points initially.
327 sal_Int32
GetPageIndex (
328 SdDrawDocument
* pDocument
,
329 const ::boost::shared_ptr
<ViewShell
>& rpViewShell
,
332 bool bDirectionIsForward
,
333 IteratorLocation aLocation
);
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;};
344 /** Data collection specifying a <type>SdrObject</type> and its position in
347 class IteratorPosition
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.
354 IteratorPosition (void);
355 /** Create a new object with all data members set from the given
358 The position object from which to take the values that are
359 assigned to the data members of this object.
361 IteratorPosition (const IteratorPosition
& aPosition
);
362 /** Create a new object and set its data members to the given values.
364 IteratorPosition (SdrObject
* pObject
, sal_Int32 nText
, sal_Int32 nPageIndex
, PageKind ePageKind
, EditMode eEditMode
);
366 /// The destructor is a no-op at the moment.
367 ~IteratorPosition (void);
368 /** Assign the content of the given position to this one.
370 This is the position object from which to take the values of all
373 Returns a reference to this object.
375 IteratorPosition
& operator= (const IteratorPosition
& aPosition
);
376 /** Compare two positions for equality.
378 <TRUE/> is returned only when all data members have the same
379 values in both position objects.
381 bool operator== (const IteratorPosition
& aPosition
) const;
383 /// Pointer to the actual <type>SdrObject</type> object.
384 SdrObjectWeakRef mxObject
;
386 /// Number of the actual SdrText from the current <type>SdrObject</type>
389 /// The index of a page where the object is located on.
390 sal_Int32 mnPageIndex
;
391 /// Page kind of the view.
393 /// Edit mode of the view.
398 } } // end of namespace ::sd::outliner
401 #endif // _SD_OUTLINER_ITERATOR_HXX