Base::SequencerBase Class Reference

This class gives the user an indication of the progress of an operation and it is used to reassure him that the application is still running. More...

#include <Sequencer.h>

Public Member Functions
virtual void	checkAbort ()
	Check if the operation is aborted by user. More...
virtual bool	isBlocking () const
	Returns true if the running sequencer is blocking any user input. More...
bool	isLocked () const
	Returns true if the sequencer was locked, false otherwise. More...
bool	isRunning () const
	Returns true if the sequencer is running, otherwise returns false. More...
bool	setLocked (bool bLock)
	If bLock is true then the sequencer gets locked. More...
bool	wasCanceled () const
	Returns true if the pending operation was canceled. More...

Static Public Member Functions
static SequencerBase &	Instance ()
	Returns the last created sequencer instance. More...

Protected Member Functions
bool	next (bool canAbort=false)
	Performs the next step and returns true if the operation is not yet finished. More...
virtual void	nextStep (bool canAbort)
	This method can be reimplemented in sub-classes to give the user a feedback when the next is performed. More...
size_t	numberOfSteps () const
	Returns the number of steps. More...
SequencerBase &	operator= (const SequencerBase &)=default
virtual void	pause ()
	Breaks the sequencer if needed. More...
int	progressInPercent () const
	Returns the current state of progress in percent. More...
void	rejectCancel ()
	If you tried to cancel but then decided to continue the operation. More...
virtual void	resetData ()
	Resets internal data. More...
virtual void	resume ()
	Continues with progress. More...
	SequencerBase ()
	construction More...
	SequencerBase (const SequencerBase &)=default
virtual void	setProgress (size_t)
	Sets the progress indicator to a certain position. More...
virtual void	setText (const char *pszTxt)
	Sets a text what the pending operation is doing. More...
bool	start (const char *pszStr, size_t steps)
	Starts a new operation, returns false if there is already a pending operation, otherwise it returns true. More...
virtual void	startStep ()
	This method can be reimplemented in sub-classes to give the user a feedback when a new sequence starts. More...
bool	stop ()
	Stops the sequencer if all operations are finished. More...
void	tryToCancel ()
	Try to cancel the pending operation(s). More...
virtual	~SequencerBase ()
	Destruction. More...

Protected Attributes
size_t	nProgress
	Stores the current amount of progress. More...
size_t	nTotalSteps
	Stores the total number of steps. More...

Friends
class	SequencerLauncher

Detailed Description

This class gives the user an indication of the progress of an operation and it is used to reassure him that the application is still running.

Here are some code snippets of how to use the sequencer:

#include <Base/Sequencer.h>
 
//first example
Base::SequencerLauncher seq("my text", 10)
for (int i=0; i<10; i++)
{
  // do something
  seq.next ();
}
 
//second example
Base::SequencerLauncher seq("my text", 10)
do
{
  // do something
}
while (seq.next());

The implementation of this class also supports several nested instances at a time. But note, that only the first instance has an effect. Any further sequencer instance doesn't influence the total number of iteration steps. This is simply because it's impossible to get the exact number of iteration steps for nested instances and thus we have either too few steps estimated then the sequencer may indicate 100% but the algorithm still running or we have too many steps estimated so that the an algorithm may stop long before the sequencer reaches 100%.

try {
  //start the first operation
  Base::SequencerLauncher seq1("my text", 10)
  for (int i=0; i<10, i++)
  {
    // do something
 
    // start the second operation while the first one is still running
    Base::SequencerLauncher seq2("another text", 10);
    for (int j=0; j<10; j++)
    {
      // do something different
      seq2.next ();
    }
 
    seq1.next ( true ); // allow to cancel
  }
}
catch(const Base::AbortException&){
  // cleanup your data if needed
}

Note

If using the sequencer with SequencerLauncher.next(true) then you must take into account that the exception AbortException could be thrown, e.g. in case the ESC button was pressed. So in this case it's always a good idea to use the sequencer within a try-catch block.

Instances of SequencerLauncher should always be created on the stack. This is because if an exception somewhere is thrown the destructor is auto- matically called to clean-up internal data.

It's not supported to create an instance of SequencerBase or a sub-class in another thread than the main thread. But you can create SequencerLauncher instances in other threads.

Author

Werner Mayer

Constructor & Destructor Documentation

SequencerBase() [1/2]

SequencerBase::SequencerBase ( )

protected

construction

References Base::SequencerP::appendInstance().

SequencerBase() [2/2]

Base::SequencerBase::SequencerBase ( const SequencerBase &  )

protecteddefault

~SequencerBase()

