Branch data Line data Source code
1 : : /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 : : /*************************************************************************
3 : : *
4 : : * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
5 : : *
6 : : * Copyright 2000, 2010 Oracle and/or its affiliates.
7 : : *
8 : : * OpenOffice.org - a multi-platform office productivity suite
9 : : *
10 : : * This file is part of OpenOffice.org.
11 : : *
12 : : * OpenOffice.org is free software: you can redistribute it and/or modify
13 : : * it under the terms of the GNU Lesser General Public License version 3
14 : : * only, as published by the Free Software Foundation.
15 : : *
16 : : * OpenOffice.org is distributed in the hope that it will be useful,
17 : : * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 : : * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 : : * GNU Lesser General Public License version 3 for more details
20 : : * (a copy is included in the LICENSE file that accompanied this code).
21 : : *
22 : : * You should have received a copy of the GNU Lesser General Public License
23 : : * version 3 along with OpenOffice.org. If not, see
24 : : * <http://www.openoffice.org/license.html>
25 : : * for a copy of the LGPLv3 License.
26 : : *
27 : : ************************************************************************/
28 : :
29 : : #ifndef SC_FPROGRESSBAR_HXX
30 : : #define SC_FPROGRESSBAR_HXX
31 : :
32 : : #include <boost/noncopyable.hpp>
33 : : #include <boost/ptr_container/ptr_vector.hpp>
34 : : #include "globstr.hrc"
35 : : #include "ftools.hxx"
36 : : #include "scdllapi.h"
37 : :
38 : : class SfxObjectShell;
39 : : class ScProgress;
40 : :
41 : : // ============================================================================
42 : :
43 : : const sal_Int32 SCF_INV_SEGMENT = -1;
44 : :
45 : : // ============================================================================
46 : :
47 : : /** Progress bar for complex progress representation.
48 : :
49 : : The progress bar contains one or more segments, each with customable
50 : : size. Each segment is represented by a unique identifier. While showing the
51 : : progress bar, several segments can be started simultaneously. The progress
52 : : bar displays the sum of all started segments on screen.
53 : :
54 : : It is possible to create a full featured ScfProgressBar object from
55 : : any segment. This sub progress bar works only on that parent segment, with
56 : : the effect, that if the sub progress bar reaches 100%, the parent segment is
57 : : filled completely.
58 : :
59 : : After adding segments, the progress bar has to be activated. In this step the
60 : : total size of all segments is calculated. Therefore it is not possible to add
61 : : more segments from here.
62 : :
63 : : If a sub progress bar is created from a segment, and the main progress bar
64 : : has been started (but not the sub progress bar), it is still possible to add
65 : : segments to the sub progress bar. It is not allowed to get the sub progress bar
66 : : of a started segment. And it is not allowed to modify the segment containing
67 : : a sub progress bar directly.
68 : :
69 : : Following a few code examples, how to use the progress bar.
70 : :
71 : : Example 1: Simple progress bar (see also ScfSimpleProgressBar below).
72 : :
73 : : ScfProgressBar aProgress( ... );
74 : : sal_Int32 nSeg = aProgress.AddSegment( 50 ); // segment with 50 steps (1 step = 2%)
75 : :
76 : : aProgress.ActivateSegment( nSeg ); // start segment nSeg
77 : : aProgress.Progress(); // 0->1; display: 2%
78 : : aProgress.ProgressAbs( 9 ); // 1->9; display: 18%
79 : :
80 : : Example 2: Progress bar with 2 segments.
81 : :
82 : : ScfProgressBar aProgress( ... );
83 : : sal_Int32 nSeg1 = aProgress.AddSegment( 70 ); // segment with 70 steps
84 : : sal_Int32 nSeg2 = aProgress.AddSegment( 30 ); // segment with 30 steps
85 : : // both segments: 100 steps (1 step = 1%)
86 : :
87 : : aProgress.ActivateSegment( nSeg1 ); // start first segment
88 : : aProgress.Progress(); // 0->1, display: 1%
89 : : aProgress.Progress( 2 ); // 1->3, display: 3%
90 : : aProgress.ActivateSegment( nSeg2 ); // start second segment
91 : : aProgress.Progress( 5 ); // 0->5, display: 8% (5+3 steps)
92 : : aProgress.ActivateSegment( nSeg1 ); // continue with first segment
93 : : aProgress.Progress(); // 3->4, display: 9% (5+4 steps)
94 : :
95 : : Example 3: Progress bar with 2 segments, one contains a sub progress bar.
96 : :
97 : : ScfProgressBar aProgress( ... );
98 : : sal_Int32 nSeg1 = aProgress.AddSegment( 75 ); // segment with 75 steps
99 : : sal_Int32 nSeg2 = aProgress.AddSegment( 25 ); // segment with 25 steps
100 : : // both segments: 100 steps (1 step = 1%)
101 : :
102 : : aProgress.ActivateSegment( nSeg1 ); // start first segment
103 : : aProgress.Progress(); // 0->1, display: 1%
104 : :
105 : : ScfProgressBar& rSubProgress = aProgress.GetSegmentProgressBar( nSeg2 );
106 : : // sub progress bar from second segment
107 : : sal_Int32 nSubSeg = rSubProgress.AddSegment( 5 ); // 5 steps, mapped to second segment
108 : : // => 1 step = 5 steps in parent = 5%
109 : :
110 : : rSubProgress.ActivateSegment( nSubSeg ); // start the segment (auto activate parent segment)
111 : : rSubProgress.Progress(); // 0->1 (0->5 in parent); display: 6% (1+5)
112 : :
113 : : // not allowed (second segment active): aProgress.Progress();
114 : : // not allowed (first segment not empty): aProgress.GetSegmentProgressBar( nSeg1 );
115 : : */
116 : : class ScfProgressBar : private boost::noncopyable
117 : : {
118 : : public:
119 : : explicit ScfProgressBar( SfxObjectShell* pDocShell, const String& rText );
120 : : explicit ScfProgressBar( SfxObjectShell* pDocShell, sal_uInt16 nResId );
121 : : virtual ~ScfProgressBar();
122 : :
123 : : /** Adds a new segment to the progress bar.
124 : : @return the identifier of the segment. */
125 : : sal_Int32 AddSegment( sal_Size nSize );
126 : : /** Returns a complete progress bar for the specified segment.
127 : : @descr The progress bar can be used to create sub segments inside of the
128 : : segment. Do not delete it (done by root progress bar)!
129 : : @return A reference to an ScfProgressBar connected to the segment. */
130 : : ScfProgressBar& GetSegmentProgressBar( sal_Int32 nSegment );
131 : :
132 : : /** Returns true, if any progress segment has been started. */
133 : : inline bool IsStarted() const { return mbInProgress; }
134 : : /** Returns true, if the current progress segment is already full. */
135 : : bool IsFull() const;
136 : :
137 : : /** Starts the progress bar or activates another segment. */
138 : : void ActivateSegment( sal_Int32 nSegment );
139 : : /** Starts the progress bar (with first segment). */
140 : 17 : inline void Activate() { ActivateSegment( 0 ); }
141 : : /** Set current segment to the specified absolute position. */
142 : : void ProgressAbs( sal_Size nPos );
143 : : /** Increase current segment by the passed value. */
144 : : void Progress( sal_Size nDelta = 1 );
145 : :
146 : : private:
147 : : struct ScfProgressSegment;
148 : :
149 : : /** Used to create sub progress bars. */
150 : : explicit ScfProgressBar(
151 : : ScfProgressBar& rParProgress,
152 : : ScfProgressSegment* pParSegment );
153 : :
154 : : /** Initializes all members on construction. */
155 : : void Init( SfxObjectShell* pDocShell );
156 : :
157 : : /** Returns the segment specified by list index. */
158 : : ScfProgressSegment* GetSegment( sal_Int32 nSegment );
159 : : /** Activates progress bar and sets current segment. */
160 : : void SetCurrSegment( ScfProgressSegment* pSegment );
161 : : /** Increases mnTotalPos and calls the system progress bar. */
162 : : void IncreaseProgressBar( sal_Size nDelta );
163 : :
164 : : private:
165 : : /** Contains all data of a segment of the progress bar. */
166 : : struct ScfProgressSegment
167 : : {
168 : : typedef ::std::auto_ptr< ScfProgressBar > ScfProgressBarPtr;
169 : :
170 : : ScfProgressBarPtr mxProgress; /// Pointer to sub progress bar for this segment.
171 : : sal_Size mnSize; /// Size of this segment.
172 : : sal_Size mnPos; /// Current position of this segment.
173 : :
174 : : explicit ScfProgressSegment( sal_Size nSize );
175 : : ~ScfProgressSegment();
176 : : };
177 : :
178 : : typedef ::std::auto_ptr< ScProgress > ScProgressPtr;
179 : : typedef boost::ptr_vector< ScfProgressSegment > ScfSegmentList;
180 : :
181 : : ScfSegmentList maSegments; /// List of progress segments.
182 : : String maText; /// UI string for system progress.
183 : :
184 : : ScProgressPtr mxSysProgress; /// System progress bar.
185 : : SfxObjectShell* mpDocShell; /// The document shell for the progress bar.
186 : : ScfProgressBar* mpParentProgress; /// Parent progress bar, if this is a segment progress bar.
187 : : ScfProgressSegment* mpParentSegment; /// Parent segment, if this is a segment progress bar.
188 : : ScfProgressSegment* mpCurrSegment; /// Current segment for progress.
189 : :
190 : : sal_Size mnTotalSize; /// Total size of all segments.
191 : : sal_Size mnTotalPos; /// Sum of positions of all segments.
192 : : sal_Size mnUnitSize; /// Size between two calls of system progress.
193 : : sal_Size mnNextUnitPos; /// Limit for next system progress call.
194 : : sal_Size mnSysProgressScale; /// Additionally scaling factor for system progress.
195 : : bool mbInProgress; /// true = progress bar started.
196 : : };
197 : :
198 : : // ============================================================================
199 : :
200 : : /** A simplified progress bar with only one segment. */
201 : 55 : class ScfSimpleProgressBar
202 : : {
203 : : public:
204 : : explicit ScfSimpleProgressBar( sal_Size nSize, SfxObjectShell* pDocShell, const String& rText );
205 : : explicit ScfSimpleProgressBar( sal_Size nSize, SfxObjectShell* pDocShell, sal_uInt16 nResId );
206 : :
207 : : /** Set progress bar to the specified position. */
208 : 22567 : inline void ProgressAbs( sal_Size nPos ) { maProgress.ProgressAbs( nPos ); }
209 : : /** Increase progress bar by 1. */
210 : : inline void Progress( sal_Size nDelta = 1 ) { maProgress.Progress( nDelta ); }
211 : :
212 : : private:
213 : : /** Initializes and starts the progress bar. */
214 : : void Init( sal_Size nSize );
215 : :
216 : : private:
217 : : ScfProgressBar maProgress; /// The used progress bar.
218 : : };
219 : :
220 : : // ============================================================================
221 : :
222 : : /** A simplified progress bar based on the stream position of an existing stream. */
223 : 0 : class ScfStreamProgressBar
224 : : {
225 : : public:
226 : : explicit ScfStreamProgressBar( SvStream& rStrm, SfxObjectShell* pDocShell, sal_uInt16 nResId = STR_LOAD_DOC );
227 : :
228 : : /** Sets the progress bar to the current stream position. */
229 : : void Progress();
230 : :
231 : : private:
232 : : /** Initializes and starts the progress bar. */
233 : : void Init( SfxObjectShell* pDocShell, const String& rText );
234 : :
235 : : private:
236 : : typedef ::std::auto_ptr< ScfSimpleProgressBar > ScfSimpleProgressBarPtr;
237 : :
238 : : ScfSimpleProgressBarPtr mxProgress; /// The used progress bar.
239 : : SvStream& mrStrm; /// The used stream.
240 : : };
241 : :
242 : : // ============================================================================
243 : :
244 : : #endif
245 : :
246 : : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|
