1 | /* This file is part of the KDE project |
2 | Copyright (C) 2007 Kevin Ottens <ervin@kde.org> |
3 | |
4 | This library is free software; you can redistribute it and/or |
5 | modify it under the terms of the GNU Library General Public |
6 | License version 2 as published by the Free Software Foundation. |
7 | |
8 | This library is distributed in the hope that it will be useful, |
9 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
10 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
11 | Library General Public License for more details. |
12 | |
13 | You should have received a copy of the GNU Library General Public License |
14 | along with this library; see the file COPYING.LIB. If not, write to |
15 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
16 | Boston, MA 02110-1301, USA. |
17 | |
18 | */ |
19 | |
20 | #ifndef KJOBTRACKERINTERFACE_H |
21 | #define KJOBTRACKERINTERFACE_H |
22 | |
23 | #include <kdecore_export.h> |
24 | #include <kjob.h> |
25 | |
26 | #include <QtCore/QObject> |
27 | #include <QtCore/QPair> |
28 | |
29 | /** |
30 | * The interface to implement to track the progresses of a job. |
31 | */ |
32 | class KDECORE_EXPORT KJobTrackerInterface : public QObject |
33 | { |
34 | Q_OBJECT |
35 | |
36 | public: |
37 | /** |
38 | * Creates a new KJobTrackerInterface |
39 | * |
40 | * @param parent the parent object |
41 | */ |
42 | KJobTrackerInterface(QObject *parent=0); |
43 | |
44 | /** |
45 | * Destroys a KJobTrackerInterface |
46 | */ |
47 | virtual ~KJobTrackerInterface(); |
48 | |
49 | public Q_SLOTS: |
50 | /** |
51 | * Register a new job in this tracker. |
52 | * |
53 | * @param job the job to register |
54 | */ |
55 | virtual void registerJob(KJob *job); |
56 | |
57 | /** |
58 | * Unregister a job from this tracker. |
59 | * |
60 | * @param job the job to unregister |
61 | */ |
62 | virtual void unregisterJob(KJob *job); |
63 | |
64 | protected Q_SLOTS: |
65 | /** |
66 | * Called when a job is finished, in any case. It is used to notify |
67 | * that the job is terminated and that progress UI (if any) can be hidden. |
68 | * |
69 | * @param job the job that emitted this signal |
70 | */ |
71 | virtual void finished(KJob *job); |
72 | |
73 | /** |
74 | * Called when a job is suspended. |
75 | * |
76 | * @param job the job that emitted this signal |
77 | */ |
78 | virtual void suspended(KJob *job); |
79 | |
80 | /** |
81 | * Called when a job is resumed. |
82 | * |
83 | * @param job the job that emitted this signal |
84 | */ |
85 | virtual void resumed(KJob *job); |
86 | |
87 | /** |
88 | * Called to display general description of a job. A description has |
89 | * a title and two optional fields which can be used to complete the |
90 | * description. |
91 | * |
92 | * Examples of titles are "Copying", "Creating resource", etc. |
93 | * The fields of the description can be "Source" with an URL, and, |
94 | * "Destination" with an URL for a "Copying" description. |
95 | * @param job the job that emitted this signal |
96 | * @param title the general description of the job |
97 | * @param field1 first field (localized name and value) |
98 | * @param field2 second field (localized name and value) |
99 | */ |
100 | virtual void description(KJob *job, const QString &title, |
101 | const QPair<QString, QString> &field1, |
102 | const QPair<QString, QString> &field2); |
103 | |
104 | /** |
105 | * Called to display state information about a job. |
106 | * Examples of message are "Resolving host", "Connecting to host...", etc. |
107 | * |
108 | * @param job the job that emitted this signal |
109 | * @param plain the info message |
110 | * @param rich the rich text version of the message, or QString() is none is available |
111 | */ |
112 | virtual void infoMessage(KJob *job, const QString &plain, const QString &rich); |
113 | |
114 | /** |
115 | * Emitted to display a warning about a job. |
116 | * |
117 | * @param job the job that emitted this signal |
118 | * @param plain the warning message |
119 | * @param rich the rich text version of the message, or QString() is none is available |
120 | */ |
121 | virtual void warning(KJob *job, const QString &plain, const QString &rich); |
122 | |
123 | /** |
124 | * Called when we know the amount a job will have to process. The unit of this |
125 | * amount is provided too. It can be called several times for a given job if the job |
126 | * manages several different units. |
127 | * |
128 | * @param job the job that emitted this signal |
129 | * @param unit the unit of the total amount |
130 | * @param amount the total amount |
131 | */ |
132 | virtual void totalAmount(KJob *job, KJob::Unit unit, qulonglong amount); |
133 | |
134 | /** |
135 | * Regularly called to show the progress of a job by giving the current amount. |
136 | * The unit of this amount is provided too. It can be called several times for a given |
137 | * job if the job manages several different units. |
138 | * |
139 | * @param job the job that emitted this signal |
140 | * @param unit the unit of the processed amount |
141 | * @param amount the processed amount |
142 | */ |
143 | virtual void processedAmount(KJob *job, KJob::Unit unit, qulonglong amount); |
144 | |
145 | /** |
146 | * Called to show the overall progress of the job. |
147 | * Note that this is not called for finished jobs. |
148 | * |
149 | * @param job the job that emitted this signal |
150 | * @param percent the percentage |
151 | */ |
152 | virtual void percent(KJob *job, unsigned long percent); |
153 | |
154 | /** |
155 | * Called to show the speed of the job. |
156 | * |
157 | * @param job the job that emitted this signal |
158 | * @param value the current speed of the job |
159 | */ |
160 | virtual void speed(KJob *job, unsigned long value); |
161 | |
162 | private: |
163 | class Private; |
164 | Private *const d; |
165 | }; |
166 | |
167 | #endif |
168 | |