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

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