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 kjobtrackerinterface.h KJobTrackerInterface
22 *
23 * The interface to implement to track the progresses of a job.
24 */
25class KCOREADDONS_EXPORT KJobTrackerInterface : public QObject
26{
27 Q_OBJECT
28
29public:
30 /**
31 * Creates a new KJobTrackerInterface
32 *
33 * @param parent the parent object
34 */
35 explicit KJobTrackerInterface(QObject *parent = nullptr);
36
37 /**
38 * Destroys a KJobTrackerInterface
39 */
40 ~KJobTrackerInterface() override;
41
42public Q_SLOTS:
43 /**
44 * Register a new job in this tracker.
45 * The default implementation connects the following KJob signals
46 * to the respective protected slots of this class:
47 * - finished() (also connected to the unregisterJob() slot)
48 * - suspended()
49 * - resumed()
50 * - description()
51 * - infoMessage()
52 * - totalAmount()
53 * - processedAmount()
54 * - percent()
55 * - speed()
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 * @param job the job to register
67 * @see unregisterJob()
68 */
69 virtual void registerJob(KJob *job);
70
71 /**
72 * Unregister a job from this tracker.
73 * @note You need to manually call this method only if you re-implemented
74 * registerJob() without connecting KJob::finished to this slot.
75 *
76 * @param job the job to unregister
77 * @see registerJob()
78 */
79 virtual void unregisterJob(KJob *job);
80
81protected Q_SLOTS:
82 /**
83 * Called when a job is finished, in any case. It is used to notify
84 * that the job is terminated and that progress UI (if any) can be hidden.
85 *
86 * @param job the job that emitted this signal
87 */
88 virtual void finished(KJob *job);
89
90 /**
91 * Called when a job is suspended.
92 *
93 * @param job the job that emitted this signal
94 */
95 virtual void suspended(KJob *job);
96
97 /**
98 * Called when a job is resumed.
99 *
100 * @param job the job that emitted this signal
101 */
102 virtual void resumed(KJob *job);
103
104 /**
105 * Called to display general description of a job. A description has
106 * a title and two optional fields which can be used to complete the
107 * description.
108 *
109 * Examples of titles are "Copying", "Creating resource", etc.
110 * The fields of the description can be "Source" with an URL, and,
111 * "Destination" with an URL for a "Copying" description.
112 * @param job the job that emitted this signal
113 * @param title the general description of the job
114 * @param field1 first field (localized name and value)
115 * @param field2 second field (localized name and value)
116 */
117 virtual void description(KJob *job, const QString &title, const QPair<QString, QString> &field1, const QPair<QString, QString> &field2);
118
119 /**
120 * Called to display state information about a job.
121 * Examples of message are "Resolving host", "Connecting to host...", etc.
122 *
123 * @param job the job that emitted this signal
124 * @param message the info message
125 */
126 virtual void infoMessage(KJob *job, const QString &message);
127
128 /**
129 * Emitted to display a warning about a job.
130 *
131 * @param job the job that emitted this signal
132 * @param message the warning message
133 */
134 virtual void warning(KJob *job, const QString &message);
135
136 /**
137 * Called when we know the amount a job will have to process. The unit of this
138 * amount is provided too. It can be called several times for a given job if the job
139 * manages several different units.
140 *
141 * @param job the job that emitted this signal
142 * @param unit the unit of the total amount
143 * @param amount the total amount
144 */
145 virtual void totalAmount(KJob *job, KJob::Unit unit, qulonglong amount);
146
147 /**
148 * Regularly called to show the progress of a job by giving the current amount.
149 * The unit of this amount is provided too. It can be called several times for a given
150 * job if the job manages several different units.
151 *
152 * @param job the job that emitted this signal
153 * @param unit the unit of the processed amount
154 * @param amount the processed amount
155 */
156 virtual void processedAmount(KJob *job, KJob::Unit unit, qulonglong amount);
157
158 /**
159 * Called to show the overall progress of the job.
160 * Note that this is not called for finished jobs.
161 *
162 * @param job the job that emitted this signal
163 * @param percent the percentage
164 */
165 virtual void percent(KJob *job, unsigned long percent);
166
167 /**
168 * Called to show the speed of the job.
169 *
170 * @param job the job that emitted this signal
171 * @param value the current speed of the job
172 */
173 virtual void speed(KJob *job, unsigned long value);
174
175private:
176 std::unique_ptr<class KJobTrackerInterfacePrivate> const d;
177};
178
179#endif
180

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