sc/source/filter/inc/fprogressbar.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: fprogressbar.hxx,v $
  10  * $Revision: 1.8.32.2 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  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.
  17  *
  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).
  23  *
  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.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef SC_FPROGRESSBAR_HXX
  32 #define SC_FPROGRESSBAR_HXX
  33
  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 : ScfNoCopy
 117 {
 118 public:
 119     explicit            ScfProgressBar( SfxObjectShell* pDocShell, const String& rText );
 120     explicit            ScfProgressBar( SfxObjectShell* pDocShell, USHORT 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     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 ) const;
 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 ScfDelList< 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 class ScfSimpleProgressBar
 202 {
 203 public:
 204     explicit            ScfSimpleProgressBar( sal_Size nSize, SfxObjectShell* pDocShell, const String& rText );
 205     explicit            ScfSimpleProgressBar( sal_Size nSize, SfxObjectShell* pDocShell, USHORT nResId );
 206
 207     /** Set progress bar to the specified position. */
 208     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 class ScfStreamProgressBar
 224 {
 225 public:
 226 //UNUSED2008-05  explicit            ScfStreamProgressBar( SvStream& rStrm, SfxObjectShell* pDocShell, const String& rText );
 227     explicit            ScfStreamProgressBar( SvStream& rStrm, SfxObjectShell* pDocShell, USHORT nResId = STR_LOAD_DOC );
 228
 229     /** Sets the progress bar to the current stream position. */
 230     void                Progress();
 231
 232 private:
 233     /** Initializes and starts the progress bar. */
 234     void                Init( SfxObjectShell* pDocShell, const String& rText );
 235
 236 private:
 237     typedef ::std::auto_ptr< ScfSimpleProgressBar > ScfSimpleProgressBarPtr;
 238
 239     ScfSimpleProgressBarPtr mxProgress; /// The used progress bar.
 240     SvStream&           mrStrm;         /// The used stream.
 241 };
 242
 243 // ============================================================================
 244
 245 #endif
 246