home *** CD-ROM | disk | FTP | other *** search
/ Clickx 115 / Clickx 115.iso / software / tools / windows / tails-i386-0.16.iso / live / filesystem.squashfs / usr / include / scribus-ng / deferredtask.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-03-22  |  5.1 KB  |  129 lines

  1. /*
  2. For general Scribus (>=1.3.2) copyright and licensing information please refer
  3. to the COPYING file provided with the program. Following this notice may exist
  4. a copyright and/or license notice that predates the release of Scribus 1.3.2
  5. for which a new license (GPL+exception) is in place.
  6. */
  7. #ifndef _DEFERREDTASK_H
  8. #define _DEFERREDTASK_H
  9.  
  10. #include <QObject>
  11. #include <QString>
  12. #include "scribusapi.h"
  13.  
  14. class QTimer;
  15.  
  16. /*! \brief DeferredTask is an abstraction of a generally long-running operation
  17. that is done in small steps under the control of the event loop. It
  18. is an abstract class that provides a common interface for such tasks,
  19. but cannot be used directly.
  20.  
  21. To use it, subclass it and add the private methods and members you need
  22. to keep track of your task. FileSearch uses this interface and might
  23. be worth looking at. You can change the constructor arguments around
  24. as much as you like, but should maintain the rest of the interface.
  25.  
  26. When you instantiate a DeferredTask subclass, it should do any general setup
  27. it requires but not begin processing. The start() slot will be called to
  28. trigger the beginning of processing. next() will then be called repeatedly
  29. by an idle timer to do small chunks of processing work. When the class
  30. emits finished() or aborted(bool), the timer will stop and next() will not be
  31. called again.
  32.  
  33. A DeferredTask is single use. It will be automatically deleted if its parent
  34. is deleted (and it hasn't yet been deleted). Otherwise, delete it when
  35. you're done with it. You should not delete it without cancelling it first.
  36. */
  37. class SCRIBUS_API DeferredTask : public QObject
  38. {
  39.     Q_OBJECT
  40.  
  41. public:
  42.     /*! \brief If you override the destructor, call DeferredTask::cleanup() at the
  43.     end of your dtor. */
  44.     virtual ~DeferredTask();
  45.  
  46.     /*! \brief Returns true iff processing has finished. Note that this will return false
  47.     both while processing, and before start() has been called. */
  48.     bool isFinished() const;
  49.  
  50.     /*! \brief Return a human-readable version of the last error message. Unless
  51.     overridden, returns the value of m_lastError. Value is undefined
  52.     until either finished() or aborted(bool) have been emitted. */
  53.     virtual const QString& lastError() const;
  54.  
  55. public slots:
  56.  
  57.     /*! \brief Starts the timer and begins processing. If you override this you must
  58.     call DeferredTask::start() at the end of your start() implementation.
  59.     If something goes wrong, emit aborted(); */
  60.     virtual void start();
  61.  
  62.     /*! \brief Run continuously without returning control to the event loop, until
  63.     either aborted(bool) or finished() are emitted. Note that EVENTS ARE NOT
  64.     PROCESSED, including deleteLater() and posted events. It is not
  65.     recommended that you use this method. */
  66.     void runUntilFinished();
  67.  
  68.     /*! \brief Abort the search and emit aborted(true). This is treated as an abort by
  69.     the user. If you reimplement this you must call DeferredTask::cancel()
  70.     at the end of your implementation. Do not emit aborted(bool) yourself
  71.     from your cancel() implementation, let DeferredTask::cancel() do that. */
  72.     virtual void cancel();
  73.  
  74. signals:
  75.     /*! \brief Emitted if the processing work was aborted before completion. The signal
  76.     argument is true if processing was aborted by direct or indirect user action,
  77.     and false if it was aborted for any other reason (such as an internal error). */
  78.     void aborted(bool);
  79.  
  80.     /*! \brief Emitted when processing is complete, from DeferredTask::done(). You can
  81.     also emit your own custom signal if you want to convey more information,
  82.     so long as you do so AFTER calling done(). */
  83.     void finished();
  84.  
  85.     /*! \brief Emitted to inform anybody interested of the approximate level of
  86.     progress made in the processing task. The argument is a positive integer
  87.     percentage from 0 to 100 inclusive. Subclasses are not required to emit
  88.     this signal, but it's a good idea if the user is likely to care about
  89.     what your class does. */
  90.     void progress(int);
  91.  
  92. protected slots:
  93.     /*! \brief Do the next small chunk of processing, then return. You must implement this method
  94.     to do whatever processing work you need to. It will be called repeatedly until it emits
  95.     either aborted(bool) or finished() to indicate that it's done. */
  96.     virtual void next() = 0;
  97.  
  98. protected:
  99.     /*! \brief You must provide a new, public, constructor. It should set up the class
  100.     but not begin processing. You must call DeferredTask::init() from your
  101.     ctor, preferably early on. */
  102.     DeferredTask(QObject* parent);
  103.  
  104.     //! \brief  Human readable, translated version of last error encountered.
  105.     QString m_lastError;
  106.  
  107.     //! \brief  Do some setup of the DeferredTask. Must be called from all subclass ctors.
  108.     void init();
  109.  
  110.     //! \brief  Do some cleanup before deletion. Must be called from all subclass dtors.
  111.     void cleanup();
  112.  
  113.     /*! \brief Indicate that processing has finished. You must call this before
  114.     emitting finished(), since it sets up some state that must happen before
  115.     any slots connected to finished() are called, and the ordering of slot
  116.     calls from a signal can not be guaranteed. */
  117.     void done();
  118.  
  119. private:
  120.     /*! \brief Status code indicating whether we're running, not yet started, failed,
  121.     etc. */
  122.     int m_status;
  123.  
  124.     //! \brief  The timer used to control next() calls.
  125.     QTimer* m_timer;
  126. };
  127.  
  128. #endif
  129.