|
| 1 | +/** \ingroup core |
| 2 | + * \class QgsTask |
| 3 | + * \brief Interface class for long running tasks which will be handled by a QgsTaskManager |
| 4 | + * \note Added in version 2.16 |
| 5 | + */ |
| 6 | +class QgsTask : QObject |
| 7 | +{ |
| 8 | + |
| 9 | +%TypeHeaderCode |
| 10 | +#include <qgstaskmanager.h> |
| 11 | +%End |
| 12 | + public: |
| 13 | + |
| 14 | + //! Status of tasks |
| 15 | + enum TaskStatus |
| 16 | + { |
| 17 | + Running, /*!< Task is currently running */ |
| 18 | + Complete, /*!< Task successfully completed */ |
| 19 | + Terminated, /*!< Task was terminated or errored */ |
| 20 | + // Paused, |
| 21 | + // Queued, |
| 22 | + }; |
| 23 | + |
| 24 | + /** Constructor for QgsTask. |
| 25 | + * @param description text description of task |
| 26 | + */ |
| 27 | + QgsTask( const QString& description = QString() ); |
| 28 | + |
| 29 | + //! Will be called when task has been terminated, either through |
| 30 | + //! user interaction or other reason (eg application exit) |
| 31 | + //! @note derived classes must ensure they call the base method |
| 32 | + virtual void terminate(); |
| 33 | + |
| 34 | + //! Returns true if the task is active, ie it is not complete and has |
| 35 | + //! not been terminated. |
| 36 | + bool isActive() const; |
| 37 | + |
| 38 | + //! Returns the current task status. |
| 39 | + TaskStatus status() const; |
| 40 | + |
| 41 | + //! Returns the task's description. |
| 42 | + QString description() const; |
| 43 | + |
| 44 | + //! Returns the task's progress (between 0.0 and 100.0) |
| 45 | + double progress() const; |
| 46 | + |
| 47 | + signals: |
| 48 | + |
| 49 | + //! Will be emitted by task when its progress changes |
| 50 | + //! @param progress percent of progress, from 0.0 - 100.0 |
| 51 | + //! @note derived classes should not emit this signal directly, instead they should call |
| 52 | + //! setProgress() |
| 53 | + void progressChanged( double progress ); |
| 54 | + |
| 55 | + //! Will be emitted by task when its status changes |
| 56 | + //! @param status new task status |
| 57 | + //! @note derived classes should not emit this signal directly, instead they should call |
| 58 | + //! completed() or stopped() |
| 59 | + void statusChanged( int status ); |
| 60 | + |
| 61 | + //! Will be emitted by task to indicate its completion. |
| 62 | + //! @note derived classes should not emit this signal directly, instead they should call |
| 63 | + //! completed() |
| 64 | + void taskCompleted(); |
| 65 | + |
| 66 | + //! Will be emitted by task if it has terminated for any reason |
| 67 | + //! other then completion. |
| 68 | + //! @note derived classes should not emit this signal directly, instead they should call |
| 69 | + //! stopped()//! |
| 70 | + void taskStopped(); |
| 71 | + |
| 72 | + protected: |
| 73 | + |
| 74 | + //! Sets the task's current progress. Should be called whenever the |
| 75 | + //! task wants to update it's progress. Calling will automatically emit the progressChanged |
| 76 | + //! signal. |
| 77 | + //! @param progress percent of progress, from 0.0 - 100.0 |
| 78 | + void setProgress( double progress ); |
| 79 | + |
| 80 | + //! Sets the task as completed. Should be called when the task is complete. |
| 81 | + //! Calling will automatically emit the statusChanged and taskCompleted signals. |
| 82 | + void completed(); |
| 83 | + |
| 84 | + //! Sets the task as stopped. Should be called whenever the task ends for any |
| 85 | + //! reason other than successful completion. |
| 86 | + //! Calling will automatically emit the statusChanged and taskStopped signals. |
| 87 | + void stopped(); |
| 88 | +}; |
| 89 | + |
| 90 | +/** \ingroup core |
| 91 | + * \class QgsTaskManager |
| 92 | + * \brief Task manager for managing a set of long-running QgsTask tasks. This class can be created directly, |
| 93 | + * or accessed via a global instance. |
| 94 | + * \note Added in version 2.16 |
| 95 | + */ |
| 96 | +class QgsTaskManager : QObject |
| 97 | +{ |
| 98 | +%TypeHeaderCode |
| 99 | +#include <qgstaskmanager.h> |
| 100 | +%End |
| 101 | + public: |
| 102 | + |
| 103 | + /** Returns the global task manager instance pointer, creating the object on the first call. |
| 104 | + */ |
| 105 | + static QgsTaskManager * instance(); |
| 106 | + |
| 107 | + /** Constructor for QgsTaskManager. |
| 108 | + * @param parent parent QObject |
| 109 | + */ |
| 110 | + QgsTaskManager( QObject* parent /TransferThis/ = nullptr ); |
| 111 | + |
| 112 | + virtual ~QgsTaskManager(); |
| 113 | + |
| 114 | + /** Adds a task to the manager. Ownership of the task is transferred |
| 115 | + * to the manager. |
| 116 | + * @param task task to add |
| 117 | + * @returns unique task ID |
| 118 | + */ |
| 119 | + long addTask( QgsTask* task /Transfer/ ); |
| 120 | + |
| 121 | + /** Deletes the specified task, first terminating it if it is currently |
| 122 | + * running. |
| 123 | + * @param id task ID |
| 124 | + * @returns true if task was found and deleted |
| 125 | + */ |
| 126 | + bool deleteTask( long id ); |
| 127 | + |
| 128 | + /** Deletes the specified task, first terminating it if it is currently |
| 129 | + * running. |
| 130 | + * @param task task to delete |
| 131 | + * @returns true if task was contained in manager and deleted |
| 132 | + */ |
| 133 | + bool deleteTask( QgsTask* task ); |
| 134 | + |
| 135 | + /** Returns the task with matching ID. |
| 136 | + * @param id task ID |
| 137 | + * @returns task if found, or nullptr |
| 138 | + */ |
| 139 | + QgsTask* task( long id ) const; |
| 140 | + |
| 141 | + /** Returns all tasks tracked by the manager. |
| 142 | + */ |
| 143 | + QList<QgsTask*> tasks() const; |
| 144 | + |
| 145 | + //! Returns the number of tasks tracked by the manager. |
| 146 | + int count() const; |
| 147 | + |
| 148 | + /** Returns the unique task ID corresponding to a task managed by the class. |
| 149 | + * @param task task to find |
| 150 | + * @returns task ID, or -1 if task not found |
| 151 | + */ |
| 152 | + long taskId( QgsTask* task ) const; |
| 153 | + |
| 154 | + signals: |
| 155 | + |
| 156 | + //! Will be emitted when a task reports a progress change |
| 157 | + //! @param taskId ID of task |
| 158 | + //! @param progress percent of progress, from 0.0 - 100.0 |
| 159 | + void progressChanged( long taskId, double progress ); |
| 160 | + |
| 161 | + //! Will be emitted when a task reports a status change |
| 162 | + //! @param taskId ID of task |
| 163 | + //! @param status new task status |
| 164 | + void statusChanged( long taskId, int status ); |
| 165 | + |
| 166 | + //! Emitted when a new task has been added to the manager |
| 167 | + //! @param taskId ID of task |
| 168 | + void taskAdded( long taskId ); |
| 169 | + |
| 170 | + //! Emitted when a task is about to be deleted |
| 171 | + //! @param taskId ID of task |
| 172 | + void taskAboutToBeDeleted( long taskId ); |
| 173 | + |
| 174 | +}; |
0 commit comments