1/*
2 This file is part of the KDE project
3 SPDX-FileCopyrightText: 2000 Matej Koss <koss@miesto.sk>
4 SPDX-FileCopyrightText: 2007 Kevin Ottens <ervin@kde.org>
5 SPDX-FileCopyrightText: 2008 Rafael Fernández López <ereslibre@kde.org>
6
7 SPDX-License-Identifier: LGPL-2.0-only
8*/
9
10#ifndef KABSTRACTWIDGETJOBTRACKER_H
11#define KABSTRACTWIDGETJOBTRACKER_H
12
13#include <KJobTrackerInterface>
14#include <kjobwidgets_export.h>
15
16#include <memory>
17
18class KJob;
19class QWidget;
20class KAbstractWidgetJobTrackerPrivate;
21
22/*!
23 * \class KAbstractWidgetJobTracker
24 * \inmodule KJobWidgets
25 *
26 * \brief The base class for widget based job trackers.
27 */
28class KJOBWIDGETS_EXPORT KAbstractWidgetJobTracker : public KJobTrackerInterface
29{
30 Q_OBJECT
31
32public:
33 /*!
34 * Creates a new KAbstractWidgetJobTracker
35 *
36 * \a parent the parent of this object and of the widget displaying the job progresses
37 */
38 explicit KAbstractWidgetJobTracker(QWidget *parent = nullptr);
39
40 ~KAbstractWidgetJobTracker() override;
41
42 // KDE5: move this two virtual methods to be placed correctly (ereslibre)
43public Q_SLOTS:
44 /*!
45 * Register a new job in this tracker.
46 * Note that job trackers inheriting from this class can have only one job
47 * registered at a time.
48 *
49 * \a job the job to register
50 */
51 void registerJob(KJob *job) override;
52
53 /*!
54 * Unregister a job from this tracker.
55 *
56 * \a job the job to unregister
57 */
58 void unregisterJob(KJob *job) override;
59
60public:
61 /*!
62 * The widget associated to this tracker.
63 *
64 * \a job the job that is assigned the widget we want to return
65 * Returns the widget displaying the job progresses
66 */
67 virtual QWidget *widget(KJob *job) = 0;
68
69 /*!
70 * This controls whether the job should be canceled if the dialog is closed.
71 *
72 * \a job the job's widget that will be stopped when closing
73 *
74 * \a stopOnClose If true the job will be stopped if the dialog is closed,
75 * otherwise the job will continue even on close.
76 *
77 * \sa stopOnClose()
78 */
79 void setStopOnClose(KJob *job, bool stopOnClose);
80
81 /*!
82 * Checks whether the job will be killed when the dialog is closed.
83 *
84 * \a job the job's widget that will be stopped when closing
85 *
86 * Returns \c true if the job is killed on close event, false otherwise.
87 *
88 * \sa setStopOnClose()
89 */
90 bool stopOnClose(KJob *job) const;
91
92 /*!
93 * This controls whether the dialog should be deleted or only cleaned when
94 * the KJob is finished (or canceled).
95 *
96 * If your dialog is an embedded widget and not a separate window, you should
97 * setAutoDelete(false) in the constructor of your custom dialog.
98 *
99 * \a job the job's widget that is going to be auto-deleted
100 *
101 * \a autoDelete If false the dialog will only call method slotClean.
102 *
103 * If true the dialog will be deleted.
104 *
105 * \sa autoDelete()
106 */
107 void setAutoDelete(KJob *job, bool autoDelete);
108
109 /*!
110 * Checks whether the dialog should be deleted or cleaned.
111 *
112 * \a job the job's widget that will be auto-deleted
113 *
114 * Returns \c false if the dialog only calls slotClean, true if it will be deleted
115 * \sa setAutoDelete()
116 */
117 bool autoDelete(KJob *job) const;
118
119protected Q_SLOTS:
120 void finished(KJob *job) override;
121
122 /*!
123 * This method should be called for correct cancellation of IO operation
124 * Connect this to the progress widgets buttons etc.
125 *
126 * \a job The job that is being stopped
127 */
128 virtual void slotStop(KJob *job);
129
130 /*!
131 * This method should be called for pause/resume
132 * Connect this to the progress widgets buttons etc.
133 *
134 * \a job The job that is being suspended
135 */
136 virtual void slotSuspend(KJob *job);
137
138 /*!
139 * This method should be called for pause/resume
140 * Connect this to the progress widgets buttons etc.
141 *
142 * \a job The job that is being resumed
143 */
144 virtual void slotResume(KJob *job);
145
146 /*!
147 * This method is called when the widget should be cleaned (after job is finished).
148 * redefine this for custom behavior.
149 *
150 * \a job The job that is being cleaned
151 */
152 virtual void slotClean(KJob *job);
153
154Q_SIGNALS:
155 /*!
156 * Emitted when the user aborted the operation
157 *
158 * \a job The job that has been stopped
159 */
160 void stopped(KJob *job);
161
162 /*!
163 * Emitted when the user suspended the operation
164 *
165 * \a job The job that has been suspended
166 */
167 void suspend(KJob *job);
168
169 /*!
170 * Emitted when the user resumed the operation
171 *
172 * \a job The job that has been resumed
173 */
174 void resume(KJob *job);
175
176protected:
177 KJOBWIDGETS_NO_EXPORT explicit KAbstractWidgetJobTracker(KAbstractWidgetJobTrackerPrivate &dd, QWidget *parent = nullptr);
178
179protected:
180 std::unique_ptr<KAbstractWidgetJobTrackerPrivate> const d_ptr;
181
182private:
183 Q_DECLARE_PRIVATE(KAbstractWidgetJobTracker)
184};
185
186#endif
187

source code of kjobwidgets/src/kabstractwidgetjobtracker.h