Skip to content

Commit 2590f68

Browse files
nyalldawsonnyalldawson
committedDec 5, 2016
Documentation updates and small API cleanups
·
ltr-3_40final-3_0_0
1 parent bc37b40 commit 2590f68

File tree

2 files changed

+119
-60
lines changed

2 files changed

+119
-60
lines changed
 

‎src/core/qgstaskmanager.cpp

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,6 @@ void QgsTask::unhold()
7171

7272
void QgsTask::setProgress( double progress )
7373
{
74-
7574
mProgress = progress;
7675
emit progressChanged( progress );
7776
}

‎src/core/qgstaskmanager.h

Lines changed: 119 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -20,14 +20,22 @@
2020

2121
#include <QObject>
2222
#include <QMap>
23-
#include <QAbstractItemModel>
2423
#include <QFuture>
2524

2625
/**
2726
* \ingroup core
2827
* \class QgsTask
29-
* \brief Interface class for long running background tasks. Tasks can be controlled directly,
28+
* \brief Abstract base class for long running background tasks. Tasks can be controlled directly,
3029
* or added to a QgsTaskManager for automatic management.
30+
*
31+
* Derived classes should implement the process they want to execute in the background
32+
* within the run() method. This method will be called when the
33+
* task commences (ie via calling start() ).
34+
*
35+
* Long running tasks should periodically check the isCancelled() flag to detect if the task
36+
* has been cancelled via some external event. If this flag is true then the task should
37+
* clean up and terminate at the earliest possible convenience.
38+
*
3139
* \note Added in version 3.0
3240
*/
3341
class CORE_EXPORT QgsTask : public QObject
@@ -55,106 +63,158 @@ class CORE_EXPORT QgsTask : public QObject
5563
};
5664
Q_DECLARE_FLAGS( Flags, Flag )
5765

58-
/** Constructor for QgsTask.
66+
/**
67+
* Constructor for QgsTask.
5968
* @param description text description of task
6069
* @param flags task flags
6170
*/
6271
QgsTask( const QString& description = QString(), const Flags& flags = AllFlags );
6372

64-
//! Returns the flags associated with the task.
73+
/**
74+
* Returns the flags associated with the task.
75+
*/
6576
Flags flags() const { return mFlags; }
6677

67-
//! Returns true if the task can be cancelled.
78+
/**
79+
* Returns true if the task can be cancelled.
80+
*/
6881
bool canCancel() const { return mFlags & CanCancel; }
6982

70-
//! Returns true if the task is active, ie it is not complete and has
71-
//! not been cancelled.
83+
/**
84+
* Returns true if the task is active, ie it is not complete and has
85+
* not been cancelled.
86+
*/
7287
bool isActive() const { return mStatus == Running; }
7388

74-
//! Returns the current task status.
89+
/**
90+
* Returns the current task status.
91+
*/
7592
TaskStatus status() const { return mStatus; }
7693

77-
//! Returns the task's description.
94+
/**
95+
* Returns the task's description.
96+
*/
7897
QString description() const { return mDescription; }
7998

80-
//! Returns the task's progress (between 0.0 and 100.0)
99+
/**
100+
* Returns the task's progress (between 0.0 and 100.0)
101+
*/
81102
double progress() const { return mProgress; }
82103

83-
public slots:
84-
85-
//! Starts the task.
104+
/**
105+
* Starts the task. Should only be called for tasks which are not being
106+
* handled by a QgsTaskManager. If the task is managed by a QgsTaskManager
107+
* then this method should not be called directly, instead it is left to the
108+
* task manager to start the task when appropriate.
109+
*/
86110
void start();
87111

88-
//! Notifies the task that it should terminate.
89-
//! @see isCancelled()
112+
/**
113+
* Notifies the task that it should terminate. Calling this is not gauranteed
114+
* to immediately end the task, rather it sets the isCancelled() flag which
115+
* task subclasses can check and terminate their operations at an appropriate
116+
* time.
117+
* @see isCancelled()
118+
*/
90119
void cancel();
91120

92-
//! Called when the task is placed on hold. If the task in not queued
93-
//! (ie it is running or has finished) then calling this has no effect.
94-
//! @see unhold()
121+
/**
122+
* Places the task on hold. If the task in not queued
123+
* (ie it is already running or has finished) then calling this has no effect.
124+
* Calling this method only has an effect for tasks which are managed
125+
* by a QgsTaskManager.
126+
* @see unhold()
127+
*/
95128
void hold();
96129

97-
//! Called when the task should be unheld and re-added to the queue. If the
98-
//! task in not currently being held then calling this has no effect.
99-
//! @see unhold()
130+
/**
131+
* Releases the task from being held. For tasks managed by a QgsTaskManager
132+
* calling this will re-add them to the queue. If the
133+
* task in not currently being held then calling this has no effect.
134+
* @see hold()
135+
*/
100136
void unhold();
101137

