1/* This file is part of the KDE project
2 Copyright (C) 2000 Matej Koss <koss@miesto.sk>
3 Copyright (C) 2007 Kevin Ottens <ervin@kde.org>
4 Copyright (C) 2008 Rafael Fernández López <ereslibre@kde.org>
5
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Library General Public
8 License version 2 as published by the Free Software Foundation.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19
20*/
21
22#ifndef KABSTRACTWIDGETJOBTRACKER_H
23#define KABSTRACTWIDGETJOBTRACKER_H
24
25#include <kdeui_export.h>
26#include <kjobtrackerinterface.h>
27
28class KJob;
29class QWidget;
30
31/**
32 * The base class for widget based job trackers.
33 */
34class KDEUI_EXPORT KAbstractWidgetJobTracker : public KJobTrackerInterface
35{
36 Q_OBJECT
37
38public:
39 /**
40 * Creates a new KAbstractWidgetJobTracker
41 *
42 * @param parent the parent of this object and of the widget displaying the job progresses
43 */
44 KAbstractWidgetJobTracker(QWidget *parent = 0);
45
46 /**
47 * Destroys a KAbstractWidgetJobTracker
48 */
49 virtual ~KAbstractWidgetJobTracker();
50
51// KDE5: move this two virtual methods to be placed correctly (ereslibre)
52public Q_SLOTS:
53 /**
54 * Register a new job in this tracker.
55 * Note that job trackers inheriting from this class can have only one job
56 * registered at a time.
57 *
58 * @param job the job to register
59 */
60 virtual void registerJob(KJob *job);
61
62 /**
63 * Unregister a job from this tracker.
64 *
65 * @param job the job to unregister
66 */
67 virtual void unregisterJob(KJob *job);
68
69public:
70 /**
71 * The widget associated to this tracker.
72 *
73 * @param job the job that is assigned the widget we want to return
74 * @return the widget displaying the job progresses
75 */
76 virtual QWidget *widget(KJob *job) = 0;
77
78 /**
79 * This controls whether the job should be canceled if the dialog is closed.
80 *
81 * @param job the job's widget that will be stopped when closing
82 * @param stopOnClose If true the job will be stopped if the dialog is closed,
83 * otherwise the job will continue even on close.
84 * @see stopOnClose()
85 */
86 void setStopOnClose(KJob *job, bool stopOnClose);
87
88 /**
89 * Checks whether the job will be killed when the dialog is closed.
90 *
91 * @param job the job's widget that will be stopped when closing
92 * @return true if the job is killed on close event, false otherwise.
93 * @see setStopOnClose()
94 */
95 bool stopOnClose(KJob *job) const;
96
97 /**
98 * This controls whether the dialog should be deleted or only cleaned when
99 * the KJob is finished (or canceled).
100 *
101 * If your dialog is an embedded widget and not a separate window, you should
102 * setAutoDelete(false) in the constructor of your custom dialog.
103 *
104 * @param job the job's widget that is going to be auto-deleted
105 * @param autoDelete If false the dialog will only call method slotClean.
106 * If true the dialog will be deleted.
107 * @see autoDelete()
108 */
109 void setAutoDelete(KJob *job, bool autoDelete);
110
111 /**
112 * Checks whether the dialog should be deleted or cleaned.
113 *
114 * @param job the job's widget that will be auto-deleted
115 * @return false if the dialog only calls slotClean, true if it will be
116 * deleted
117 * @see setAutoDelete()
118 */
119 bool autoDelete(KJob *job) const;
120
121protected Q_SLOTS:
122 /**
123 * Called when a job is finished, in any case. It is used to notify
124 * that the job is terminated and that progress UI (if any) can be hidden.
125 *
126 * @param job the job that emitted this signal
127 */
128 virtual void finished(KJob *job);
129
130 /**
131 * This method should be called for correct cancellation of IO operation
132 * Connect this to the progress widgets buttons etc.
133 *
134 * @param job The job that is being stopped
135 */
136 virtual void slotStop(KJob *job);
137
138 /**
139 * This method should be called for pause/resume
140 * Connect this to the progress widgets buttons etc.
141 *
142 * @param job The job that is being suspended
143 */
144 virtual void slotSuspend(KJob *job);
145
146 /**
147 * This method should be called for pause/resume
148 * Connect this to the progress widgets buttons etc.
149 *
150 * @param job The job that is being resumed
151 */
152 virtual void slotResume(KJob *job);
153
154 /**
155 * This method is called when the widget should be cleaned (after job is finished).
156 * redefine this for custom behavior.
157 *
158 * @param job The job that is being cleaned
159 */
160 virtual void slotClean(KJob *job);
161
162Q_SIGNALS:
163 /**
164 * Emitted when the user aborted the operation
165 *
166 * @param job The job that has been stopped
167 */
168 void stopped(KJob *job);
169
170 /**
171 * Emitted when the user suspended the operation
172 *
173 * @param job The job that has been suspended
174 */
175 void suspend(KJob *job);
176
177 /**
178 * Emitted when the user resumed the operation
179 *
180 * @param job The job that has been resumed
181 */
182 void resume(KJob *job);
183
184protected:
185 class Private;
186 Private *const d;
187};
188
189#endif
190