1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
/*
kopetetask.h - Kopete Task
Copyright (c) 2004 by Richard Smith <kde@metafoo.co.uk>
Kopete (c) 2002-2004 by the Kopete developers <kopete-devel@kde.org>
*************************************************************************
* *
* This library is free software; you can redistribute it and/or *
* modify it under the terms of the GNU Lesser General Public *
* License as published by the Free Software Foundation; either *
* version 2 of the License, or (at your option) any later version. *
* *
*************************************************************************
*/
#ifndef KOPETETASK_H
#define KOPETETASK_H
#include <qobject.h>
#include <kdemacros.h>
namespace Kopete
{
/**
* The base class for all tasks.
* For most tasks created in Kopete, the code looks like
*
* \code
* Kopete::Task *task = someobject->someoperation( some parameters );
* connect( task, SIGNAL( result( Kopete::Task * ) ),
* this, SLOT( slotResult( Kopete::Task * ) ) );
* \endcode
* (other connects, specific to the job)
*
* And slotResult is usually at least:
*
* \code
* if ( !task->succeeded() )
* Kopete::UI::Global::showTaskError( task );
* \endcode
*
* Much of the ideas (and some of the documentation and function names) for this
* class come from KIO::Job.
* @author Richard Smith <kde@metafoo.co.uk>
*/
class Task : public QObject
{
Q_OBJECT
protected:
Task();
public:
~Task();
/**
* Returns whether the task completed successfully.
* Only call this method from the slot connected to result().
* @return if the task succeeded, returns true, otherwise returns false.
*/
bool succeeded() const;
/**
* Converts an error code and a non-i18n error message into an
* error message in the current language. The low level (non-i18n)
* error message (usually a url) is put into the translated error
* message using %%1.
*
* Use this to display the error yourself, but for a dialog box
* use Kopete::UI::Global::showTaskError. Do not call it if succeeded()
* returns true.
* @return the error message and if there is no error, a message
* telling the user that the app is broken, so check with
* succeeded() whether there is an error.
*/
const QString &errorString() const;
/** Flags for the abort() function */
enum AbortFlags { AbortNormal = 0, AbortEmitResult = 1 };
public slots:
/**
* Abort this task.
* This aborts all subtasks and deletes the task.
*
* @param flags a combination of flags from AbortFlags. If AbortEmitResult is
* set, Job will emit the result signal. AbortEmitResult is removed
* from the flags passed to the abort function of subtasks.
*/
virtual void abort( int flags = AbortNormal );
signals:
/**
* Emitted when the task is finished, in any case (completed, canceled,
* failed...). Use error() to find the result.
* @param task the task that emitted this signal
*/
void result( Kopete::Task *task );
/**
* Emitted to display status information about this task.
* Examples of messages are:
* "Removing ICQ contact Joe from server-side list",
* "Loading account plugin", etc.
* @param task the task that emitted this signal
* @param message the info message
*/
void statusMessage( Kopete::Task *task, const QString &message );
protected:
/**
* Add a task that has to be completed before a result is emitted. This
* obviously should not be called after the finish signal is emitted by
* the subtask.
*
* @param task the subtask to add
*/
virtual void addSubtask( Task *task );
enum RemoveSubtaskIfLast { IfLastDoNothing, IfLastEmitResult };
/**
* Mark a sub job as being done. If it's the last to
* wait on the job will emit a result - jobs with
* two steps might want to override slotResult
* in order to avoid calling this method.
*
* @param task the subjob to add
* @param actionIfLast the action to take if this is the last subtask.
* If set to IfLastEmitResult, the error information from @p task
* will be copied to this object, and emitResult() will be called.
*/
virtual void removeSubtask( Task *task, RemoveSubtaskIfLast actionIfLast = IfLastEmitResult );
enum Result { ResultFailed = 0, ResultSucceeded = 1 };
/**
* Utility function to emit the result signal, and suicide this job.
* Sets the stored result and error message to @p result and @p errorMessage.
* You should call this instead of emitting the result() signal yourself.
*/
void emitResult( Result result = ResultSucceeded, const QString &errorMessage = QString::null );
protected slots:
/**
* Called whenever a subtask finishes.
* The default implementation checks for errors and propagates
* them to this task, then calls removeSubtask().
* Override if you want to provide a different @p actionIfLast to
* removeSubtask, or want to perform some other processing in response
* to a subtask finishing
* @param task the subtask that finished
* @see result()
*/
virtual void slotResult( Kopete::Task *task );
private:
class Private;
Private *d;
};
}
#endif
// vim: set noet ts=4 sts=4 sw=4:
|
