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