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