102-
//! Sets the task's current progress. If task reports the CanReportProgress flag then
103-
//! the derived class should call this method whenever the task wants to update its
104-
//! progress. Calling will automatically emit the progressChanged signal.
105-
//! @param progress percent of progress, from 0.0 - 100.0
106-
void setProgress( double progress );
107-
108-
//! Sets the task as completed. Should be called when the task is complete.
109-
//! Calling will automatically emit the statusChanged and taskCompleted signals.
110-
void completed();
111-
112-
//! Sets the task as stopped. Should be called whenever the task ends for any
113-
//! reason other than successful completion.
114-
//! Calling will automatically emit the statusChanged and taskStopped signals.
115-
void stopped();
116-
117138
signals:
118139

119-
//! Will be emitted by task when its progress changes
120-
//! @param progress percent of progress, from 0.0 - 100.0
121-
//! @note derived classes should not emit this signal directly, instead they should call
122-
//! setProgress()
140+
/**
141+
* Will be emitted by task when its progress changes.
142+
* @param progress percent of progress, from 0.0 - 100.0
143+
* @note derived classes should not emit this signal directly, instead they should call
144+
* setProgress()
145+
*/
123146
void progressChanged( double progress );
124147

125-
//! Will be emitted by task when its status changes
126-
//! @param status new task status
127-
//! @note derived classes should not emit this signal directly, instead they should call
128-
//! completed() or stopped()
148+
/**
149+
* Will be emitted by task when its status changes.
150+
* @param status new task status
151+
* @note derived classes should not emit this signal directly, instead they should call
152+
* completed() or stopped()
153+
*/
129154
void statusChanged( int status );
130155

131-
//! Will be emitted by task to indicate its commencement.
132-
//! @note derived classes should not emit this signal directly, it will automatically
133-
//! be emitted when the task begins
156+
/**
157+
* Will be emitted by task to indicate its commencement.
158+
* @note derived classes should not emit this signal directly, it will automatically
159+
* be emitted when the task begins
160+
*/
134161
void begun();
135162

136-
//! Will be emitted by task to indicate its completion.
137-
//! @note derived classes should not emit this signal directly, instead they should call
138-
//! completed()
163+
/**
164+
* Will be emitted by task to indicate its successful completion.
165+
* @note derived classes should not emit this signal directly, instead they should call
166+
* completed()
167+
*/
139168
void taskCompleted();
140169

141-
//! Will be emitted by task if it has terminated for any reason
142-
//! other then completion.
143-
//! @note derived classes should not emit this signal directly, instead they should call
144-
//! stopped()//!
170+
/**
171+
* Will be emitted by task if it has terminated for any reason
172+
* other then completion (eg when a task has been cancelled or encountered
173+
* an internal error).
174+
* @note derived classes should not emit this signal directly, instead they should call
175+
* stopped()
176+
*/
145177
void taskStopped();
146178

147179
protected:
148180

149-
//! Derived tasks must implement a run() method. This method will be called when the
150-
//! task commences (ie via calling start() ).
181+
/**
182+
* Performs the task's operation. This method will be called when the task commences
183+
* (ie via calling start() ), and subclasses should implement the operation they
184+
* wish to perform in the background within this method.
185+
*/
151186
virtual void run() = 0;
152187

153-
//! Will return true if task should terminate ASAP. If the task reports the CanCancel
154-
//! flag, then derived classes' run() methods should periodically check this and
155-
//! terminate in a safe manner.
188+
/**
189+
* Will return true if task should terminate ASAP. If the task reports the CanCancel
190+
* flag, then derived classes' run() methods should periodically check this and
191+
* terminate in a safe manner.
192+
*/
156193
bool isCancelled() const { return mShouldTerminate; }
157194

195+
/**
196+
* Sets the task as completed. Should be called when the task is complete.
197+
* Calling will automatically emit the statusChanged and taskCompleted signals.
198+
*/
199+
void completed();
200+
201+
/**
202+
* Sets the task as stopped. Should be called whenever the task ends for any
203+
* reason other than successful completion.
204+
* Calling will automatically emit the statusChanged and taskStopped signals.
205+
*/
206+
void stopped();
207+
208+
protected slots:
209+
210+
/**
211+
* Sets the task's current progress. If task reports the CanReportProgress flag then
212+
* the derived class should call this method whenever the task wants to update its
213+
* progress. Calling will automatically emit the progressChanged signal.
214+
* @param progress percent of progress, from 0.0 - 100.0
215+
*/
216+
void setProgress( double progress );
217+
158218
private:
159219

160220
Flags mFlags;

0 commit comments

Comments
 (0)
Please sign in to comment.