SequencerBase::~SequencerBase ( )

protectedvirtual

Destruction.

References Base::SequencerP::removeInstance().

Member Function Documentation

checkAbort()

virtual void Base::SequencerBase::checkAbort ( )

virtual

Check if the operation is aborted by user.

Reimplemented in Gui::SequencerBar.

Instance()

SequencerBase & SequencerBase::Instance ( )

static

Returns the last created sequencer instance.

If you create an instance of a class inheriting SequencerBase this object is retrieved instead.

This mechanism is very useful to have an own sequencer for each layer of FreeCAD. For example, if FreeCAD is running in server mode you have/need no GUI layer and therewith no (graphical) progress bar; in this case ConsoleSequencer is taken. But in cases FreeCAD is running with GUI the Gui::ProgressBar is taken instead.

See also

Sequencer

References Base::SequencerP::getInstance().

Referenced by Base::SequencerLauncher::next(), Base::SequencerLauncher::numberOfSteps(), Base::Sequencer(), Base::SequencerLauncher::SequencerLauncher(), Base::SequencerLauncher::setProgress(), Base::SequencerLauncher::setText(), Base::SequencerLauncher::wasCanceled(), and Base::SequencerLauncher::~SequencerLauncher().

isBlocking()

bool SequencerBase::isBlocking ( ) const

virtual

Returns true if the running sequencer is blocking any user input.

This might be only of interest of the GUI where the progress bar or dialog is used from a thread. If started from a thread this method should return false, otherwise true. The default implementation always returns true.

Reimplemented in Gui::SequencerDialog, and Gui::SequencerBar.

Referenced by Gui::ViewerEventFilter::eventFilter().

isLocked()

bool SequencerBase::isLocked

(

)

const

Returns true if the sequencer was locked, false otherwise.

References Base::SequencerP::mutex.

isRunning()

bool SequencerBase::isRunning

(

)

const

Returns true if the sequencer is running, otherwise returns false.

References Base::SequencerP::mutex.

Referenced by Gui::ProgressBar::delayedShow(), Gui::ProgressBar::eventFilter(), Gui::ViewerEventFilter::eventFilter(), and addonmanager_workers.InstallWorkbenchWorker::update_status().

next()

bool SequencerBase::next ( bool  canAbort = false )

protected

Performs the next step and returns true if the operation is not yet finished.

But note, when 0 was passed to start() as the number of total steps this method always returns false.

In this method nextStep() gets invoked that can be reimplemented in sub-classes. If canAbort is true then the operations can be aborted, otherwise (the default) the operation cannot be aborted. In case it gets aborted an exception AbortException is thrown.

References nextStep(), nProgress, and nTotalSteps.

Referenced by Import::FeatureImportIges::Execute(), Import::FeatureImportStep::Execute(), and Base::SequencerLauncher::next().

nextStep()

void SequencerBase::nextStep ( bool  canAbort )

protectedvirtual

This method can be reimplemented in sub-classes to give the user a feedback when the next is performed.

The default implementation does nothing. If canAbort is true then the pending operation can aborted, otherwise not. Depending on the re-implementation this method can throw an AbortException if canAbort is true.

Reimplemented in Base::ConsoleSequencer, Gui::SequencerDialog, and Gui::SequencerBar.

Referenced by next().

numberOfSteps()

size_t SequencerBase::numberOfSteps ( ) const

protected

Returns the number of steps.

References nTotalSteps.

Referenced by Base::SequencerLauncher::numberOfSteps().

operator=()

SequencerBase & Base::SequencerBase::operator= ( const SequencerBase &  )

protecteddefault

pause()

void SequencerBase::pause ( )

protectedvirtual

Breaks the sequencer if needed.

The default implementation does nothing. Every pause() must eventually be followed by a corresponding resume().

See also

Gui::ProgressBar.

Reimplemented in Gui::SequencerDialog, and Gui::SequencerBar.

progressInPercent()

int SequencerBase::progressInPercent ( ) const

protected

Returns the current state of progress in percent.

Referenced by Base::ConsoleSequencer::nextStep().

rejectCancel()

void SequencerBase::rejectCancel ( )

protected

If you tried to cancel but then decided to continue the operation.

E.g. in Gui::ProgressBar a dialog appears asking if you really want to cancel. If you decide to continue this method must be called.

Referenced by Gui::SequencerBar::checkAbort(), Gui::SequencerDialog::nextStep(), and Gui::SequencerBar::nextStep().

resetData()

void SequencerBase::resetData ( )

protectedvirtual

Resets internal data.

