1/*
2 This file is part of the KDE libraries
3
4 SPDX-FileCopyrightText: 2000 Stephan Kulow <coolo@kde.org>
5 SPDX-FileCopyrightText: 2000 David Faure <faure@kde.org>
6 SPDX-FileCopyrightText: 2006 Kevin Ottens <ervin@kde.org>
7
8 SPDX-License-Identifier: LGPL-2.0-or-later
9*/
10
11#ifndef KJOBUIDELEGATE_H
12#define KJOBUIDELEGATE_H
13
14#include <QObject>
15#include <kcoreaddons_export.h>
16#include <memory>
17
18class KJob;
19
20/*!
21 * \class KJobUiDelegate
22 * \inmodule KCoreAddons
23 *
24 * \brief The base class for all KJob UI delegate.
25 *
26 * A UI delegate is responsible for the events of a
27 * job and provides a UI for them (an error message
28 * box or warning etc.).
29 *
30 * \sa KJob
31 */
32class KCOREADDONS_EXPORT KJobUiDelegate : public QObject
33{
34 Q_OBJECT
35
36public:
37 /*!
38 * Flags for the constructor, to enable automatic handling of errors and/or warnings
39 *
40 * \value AutoHandlingDisabled No automatic handling (default)
41 * \value AutoErrorHandlingEnabled Equivalent to setAutoErrorHandlingEnabled(true)
42 * \value AutoWarningHandlingEnabled Equivalent to setAutoWarningHandlingEnabled(true)
43 * \value AutoHandlingEnabled Enables both error and warning handling
44 *
45 * \since 5.70
46 */
47 enum Flag {
48 AutoHandlingDisabled = 0,
49 AutoErrorHandlingEnabled = 1,
50 AutoWarningHandlingEnabled = 2,
51 AutoHandlingEnabled = AutoErrorHandlingEnabled | AutoWarningHandlingEnabled,
52 };
53 Q_DECLARE_FLAGS(Flags, Flag)
54
55 /*!
56 * Constructs a new KJobUiDelegate with a flags argument.
57 *
58 * \a flags allows to enable automatic error/warning handling
59 *
60 * \since 5.70
61 */
62 explicit KJobUiDelegate(Flags flags = {KJobUiDelegate::AutoHandlingDisabled});
63
64 ~KJobUiDelegate() override;
65
66protected:
67 /*!
68 * Attach this UI delegate to a job. Once attached it'll track the job events.
69 *
70 * Returns \c true if this UI delegate was successfully attached to \a job, \c false otherwise
71 *
72 * \note if this UI delegate is already attached to a job, calling this method will return
73 * \c false.
74 */
75 virtual bool setJob(KJob *job);
76
77protected:
78 /*!
79 * Retrieves the current job this UI delegate is attached to.
80 *
81 * Returns the current job this UI delegate is attached to, or \c nullptr if
82 * this UI delegate is not tracking any job
83 */
84 KJob *job() const;
85
86 friend class KJob;
87
88public:
89 /*!
90 * Display to the user the error given by this job.
91 * The default implementation uses qWarning(). Subclasses
92 * reimplement this to use something more user-visible such
93 * as a message box.
94 *
95 * Only call this method if error is not 0, and only in the
96 * slot connected to result.
97 */
98 virtual void showErrorMessage();
99
100 /*!
101 * Enable or disable the automatic error handling. When automatic
102 * error handling is enabled and an error occurs, then showErrorDialog()
103 * is called, right before the emission of the result signal.
104 *
105 * The default is \c false.
106 *
107 * \a enable enable or disable automatic error handling
108 *
109 * \sa isAutoErrorHandlingEnabled()
110 */
111 void setAutoErrorHandlingEnabled(bool enable);
112
113 /*!
114 * Returns whether automatic error handling is enabled or disabled.
115 * \sa setAutoErrorHandlingEnabled()
116 */
117 bool isAutoErrorHandlingEnabled() const;
118
119 /*!
120 * Enable or disable the automatic warning handling. When automatic
121 * warning handling is enabled and an error occurs, then a message box
122 * is displayed with the warning message
123 *
124 * The default is \c true.
125 *
126 * \a enable enable or disable automatic warning handling
127 *
128 * \sa isAutoWarningHandlingEnabled()
129 */
130 void setAutoWarningHandlingEnabled(bool enable);
131
132 /*!
133 * Returns whether automatic warning handling is enabled or disabled.
134 * \sa setAutoWarningHandlingEnabled()
135 */
136 bool isAutoWarningHandlingEnabled() const;
137
138protected Q_SLOTS:
139 /*!
140 *
141 */
142 virtual void slotWarning(KJob *job, const QString &message);
143
144private:
145 KCOREADDONS_NO_EXPORT void connectJob(KJob *job);
146
147private:
148 std::unique_ptr<class KJobUiDelegatePrivate> const d;
149};
150
151Q_DECLARE_OPERATORS_FOR_FLAGS(KJobUiDelegate::Flags)
152
153#endif // KJOBUIDELEGATE_H
154

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