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 */
32class KDECORE_EXPORT KJobTrackerInterface : public QObject
33{
34 Q_OBJECT
35
36public:
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
49public 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
64protected 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
162private:
163 class Private;
164 Private *const d;
165};
166
167#endif
168