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