If you want to reimplement this method, it is very important to call it in the re-implemented method.

Reimplemented in Gui::SequencerDialog, and Gui::SequencerBar.

Referenced by stop().

resume()

void SequencerBase::resume ( )

protectedvirtual

Continues with progress.

The default implementation does nothing.

See also

pause(),

Gui::ProgressBar.

Reimplemented in Gui::SequencerDialog, and Gui::SequencerBar.

setLocked()

bool SequencerBase::setLocked

(

bool

bLock

)

If bLock is true then the sequencer gets locked.

startStep() and nextStep() don't get invoked any more until the sequencer gets unlocked again. This method returns the previous lock state.

References Base::SequencerP::mutex.

Referenced by MeshGui::ViewProviderMesh::partMeshCallback(), and MeshGui::ViewProviderMesh::segmMeshCallback().

setProgress()

void SequencerBase::setProgress ( size_t  )

protectedvirtual

Sets the progress indicator to a certain position.

Reimplemented in Gui::SequencerDialog, and Gui::SequencerBar.

Referenced by Base::SequencerLauncher::setProgress().

setText()

void SequencerBase::setText ( const char *  pszTxt )

protectedvirtual

Sets a text what the pending operation is doing.

The default implementation does nothing.

Reimplemented in Gui::SequencerDialog, and Gui::SequencerBar.

Referenced by Base::SequencerLauncher::setText(), and start().

start()

bool SequencerBase::start ( const char *  pszStr, size_t  steps  )

protected

Starts a new operation, returns false if there is already a pending operation, otherwise it returns true.

In this method startStep() gets invoked that can be reimplemented in sub-classes.

References nProgress, nTotalSteps, setText(), and startStep().

Referenced by Mod.PartDesign.WizardShaft.SegmentFunction.SegmentFunctionSegment::asString(), Mod.PartDesign.WizardShaft.SegmentFunction.SegmentFunctionSegment::clone(), Import::FeatureImportIges::Execute(), Import::FeatureImportStep::Execute(), Mod.PartDesign.WizardShaft.SegmentFunction.SegmentFunctionSegment::hasStart(), Mod.PartDesign.WizardShaft.SegmentFunction.SegmentFunctionSegment::negated(), Base::SequencerLauncher::SequencerLauncher(), and Mod.PartDesign.WizardShaft.SegmentFunction.SegmentFunctionSegment::value().

startStep()

void SequencerBase::startStep ( )

protectedvirtual

This method can be reimplemented in sub-classes to give the user a feedback when a new sequence starts.

The default implementation does nothing.

Reimplemented in Base::ConsoleSequencer, Gui::SequencerDialog, and Gui::SequencerBar.

Referenced by start().

stop()

bool SequencerBase::stop ( )

protected

Stops the sequencer if all operations are finished.

It returns false if there are still pending operations, otherwise it returns true.

References resetData().

Referenced by ArchPanel.NestTaskPanel::accept(), Import::FeatureImportIges::Execute(), Import::FeatureImportStep::Execute(), ArchPanel.NestTaskPanel::reject(), and Base::SequencerLauncher::~SequencerLauncher().

tryToCancel()

void SequencerBase::tryToCancel ( )

protected

Try to cancel the pending operation(s).

E.g. Gui::ProgressBar calls this method after the ESC button was pressed.

Referenced by Gui::ProgressBar::eventFilter(), and Gui::ProgressDialog::onCancel().

wasCanceled()

bool SequencerBase::wasCanceled

(

)

const

Returns true if the pending operation was canceled.

References Base::SequencerP::mutex.

Referenced by Gui::SequencerBar::checkAbort(), Gui::ProgressBar::delayedShow(), Gui::SequencerDialog::nextStep(), Gui::SequencerBar::nextStep(), and Base::SequencerLauncher::wasCanceled().

Friends And Related Function Documentation

SequencerLauncher

friend class SequencerLauncher

friend

Member Data Documentation

nProgress

size_t Base::SequencerBase::nProgress

protected

Stores the current amount of progress.

Referenced by next(), Gui::SequencerDialog::nextStep(), Gui::SequencerBar::nextStep(), and start().

nTotalSteps

size_t Base::SequencerBase::nTotalSteps

protected

Stores the total number of steps.

Referenced by next(), Base::ConsoleSequencer::nextStep(), numberOfSteps(), start(), Gui::SequencerDialog::startStep(), and Gui::SequencerBar::startStep().

---

The documentation for this class was generated from the following files:

• FreeCAD/src/Base/Sequencer.h
• FreeCAD/src/Base/Sequencer.cpp