API cleanups

python/core/qgstaskmanager.sip

@@ -23,8 +23,8 @@ class QgsTask : QObject
     //! Task flags
     enum Flag
     {
-      CancelSupport, //!< Task can be cancelled
+      CanCancel, //!< Task can be cancelled
-      ProgressReport, //!< Task will report its progress
+      CanReportProgress, //!< Task will report its progress
       AllFlags, //!< Task supports all flags
     };
     typedef QFlags<QgsTask::Flag> Flags;
@@ -38,13 +38,6 @@ class QgsTask : QObject
     //! Returns the flags associated with the task.
     Flags flags() const;
 
-    //! Starts the task.
-    void start();
-
-    //! Notifies the task that it should terminate.
-    //! @see isCancelled()
-    void cancel();
-
     //! Returns true if the task can be cancelled.
     bool canCancel() const;
 
@@ -61,6 +54,30 @@ class QgsTask : QObject
     //! Returns the task's progress (between 0.0 and 100.0)
     double progress() const;
 
+  public slots:
+
+    //! Starts the task.
+    void start();
+
+    //! Notifies the task that it should terminate.
+    //! @see isCancelled()
+    void cancel();
+
+    //! Sets the task's current progress. If task reports the CanReportProgress flag then
+    //! the derived class should call this method whenever the task wants to update its
+    //! progress. Calling will automatically emit the progressChanged signal.
+    //! @param progress percent of progress, from 0.0 - 100.0
+    void setProgress( double progress );
+
+    //! Sets the task as completed. Should be called when the task is complete.
+    //! Calling will automatically emit the statusChanged and taskCompleted signals.
+    void completed();
+
+    //! Sets the task as stopped. Should be called whenever the task ends for any
+    //! reason other than successful completion.
+    //! Calling will automatically emit the statusChanged and taskStopped signals.
+    void stopped();
+
   signals:
 
     //! Will be emitted by task when its progress changes
@@ -91,31 +108,15 @@ class QgsTask : QObject
     //! stopped()//!
     void taskStopped();
 
-  public slots:
-
-    //! Sets the task's current progress. Should be called whenever the
-    //! task wants to update it's progress. Calling will automatically emit the progressChanged
-    //! signal.
-    //! @param progress percent of progress, from 0.0 - 100.0
-    void setProgress( double progress );
-
-    //! Sets the task as completed. Should be called when the task is complete.
-    //! Calling will automatically emit the statusChanged and taskCompleted signals.
-    void completed();
-
-    //! Sets the task as stopped. Should be called whenever the task ends for any
-    //! reason other than successful completion.
-    //! Calling will automatically emit the statusChanged and taskStopped signals.
-    void stopped();
-
   protected:
 
     //! Derived tasks must implement a run() method. This method will be called when the
     //! task commences (ie via calling start() ).
     virtual void run() = 0;
 
-    //! Will return true if task should terminate ASAP. Derived classes run() methods
+    //! Will return true if task should terminate ASAP. If the task reports the CanCancel
-    //! should periodically check this and terminate in a safe manner.
+    //! flag, then derived classes' run() methods should periodically check this and
+    //! terminate in a safe manner.
     bool isCancelled() const;
 
 };

src/core/qgstaskmanager.h

@@ -47,9 +47,9 @@ class CORE_EXPORT QgsTask : public QObject
     //! Task flags
     enum Flag
     {
-      CancelSupport = 1 << 1, //!< Task can be cancelled
+      CanCancel = 1 << 1, //!< Task can be cancelled
-      ProgressReport = 1 << 2, //!< Task will report its progress
+      CanReportProgress = 1 << 2, //!< Task will report its progress
-      AllFlags = CancelSupport | ProgressReport, //!< Task supports all flags
+      AllFlags = CanCancel | CanReportProgress, //!< Task supports all flags
     };
     Q_DECLARE_FLAGS( Flags, Flag )
 
@@ -62,15 +62,8 @@ class CORE_EXPORT QgsTask : public QObject
     //! Returns the flags associated with the task.
     Flags flags() const { return mFlags; }
 
-    //! Starts the task.
-    void start();
-
-    //! Notifies the task that it should terminate.
-    //! @see isCancelled()
-    void cancel();
-
     //! Returns true if the task can be cancelled.
-    bool canCancel() const { return mFlags & CancelSupport; }
+    bool canCancel() const { return mFlags & CanCancel; }
 
     //! Returns true if the task is active, ie it is not complete and has
     //! not been cancelled.
