1/*
2 This file is part of the KDE project
3
4 SPDX-FileCopyrightText: 2007 Kevin Ottens <ervin@kde.org>
5
6 SPDX-License-Identifier: LGPL-2.0-or-later
7*/
8
9#ifndef KJOBTRACKERINTERFACE_H
10#define KJOBTRACKERINTERFACE_H
11
12#include <kcoreaddons_export.h>
13#include <kjob.h>
14
15#include <QObject>
16#include <QPair>
17
18#include <memory>
19
20/*!
21 * \class KJobTrackerInterface
22 * \inmodule KCoreAddons
23 *
24 * \brief The interface to implement to track the progresses of a job.
25 */
26class KCOREADDONS_EXPORT KJobTrackerInterface : public QObject
27{
28 Q_OBJECT
29
30public:
31 /*!
32 * Creates a new KJobTrackerInterface
33 *
34 * \a parent the parent object
35 */
36 explicit KJobTrackerInterface(QObject *parent = nullptr);
37
38 ~KJobTrackerInterface() override;
39
40public Q_SLOTS:
41 /*!
42 * Register a new job in this tracker.
43 * The default implementation connects the following KJob signals
44 * to the respective protected slots of this class:
45 * \list
46 * \li finished() (also connected to the unregisterJob() slot)
47 * \li suspended()
48 * \li resumed()
49 * \li description()
50 * \li infoMessage()
51 * \li totalAmount()
52 * \li processedAmount()
53 * \li percent()
54 * \li speed()
55 * \endlist
56 *
57 * If you re-implement this method, you may want to call the default
58 * implementation or add at least:
59 *
60 * \code
61 * connect(job, &KJob::finished, this, &MyJobTracker::unregisterJob);
62 * \endcode
63 *
64 * so that you won't have to manually call unregisterJob().
65 *
66 * \a job the job to register
67 *
68 * \sa unregisterJob()
69 */
70 virtual void registerJob(KJob *job);
71
72 /*!
73 * Unregister a job from this tracker.
74 *
75 * \note You need to manually call this method only if you re-implemented
76 * registerJob() without connecting KJob::finished to this slot.
77 *
78 * \a job the job to unregister
79 *
80 * \sa registerJob()
81 */
82 virtual void unregisterJob(KJob *job);
83
84protected Q_SLOTS:
85 /*!
86 * Called when a job is finished, in any case. It is used to notify
87 * that the job is terminated and that progress UI (if any) can be hidden.
88 *
89 * \a job the job that emitted this signal
90 */
91 virtual void finished(KJob *job);
92
93 /*!
94 * Called when a job is suspended.
95 *
96 * \a job the job that emitted this signal
97 */
98 virtual void suspended(KJob *job);
99
100 /*!
101 * Called when a job is resumed.
102 *
103 * \a job the job that emitted this signal
104 */
105 virtual void resumed(KJob *job);
106
107 /*!
108 * Called to display general description of a job. A description has
109 * a title and two optional fields which can be used to complete the
110 * description.
111 *
112 * Examples of titles are "Copying", "Creating resource", etc.
113 * The fields of the description can be "Source" with an URL, and,
114 * "Destination" with an URL for a "Copying" description.
115 *
116 * \a job the job that emitted this signal
117 *
118 * \a title the general description of the job
119 *
120 * \a field1 first field (localized name and value)
121 *
122 * \a field2 second field (localized name and value)
123 */
124 virtual void description(KJob *job, const QString &title, const QPair<QString, QString> &field1, const QPair<QString, QString> &field2);
125
126 /*!
127 * Called to display state information about a job.
128 * Examples of message are "Resolving host", "Connecting to host...", etc.
129 *
130 * \a job the job that emitted this signal
131 *
132 * \a message the info message
133 */
134 virtual void infoMessage(KJob *job, const QString &message);
135
136 /*!
137 * Emitted to display a warning about a job.
138 *
139 * \a job the job that emitted this signal
140 *
141 * \a message the warning message
142 */
143 virtual void warning(KJob *job, const QString &message);
144
145 /*!
146 * Called when we know the amount a job will have to process. The unit of this
147 * amount is provided too. It can be called several times for a given job if the job
148 * manages several different units.
149 *
150 * \a job the job that emitted this signal
151 *
152 * \a unit the unit of the total amount
153 *
154 * \a amount the total amount
155 */
156 virtual void totalAmount(KJob *job, KJob::Unit unit, qulonglong amount);
157
158 /*!
159 * Regularly called to show the progress of a job by giving the current amount.
160 * The unit of this amount is provided too. It can be called several times for a given
161 * job if the job manages several different units.
162 *
163 * \a job the job that emitted this signal
164 *
165 * \a unit the unit of the processed amount
166 *
167 * \a amount the processed amount
168 */
169 virtual void processedAmount(KJob *job, KJob::Unit unit, qulonglong amount);
170
171 /*!
172 * Called to show the overall progress of the job.
173 * Note that this is not called for finished jobs.
174 *
175 * \a job the job that emitted this signal
176 *
177 * \a percent the percentage
178 */
179 virtual void percent(KJob *job, unsigned long percent);
180
181 /*!
182 * Called to show the speed of the job.
183 *
184 * \a job the job that emitted this signal
185 *
186 * \a value the current speed of the job
187 */
188 virtual void speed(KJob *job, unsigned long value);
189
190private:
191 std::unique_ptr<class KJobTrackerInterfacePrivate> const d;
192};
193
194#endif
195

source code of kcoreaddons/src/lib/jobs/kjobtrackerinterface.h