1
/***************************************************************************
2
* Copyright (c) 2004 Werner Mayer <werner.wm.mayer@gmx.de> *
4
* This file is part of the FreeCAD CAx development system. *
6
* This library is free software; you can redistribute it and/or *
7
* modify it under the terms of the GNU Library General Public *
8
* License as published by the Free Software Foundation; either *
9
* version 2 of the License, or (at your option) any later version. *
11
* This library is distributed in the hope that it will be useful, *
12
* but WITHOUT ANY WARRANTY; without even the implied warranty of *
13
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
14
* GNU Library General Public License for more details. *
16
* You should have received a copy of the GNU Library General Public *
17
* License along with this library; see the file COPYING.LIB. If not, *
18
* write to the Free Software Foundation, Inc., 59 Temple Place, *
19
* Suite 330, Boston, MA 02111-1307, USA *
21
***************************************************************************/
24
#ifndef BASE_SEQUENCER_H
25
#define BASE_SEQUENCER_H
29
#include "Exception.h"
35
class SequencerLauncher;
38
* \brief This class gives the user an indication of the progress of an operation and
39
* it is used to reassure him that the application is still running.
41
* Here are some code snippets of how to use the sequencer:
44
* #include <Base/Sequencer.h>
47
* Base::SequencerLauncher seq("my text", 10))
48
* for (int i=0; i<10; i++)
55
* Base::SequencerLauncher seq("my text", 10))
64
* The implementation of this class also supports several nested instances
65
* at a time. But note, that only the first instance has an effect. Any further
66
* sequencer instance doesn't influence the total numer of iteration steps. This
67
* is simply because it's impossible to get the exact number of iteration steps
68
* for nested instances and thus we have either too few steps estimated then the
69
* sequencer may indicate 100% but the algorithm still running or we have too many
70
* steps estimated so that the an algorithm may stop long before the sequencer
75
* //start the first operation
76
* Base::SequencerLauncher seq1("my text", 10)
77
* for (int i=0; i<10, i++)
81
* // start the second operation while the first one is still running
82
* Base::SequencerLauncher seq2("another text", 10);
83
* for (int j=0; j<10; j++)
85
* // do something different
89
* seq1.next ( true ); // allow to cancel
92
* catch(const Base::AbortException&){
93
* // cleanup your data if needed
98
* \note If using the sequencer with SequencerLauncher.next(\a true) then you must
99
* take into account that the exception \a AbortException could be thrown, e.g. in
100
* case the ESC button was pressed. So in this case it's always a good idea to use
101
* the sequencer within a try-catch block.
103
* \note Instances of SequencerLauncher should always be created on the stack.
104
* This is because if an exception somewhere is thrown the destructor is auto-
105
* matically called to clean-up internal data.
107
* \author Werner Mayer
109
class BaseExport SequencerBase
111
friend class SequencerLauncher;
115
* Starts a new operation, returns false if there is already a pending operation,
116
* otherwise it returns true.
117
* In this method startStep() gets invoked that can be reimplemented in sub-classes.
119
bool start(const char* pszStr, size_t steps);
121
* Performs the next step and returns true if the operation is not yet finished.
122
* But note, when 0 was passed to start() as the number of total steps this method
123
* always returns false.
125
* In this method nextStep() gets invoked that can be reimplemented in sub-classes.
126
* If \a canAbort is true then the operations can be aborted, otherwise (the default)
127
* the operation cannot be aborted. In case it gets aborted an exception AbortException
130
bool next(bool canAbort = false);
132
* Stops the sequencer if all operations are finished. It returns false if
133
* there are still pending operations, otherwise it returns true.
139
* Returns the last created sequencer instance.
140
* If you create an instance of a class inheriting SequencerBase
141
* this object is retrieved instead.
143
* This mechanism is very useful to have an own sequencer for each layer of FreeCAD.
144
* For example, if FreeCAD is running in server mode you have/need no GUI layer
145
* and therewith no (graphical) progress bar; in this case ConsoleSequencer is taken.
146
* But in cases FreeCAD is running with GUI the @ref Gui::ProgressBar is taken instead.
149
static SequencerBase& Instance();
151
* Breaks the sequencer if needed. The default implementation does nothing.
152
* Every pause() must eventually be followed by a corresponding @ref resume().
153
* @see Gui::ProgressBar.
155
virtual void pause();
157
* Continues with progress. The default implementation does nothing.
158
* @see pause(), @see Gui::ProgressBar.
160
virtual void resume();
162
* Returns true if the running sequencer is blocking any user input.
163
* This might be only of interest of the GUI where the progress bar or dialog
164
* is used from a thread. If started from a thread this method should return
165
* false, otherwise true. The default implementation always returns true.
167
virtual bool isBlocking() const;
168
/** If \a bLock is true then the sequencer gets locked. startStep() and nextStep()
169
* don't get invoked any more until the sequencer gets unlocked again.
170
* This method returns the previous lock state.
172
bool setLocked(bool bLock);
173
/** Returns true if the sequencer was locked, false otherwise. */
174
bool isLocked() const;
175
/** Returns true if the sequencer is running, otherwise returns false. */
176
bool isRunning() const;
178
* Returns true if the pending operation was canceled.
180
bool wasCanceled() const;
182
* Try to cancel the pending operation(s).
183
* E.g. @ref Gui::ProgressBar calls this method after the ESC button was pressed.
187
* If you tried to cancel but then decided to continue the operation.
188
* E.g. in @ref Gui::ProgressBar a dialog appears asking if you really want to
189
* cancel. If you decide to continue this method must be called.
192
/** Returns the current state of progress in percent. */
193
int progressInPercent() const;
199
virtual ~SequencerBase();
201
* Sets a text what the pending operation is doing. The default implementation
204
virtual void setText (const char* pszTxt);
206
* This method can be reimplemented in sub-classes to give the user a feedback
207
* when a new sequence starts. The default implementation does nothing.
209
virtual void startStep();
211
* This method can be reimplemented in sub-classes to give the user a feedback
212
* when the next is performed. The default implementation does nothing. If \a canAbort
213
* is true then the pending operation can aborted, otherwise not. Depending on the
214
* re-implementation this method can throw an AbortException if canAbort is true.
216
virtual void nextStep(bool canAbort);
218
* Resets internal data.
219
* If you want to reimplement this method, it is very important to call it �n
220
* the re-implemented method.
222
virtual void resetData();
225
size_t nProgress; /**< Stores the current amount of progress.*/
226
size_t nTotalSteps; /**< Stores the total number of steps */
229
/** Sets a global sequencer object.
230
* Access to the last registered object is performed by @see Sequencer().
232
void _setGlobalInstance ();
234
bool _bLocked; /**< Lock/unlock sequencer. */
235
bool _bCanceled; /**< Is set to true if the last pending operation was canceled */
236
int _nLastPercentage; /**< Progress in percent. */
237
static std::vector<SequencerBase*> _aclInstances; /**< A vector of all created instances */
238
static SequencerLauncher* _topLauncher; /**< The outermost launcher */
241
/** This special sequencer might be useful if you want to suppress any indication
242
* of the progress to the user.
244
class BaseExport EmptySequencer : public Base::SequencerBase
254
* \brief This class writes the progress to the console window.
256
class BaseExport ConsoleSequencer : public SequencerBase
262
~ConsoleSequencer ();
265
/** Starts the sequencer */
267
/** Writes the current progress to the console window. */
268
void nextStep(bool canAbort);
271
/** Puts text to the console window */
272
void setText (const char* pszTxt);
273
/** Resets the sequencer */
277
/** The SequencerLauncher class is provided for convenience. It allows you to run an instance of the
278
* sequencer by instanciating an object of this class -- most suitable on the stack. So this mechanism
279
* can be used for try-catch-blocks to destroy the object automatically if the C++ exception mechanism
280
* cleans up the stack.
282
* This class has been introduced to simplify the use with the sequencer. In the FreeCAD Gui layer there
283
* is a subclass of SequencerBase called ProgressBar that grabs the keyboard and filters most of the incoming
284
* events. If the programmer uses the API of SequencerBase directly to start an instance without due diligence
285
* with exceptions then a not handled exception could block the whole application -- the user has to kill the
288
* Below is an example of a not correctly used sequencer.
292
* #include <Base/Sequencer.h>
294
* void runOperation();
301
* // the programmer forgot to stop the sequencer here
302
* // Under circumstances the sequencer never gets stopped so the keyboard never gets ungrabbed and
303
* // all Gui events still gets filtered.
307
* void runOperation()
309
* Base::Sequencer().start ("my text", 10);
311
* for (int i=0; i<10; i++)
313
* // do something where an exception be thrown
315
* Base::Sequencer().next ();
318
* Base::Sequencer().stop ();
323
* To avoid such problems the SequencerLauncher class can be used as follows:
327
* #include <Base/Sequencer.h>
329
* void runOperation();
336
* // the programmer forgot to halt the sequencer here
337
* // If SequencerLauncher leaves its scope the object gets destructed automatically and
338
* // stops the running sequencer.
342
* void runOperation()
344
* // create an instance on the stack (not on any terms on the heap)
345
* SequencerLauncher seq("my text", 10);
347
* for (int i=0; i<10; i++)
349
* // do something (e.g. here can be thrown an exception)
357
* @author Werner Mayer
359
class BaseExport SequencerLauncher
362
SequencerLauncher(const char* pszStr, size_t steps);
363
~SequencerLauncher();
364
void setText (const char* pszTxt);
365
bool next(bool canAbort = false);
368
/** Access to the only SequencerBase instance */
369
inline SequencerBase& Sequencer ()
371
return SequencerBase::Instance();
376
#endif // BASE_SEQUENCER_H
added
removed
src/Base/Sequencer.h