@@ -85,6 +78,30 @@ class CORE_EXPORT QgsTask : public QObject
     //! Returns the task's progress (between 0.0 and 100.0)
     double progress() const { return mProgress; }
 
+  public slots:
+
+    //! Starts the task.
+    void start();
+
+    //! Notifies the task that it should terminate.
+    //! @see isCancelled()
+    void cancel();
+
+    //! Sets the task's current progress. If task reports the CanReportProgress flag then
+    //! the derived class should call this method whenever the task wants to update its
+    //! progress. Calling will automatically emit the progressChanged signal.
+    //! @param progress percent of progress, from 0.0 - 100.0
+    void setProgress( double progress );
+
+    //! Sets the task as completed. Should be called when the task is complete.
+    //! Calling will automatically emit the statusChanged and taskCompleted signals.
+    void completed();
+
+    //! Sets the task as stopped. Should be called whenever the task ends for any
+    //! reason other than successful completion.
+    //! Calling will automatically emit the statusChanged and taskStopped signals.
+    void stopped();
+
   signals:
 
     //! Will be emitted by task when its progress changes
@@ -115,31 +132,15 @@ class CORE_EXPORT QgsTask : public QObject
     //! stopped()//!
     void taskStopped();
 
-  public slots:
-
-    //! Sets the task's current progress. Should be called whenever the
-    //! task wants to update it's progress. Calling will automatically emit the progressChanged
-    //! signal.
-    //! @param progress percent of progress, from 0.0 - 100.0
-    void setProgress( double progress );
-
-    //! Sets the task as completed. Should be called when the task is complete.
-    //! Calling will automatically emit the statusChanged and taskCompleted signals.
-    void completed();
-
-    //! Sets the task as stopped. Should be called whenever the task ends for any
-    //! reason other than successful completion.
-    //! Calling will automatically emit the statusChanged and taskStopped signals.
-    void stopped();
-
   protected:
 
     //! Derived tasks must implement a run() method. This method will be called when the
     //! task commences (ie via calling start() ).
     virtual void run() = 0;
 
-    //! Will return true if task should terminate ASAP. Derived classes run() methods
+    //! Will return true if task should terminate ASAP. If the task reports the CanCancel
-    //! should periodically check this and terminate in a safe manner.
+    //! flag, then derived classes' run() methods should periodically check this and
+    //! terminate in a safe manner.
     bool isCancelled() const { return mShouldTerminate; }
 
   private:

tests/src/core/testqgstaskmanager.cpp

@@ -116,7 +116,7 @@ void TestQgsTaskManager::task()
   QCOMPARE( task->description(), QString( "desc" ) );
   QVERIFY( !task->isActive() );
   QVERIFY( task->canCancel() );
-  QVERIFY( task->flags() & QgsTask::ProgressReport );
+  QVERIFY( task->flags() & QgsTask::CanReportProgress );
 
   QSignalSpy startedSpy( task.data(), SIGNAL( begun() ) );
   QSignalSpy statusSpy( task.data(), SIGNAL( statusChanged( int ) ) );
@@ -150,14 +150,14 @@ void TestQgsTaskManager::task()
   QCOMPARE( static_cast< QgsTask::TaskStatus >( statusSpy2.last().at( 0 ).toInt() ), QgsTask::Complete );
 
   // test flags
-  task.reset( new TestTask( "desc", QgsTask::ProgressReport ) );
+  task.reset( new TestTask( "desc", QgsTask::CanReportProgress ) );
   QVERIFY( !task->canCancel() );
-  QVERIFY( task->flags() & QgsTask::ProgressReport );
+  QVERIFY( task->flags() & QgsTask::CanReportProgress );
-  QVERIFY( !( task->flags() & QgsTask::CancelSupport ) );
+  QVERIFY( !( task->flags() & QgsTask::CanCancel ) );
-  task.reset( new TestTask( "desc", QgsTask::CancelSupport ) );
+  task.reset( new TestTask( "desc", QgsTask::CanCancel ) );
   QVERIFY( task->canCancel() );
-  QVERIFY( !( task->flags() & QgsTask::ProgressReport ) );
+  QVERIFY( !( task->flags() & QgsTask::CanReportProgress ) );
-  QVERIFY( task->flags() & QgsTask::CancelSupport );
+  QVERIFY( task->flags() & QgsTask::CanCancel );
 }