Base::SequencerLauncher Class Reference

The SequencerLauncher class is provided for convenience. More...

#include <Sequencer.h>

Public Member Functions
bool	next (bool canAbort=false)
size_t	numberOfSteps () const
	SequencerLauncher (const char *pszStr, size_t steps)
void	setProgress (size_t)
void	setText (const char *pszTxt)
bool	wasCanceled () const
	~SequencerLauncher ()

Detailed Description

The SequencerLauncher class is provided for convenience.

It allows you to run an instance of the sequencer by instantiating an object of this class -- most suitable on the stack. So this mechanism can be used for try-catch-blocks to destroy the object automatically if the C++ exception mechanism cleans up the stack.

This class has been introduced to simplify the use with the sequencer. In the FreeCAD Gui layer there is a subclass of SequencerBase called ProgressBar that grabs the keyboard and filters most of the incoming events. If the programmer uses the API of SequencerBase directly to start an instance without due diligence with exceptions then a not handled exception could block the whole application -- the user has to kill the application then.

Below is an example of a not correctly used sequencer.

  #include <Base/Sequencer.h>

  void runOperation();

  void myTest()
  {
    try{
       runOperation();
    } catch(...) {
       // the programmer forgot to stop the sequencer here
       // Under circumstances the sequencer never gets stopped so the keyboard never gets ungrabbed and
       // all Gui events still gets filtered.
    }
  }

  void runOperation()
  {
    Base::Sequencer().start ("my text", 10);

    for (int i=0; i<10; i++)
    {
      // do something where an exception be thrown
      ...
      Base::Sequencer().next ();
    }

    Base::Sequencer().stop ();
  }

To avoid such problems the SequencerLauncher class can be used as follows:

  #include <Base/Sequencer.h>

  void runOperation();

  void myTest()
  {
    try{
       runOperation();
    } catch(...) {
       // the programmer forgot to halt the sequencer here
       // If SequencerLauncher leaves its scope the object gets destructed automatically and
       // stops the running sequencer.
    }
  }

  void runOperation()
  {
    // create an instance on the stack (not on any terms on the heap)
    SequencerLauncher seq("my text", 10);

    for (int i=0; i<10; i++)
    {
      // do something (e.g. here can be thrown an exception)
      ...
      seq.next ();
    }
  }