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 | |
18 | class KJob; |
19 | class QWidget; |
20 | class KAbstractWidgetJobTrackerPrivate; |
21 | |
22 | /** |
23 | * @class KAbstractWidgetJobTracker kabstractwidgetjobtracker.h KAbstractWidgetJobTracker |
24 | * |
25 | * The base class for widget based job trackers. |
26 | */ |
27 | class KJOBWIDGETS_EXPORT KAbstractWidgetJobTracker : public KJobTrackerInterface |
28 | { |
29 | Q_OBJECT |
30 | |
31 | public: |
32 | /** |
33 | * Creates a new KAbstractWidgetJobTracker |
34 | * |
35 | * @param parent the parent of this object and of the widget displaying the job progresses |
36 | */ |
37 | explicit KAbstractWidgetJobTracker(QWidget *parent = nullptr); |
38 | |
39 | /** |
40 | * Destroys a KAbstractWidgetJobTracker |
41 | */ |
42 | ~KAbstractWidgetJobTracker() override; |
43 | |
44 | // KDE5: move this two virtual methods to be placed correctly (ereslibre) |
45 | public Q_SLOTS: |
46 | /** |
47 | * Register a new job in this tracker. |
48 | * Note that job trackers inheriting from this class can have only one job |
49 | * registered at a time. |
50 | * |
51 | * @param job the job to register |
52 | */ |
53 | void registerJob(KJob *job) override; |
54 | |
55 | /** |
56 | * Unregister a job from this tracker. |
57 | * |
58 | * @param job the job to unregister |
59 | */ |
60 | void unregisterJob(KJob *job) override; |
61 | |
62 | public: |
63 | /** |
64 | * The widget associated to this tracker. |
65 | * |
66 | * @param job the job that is assigned the widget we want to return |
67 | * @return the widget displaying the job progresses |
68 | */ |
69 | virtual QWidget *widget(KJob *job) = 0; |
70 | |
71 | /** |
72 | * This controls whether the job should be canceled if the dialog is closed. |
73 | * |
74 | * @param job the job's widget that will be stopped when closing |
75 | * @param stopOnClose If true the job will be stopped if the dialog is closed, |
76 | * otherwise the job will continue even on close. |
77 | * @see 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 | * @param job the job's widget that will be stopped when closing |
85 | * @return true if the job is killed on close event, false otherwise. |
86 | * @see setStopOnClose() |
87 | */ |
88 | bool stopOnClose(KJob *job) const; |
89 | |
90 | /** |
91 | * This controls whether the dialog should be deleted or only cleaned when |
92 | * the KJob is finished (or canceled). |
93 | * |
94 | * If your dialog is an embedded widget and not a separate window, you should |
95 | * setAutoDelete(false) in the constructor of your custom dialog. |
96 | * |
97 | * @param job the job's widget that is going to be auto-deleted |
98 | * @param autoDelete If false the dialog will only call method slotClean. |
99 | * If true the dialog will be deleted. |
100 | * @see autoDelete() |
101 | */ |
102 | void setAutoDelete(KJob *job, bool autoDelete); |
103 | |
104 | /** |
105 | * Checks whether the dialog should be deleted or cleaned. |
106 | * |
107 | * @param job the job's widget that will be auto-deleted |
108 | * @return false if the dialog only calls slotClean, true if it will be |
109 | * deleted |
110 | * @see setAutoDelete() |
111 | */ |
112 | bool autoDelete(KJob *job) const; |
113 | |
114 | protected Q_SLOTS: |
115 | /** |
116 | * Called when a job is finished, in any case. It is used to notify |
117 | * that the job is terminated and that progress UI (if any) can be hidden. |
118 | * |
119 | * @param job the job that emitted this signal |
120 | */ |
121 | void finished(KJob *job) override; |
122 | |
123 | /** |
124 | * This method should be called for correct cancellation of IO operation |
125 | * Connect this to the progress widgets buttons etc. |
126 | * |
127 | * @param job The job that is being stopped |
128 | */ |
129 | virtual void slotStop(KJob *job); |
130 | |
131 | /** |
132 | * This method should be called for pause/resume |
133 | * Connect this to the progress widgets buttons etc. |
134 | * |
135 | * @param job The job that is being suspended |
136 | */ |
137 | virtual void slotSuspend(KJob *job); |
138 | |
139 | /** |
140 | * This method should be called for pause/resume |
141 | * Connect this to the progress widgets buttons etc. |
142 | * |
143 | * @param job The job that is being resumed |
144 | */ |
145 | virtual void slotResume(KJob *job); |
146 | |
147 | /** |
148 | * This method is called when the widget should be cleaned (after job is finished). |
149 | * redefine this for custom behavior. |
150 | * |
151 | * @param job The job that is being cleaned |
152 | */ |
153 | virtual void slotClean(KJob *job); |
154 | |
155 | Q_SIGNALS: |
156 | /** |
157 | * Emitted when the user aborted the operation |
158 | * |
159 | * @param job The job that has been stopped |
160 | */ |
161 | void stopped(KJob *job); |
162 | |
163 | /** |
164 | * Emitted when the user suspended the operation |
165 | * |
166 | * @param job The job that has been suspended |
167 | */ |
168 | void suspend(KJob *job); |
169 | |
170 | /** |
171 | * Emitted when the user resumed the operation |
172 | * |
173 | * @param job The job that has been resumed |
174 | */ |
175 | void resume(KJob *job); |
176 | |
177 | protected: |
178 | KJOBWIDGETS_NO_EXPORT explicit KAbstractWidgetJobTracker(KAbstractWidgetJobTrackerPrivate &dd, QWidget *parent = nullptr); |
179 | |
180 | protected: |
181 | std::unique_ptr<KAbstractWidgetJobTrackerPrivate> const d_ptr; |
182 | |
183 | private: |
184 | Q_DECLARE_PRIVATE(KAbstractWidgetJobTracker) |
185 | }; |
186 | |
187 | #endif |
188 | |