KCoreAddons

kjobuidelegate.h
1 /*
2  This file is part of the KDE libraries
3 
4  SPDX-FileCopyrightText: 2000 Stephan Kulow <[email protected]>
5  SPDX-FileCopyrightText: 2000 David Faure <[email protected]>
6  SPDX-FileCopyrightText: 2006 Kevin Ottens <[email protected]>
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 
18 class 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  */
31 class KCOREADDONS_EXPORT KJobUiDelegate : public QObject
32 {
33  Q_OBJECT
34 
35 public:
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.
54  */
56 
57  /**
58  * Constructs a new KJobUiDelegate with a flags argument.
59  * @param flags allows to enable automatic error/warning handling
60  * @since 5.70
61  */
62  explicit KJobUiDelegate(Flags flags); // KF6 TODO merge with default constructor, using AutoHandlingDisabled as default value
63 
64  /**
65  * Destroys a KJobUiDelegate.
66  */
67  ~KJobUiDelegate() override;
68 
69 protected:
70  /**
71  * Attach this UI delegate to a job. Once attached it'll track the job events.
72  *
73  * @return @c true if this UI delegate was successfully attached to @p job, @c false otherwise
74  *
75  * @note if this UI delegate is already attached to a job, calling this method will return
76  * @c false.
77  */
78  virtual bool setJob(KJob *job);
79 
80 protected:
81  /**
82  * Retrieves the current job this UI delegate is attached to.
83  *
84  * @return current job this UI delegate is attached to, or @c nullptr if
85  * this UI delegate is not tracking any job
86  */
87  KJob *job() const;
88 
89  friend class KJob;
90 
91 public:
92  /**
93  * Display to the user the error given by this job.
94  * The default implementation uses qWarning(). Subclasses
95  * reimplement this to use something more user-visible such
96  * as a message box.
97  *
98  * Only call this method if error is not 0, and only in the
99  * slot connected to result.
100  */
101  virtual void showErrorMessage();
102 
103  /**
104  * Enable or disable the automatic error handling. When automatic
105  * error handling is enabled and an error occurs, then showErrorDialog()
106  * is called, right before the emission of the result signal.
107  *
108  * The default is false.
109  *
110  * See also isAutoErrorHandlingEnabled , showErrorDialog
111  *
112  * @param enable enable or disable automatic error handling
113  * @see isAutoErrorHandlingEnabled()
114  */
115  void setAutoErrorHandlingEnabled(bool enable);
116 
117  /**
118  * Returns whether automatic error handling is enabled or disabled.
119  * See also setAutoErrorHandlingEnabled .
120  * @return true if automatic error handling is enabled
121  * @see setAutoErrorHandlingEnabled()
122  */
123  bool isAutoErrorHandlingEnabled() const;
124 
125  /**
126  * Enable or disable the automatic warning handling. When automatic
127  * warning handling is enabled and an error occurs, then a message box
128  * is displayed with the warning message
129  *
130  * The default is true.
131  *
132  * See also isAutoWarningHandlingEnabled , showErrorDialog
133  *
134  * @param enable enable or disable automatic warning handling
135  * @see isAutoWarningHandlingEnabled()
136  */
137  void setAutoWarningHandlingEnabled(bool enable);
138 
139  /**
140  * Returns whether automatic warning handling is enabled or disabled.
141  * See also setAutoWarningHandlingEnabled .
142  * @return true if automatic warning handling is enabled
143  * @see setAutoWarningHandlingEnabled()
144  */
145  bool isAutoWarningHandlingEnabled() const;
146 
147 protected Q_SLOTS:
148  virtual void slotWarning(KJob *job, const QString &plain, const QString &rich);
149 
150 private:
151  KCOREADDONS_NO_EXPORT void connectJob(KJob *job);
152 
153 private:
154  std::unique_ptr<class KJobUiDelegatePrivate> const d;
155 };
156 
157 Q_DECLARE_OPERATORS_FOR_FLAGS(KJobUiDelegate::Flags)
158 
159 #endif // KJOBUIDELEGATE_H
Q_SLOTSQ_SLOTS
Definition: kjob.h:73
Flag
Flags for the constructor, to enable automatic handling of errors and/or warnings.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sat Sep 30 2023 04:01:18 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.