KCoreAddons

kjobtrackerinterface.h
1 /*
2  This file is part of the KDE project
3 
4  SPDX-FileCopyrightText: 2007 Kevin Ottens <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-only
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  */
25 class KCOREADDONS_EXPORT KJobTrackerInterface : public QObject
26 {
27  Q_OBJECT
28 
29 public:
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 
42 public 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 
81 protected 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 plain the info message
125  * @param rich the rich text version of the message, or QString() is none is available
126  */
127  virtual void infoMessage(KJob *job, const QString &plain, const QString &rich);
128 
129  /**
130  * Emitted to display a warning about a job.
131  *
132  * @param job the job that emitted this signal
133  * @param plain the warning message
134  * @param rich the rich text version of the message, or QString() is none is available
135  */
136  virtual void warning(KJob *job, const QString &plain, const QString &rich);
137 
138  /**
139  * Called when we know the amount a job will have to process. The unit of this
140  * amount is provided too. It can be called several times for a given job if the job
141  * manages several different units.
142  *
143  * @param job the job that emitted this signal
144  * @param unit the unit of the total amount
145  * @param amount the total amount
146  */
147  virtual void totalAmount(KJob *job, KJob::Unit unit, qulonglong amount);
148 
149  /**
150  * Regularly called to show the progress of a job by giving the current amount.
151  * The unit of this amount is provided too. It can be called several times for a given
152  * job if the job manages several different units.
153  *
154  * @param job the job that emitted this signal
155  * @param unit the unit of the processed amount
156  * @param amount the processed amount
157  */
158  virtual void processedAmount(KJob *job, KJob::Unit unit, qulonglong amount);
159 
160  /**
161  * Called to show the overall progress of the job.
162  * Note that this is not called for finished jobs.
163  *
164  * @param job the job that emitted this signal
165  * @param percent the percentage
166  */
167  virtual void percent(KJob *job, unsigned long percent);
168 
169  /**
170  * Called to show the speed of the job.
171  *
172  * @param job the job that emitted this signal
173  * @param value the current speed of the job
174  */
175  virtual void speed(KJob *job, unsigned long value);
176 
177 private:
178  std::unique_ptr<class KJobTrackerInterfacePrivate> const d;
179 };
180 
181 #endif
Unit
Describes the unit used in the methods that handle reporting the job progress info.
Definition: kjob.h:90
The interface to implement to track the progresses of a job.
The base class for all jobs.
Definition: kjob.h:76
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Wed Apr 21 2021 23:01:58 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.