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>

Inheritance diagram for Base::SequencerBase:

List of all members.

Public Member Functions
virtual bool	isBlocking () const
	Returns true if the running sequencer is blocking any user input.
bool	isLocked () const
	Returns true if the sequencer was locked, false otherwise.
bool	isRunning () const
	Returns true if the sequencer is running, otherwise returns false.
bool	setLocked (bool bLock)
	If bLock is true then the sequencer gets locked.
bool	wasCanceled () const
	Returns true if the pending operation was canceled.
Static Public Member Functions
static SequencerBase &	Instance ()
	Returns the last created sequencer instance.
Protected Member Functions
bool	next (bool canAbort=false)
	Performs the next step and returns true if the operation is not yet finished.
virtual void	nextStep (bool canAbort)
	This method can be reimplemented in sub-classes to give the user a feedback when the next is performed.
size_t	numberOfSteps () const
	Returns the number of steps.
virtual void	pause ()
	Breaks the sequencer if needed.
int	progressInPercent () const
	Returns the current state of progress in percent.
void	rejectCancel ()
	If you tried to cancel but then decided to continue the operation.
virtual void	resetData ()
	Resets internal data.
virtual void	resume ()
	Continues with progress.
	SequencerBase ()
	construction
virtual void	setProgress (size_t)
	Sets the progress indicator to a certain position.
virtual void	setText (const char *pszTxt)
	Sets a text what the pending operation is doing.
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.
virtual void	startStep ()
	This method can be reimplemented in sub-classes to give the user a feedback when a new sequence starts.
bool	stop ()
	Stops the sequencer if all operations are finished.
void	tryToCancel ()
	Try to cancel the pending operation(s).
virtual	~SequencerBase ()
	Destruction.
Protected Attributes
size_t	nProgress
	Stores the current amount of progress.
size_t	nTotalSteps
	Stores the total number of steps.
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 numer 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

Definition at line 115 of file Sequencer.h.

Constructor & Destructor Documentation

SequencerBase::SequencerBase ( ) [protected]

construction

Definition at line 83 of file Sequencer.cpp.

References Base::SequencerP::appendInstance().

SequencerBase::~SequencerBase ( ) [protected, virtual]

Destruction.

Definition at line 89 of file Sequencer.cpp.

References Base::SequencerP::removeInstance().

Member Function Documentation

SequencerBase & SequencerBase::Instance ( void ) [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

Definition at line 73 of file Sequencer.cpp.

References Base::SequencerP::_instances, and 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().

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::Sequencer, and Gui::SequencerDialog.

Definition at line 161 of file Sequencer.cpp.

bool SequencerBase::isLocked ( ) const

Returns true if the sequencer was locked, false otherwise.

Definition at line 174 of file Sequencer.cpp.

References Base::SequencerP::mutex.

bool SequencerBase::isRunning ( ) const

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

Definition at line 180 of file Sequencer.cpp.

References Base::SequencerP::_topLauncher, and Base::SequencerP::mutex.

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

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.

Definition at line 121 of file Sequencer.cpp.

References SketcherExample::f, Py::int, nextStep(), nProgress, and nTotalSteps.

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

void SequencerBase::nextStep ( bool canAbort ) [protected, virtual]

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::Sequencer, and Gui::SequencerDialog.

Definition at line 139 of file Sequencer.cpp.

Referenced by next().

size_t SequencerBase::numberOfSteps ( ) const [protected]

Returns the number of steps.

Definition at line 112 of file Sequencer.cpp.

References nTotalSteps.

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

void SequencerBase::pause ( ) [protected, virtual]

Breaks the sequencer if needed.

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