1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2020 Ahmad Samir <a.samirh78@gmail.com>
4
5 SPDX-License-Identifier: LGPL-2.0-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
6*/
7
8#ifndef ASKUSERACTIONINTERFACE_H
9#define ASKUSERACTIONINTERFACE_H
10
11#include <kio/jobuidelegateextension.h> // RenameDialog_Result, SkipDialog_Result
12#include <kiocore_export.h>
13
14#include <QObject>
15#include <QUrl>
16
17#include <QSsl>
18
19#include <memory>
20
21class KJob;
22
23namespace KIO
24{
25class AskUserActionInterfacePrivate;
26
27/*!
28 * \class KIO::AskUserActionInterface
29 * \inheaderfile KIO/AskUserActionInterface
30 * \inmodule KIOCore
31 *
32 * \brief The AskUserActionInterface class allows a KIO::Job to prompt the user
33 * for a decision when e.g.\ copying directories/files and there is a conflict
34 * (e.g.\ a file with the same name already exists at the destination).
35 *
36 * The methods in this interface are similar to their counterparts in
37 * KIO::JobUiDelegateExtension, the main difference is that AskUserActionInterface
38 * shows the dialogs using show() or open(), rather than exec(), the latter creates
39 * a nested event loop which could lead to crashes.
40 *
41 * \sa KIO::JobUiDelegateExtension
42 *
43 * \since 5.78
44 */
45class KIOCORE_EXPORT AskUserActionInterface : public QObject
46{
47 Q_OBJECT
48
49protected:
50 /*!
51 * Constructor
52 */
53 explicit AskUserActionInterface(QObject *parent = nullptr);
54
55public:
56 ~AskUserActionInterface() override;
57
58 /*!
59 * \sa KIO::RenameDialog
60 *
61 * Constructs a modal, parent-less "rename" dialog, to prompt the user for a decision
62 * in case of conflicts, while copying/moving files. The dialog is shown using open(),
63 * rather than exec() (the latter creates a nested eventloop which could lead to crashes).
64 * You will need to connect to the askUserRenameResult() signal to get the dialog's result
65 * (exit code). The exit code is one of KIO::RenameDialog_Result.
66 *
67 * \sa KIO::RenameDialog_Result
68 *
69 * \a job the job that called this method
70 *
71 * \a title the title for the dialog box
72 *
73 * \a src the URL of the file/dir being copied/moved
74 *
75 * \a dest the URL of the destination file/dir, i.e. the one that already exists
76 *
77 * \a options parameters for the dialog (which buttons to show... etc), OR'ed values
78 *
79 * \a from the KIO::RenameDialog_Options enum
80 *
81 * \a sizeSrc size of the source file
82 *
83 * \a sizeDest size of the destination file
84 *
85 * \a ctimeSrc creation time of the source file
86 *
87 * \a ctimeDest creation time of the destination file
88 *
89 * \a mtimeSrc modification time of the source file
90 *
91 * \a mtimeDest modification time of the destination file
92 */
93 virtual void askUserRename(KJob *job,
94 const QString &title,
95 const QUrl &src,
96 const QUrl &dest,
97 KIO::RenameDialog_Options options,
98 KIO::filesize_t sizeSrc,
99 KIO::filesize_t sizeDest,
100 const QDateTime &ctimeSrc = {},
101 const QDateTime &ctimeDest = {},
102 const QDateTime &mtimeSrc = {},
103 const QDateTime &mtimeDest = {}) = 0;
104
105 /*!
106 * \sa KIO::SkipDialog
107 *
108 * You need to connect to the askUserSkipResult signal to get the dialog's
109 * result.
110 *
111 * \a job the job that called this method
112 *
113 * \a options parameters for the dialog (which buttons to show... etc), OR'ed
114 * values from the KIO::SkipDialog_Options enum
115 *
116 * \a error_text the error text to show to the user (usually the string returned
117 * by KJob::errorText())
118 */
119 virtual void askUserSkip(KJob *job, KIO::SkipDialog_Options options, const QString &errorText) = 0;
120
121 /*!
122 * The type of deletion.
123 *
124 * Used by askUserDelete().
125 *
126 * \value Delete Delete the files/directories directly, i.e. without moving them to Trash
127 * \value Trash Move the files/directories to Trash
128 * \value EmptyTrash Empty the Trash
129 * \value [since 5.100] DeleteInsteadOfTrash This is the same as Delete, but more text is added to the message to inform the user that moving to Trash was
130 * tried but failed due to size constraints. Typical use case is re-asking the user about deleting instead of Trashing.
131 */
132 enum DeletionType {
133 Delete,
134 Trash,
135 EmptyTrash,
136 DeleteInsteadOfTrash,
137 };
138
139 /*!
140 * Deletion confirmation type.
141 *
142 * Used by askUserDelete().
143 *
144 * \value DefaultConfirmation Do not ask if the user has previously set the "Do not ask again" checkbox (which is is shown in the message dialog invoked by
145 * askUserDelete())
146 * \value ForceConfirmation Always ask the user for confirmation
147 *
148 */
149 enum ConfirmationType {
150 DefaultConfirmation,
151 ForceConfirmation,
152 };
153
154 /*!
155 * Ask for confirmation before moving \a urls (files/directories) to the Trash,
156 * emptying the Trash, or directly deleting files (i.e. without moving to Trash).
157 *
158 * Note that this method is not called automatically by KIO jobs. It's the
159 * application's responsibility to ask the user for confirmation before calling
160 * KIO::del() or KIO::trash().
161 *
162 * You need to connect to the askUserDeleteResult signal to get the dialog's result
163 * (exit code).
164 *
165 * \a urls the urls about to be moved to the Trash or deleted directly
166 *
167 * \a deletionType the type of deletion (Delete for real deletion, Trash otherwise),
168 * see the DeletionType enum
169 *
170 * \a confirmationType The type of deletion confirmation, see the ConfirmationType enum.
171 * Normally set to DefaultConfirmation
172 *
173 * \a parent the parent widget of the message box
174 */
175 virtual void askUserDelete(const QList<QUrl> &urls,
176 DeletionType deletionType,
177 ConfirmationType confirmationType,
178 QWidget *parent = nullptr) = 0; // TODO KF6: replace QWidget* with QObject*
179
180 /*!
181 * \value [since 5.100] QuestionTwoActions
182 * \value [since 5.100] QuestionTwoActionsCancel
183 * \value [since 5.100] WarningTwoActions
184 * \value [since 5.100] WarningTwoActionsCancel
185 * \value WarningContinueCancel
186 * \value Information
187 * \value Error
188 */
189 enum MessageDialogType {
190 QuestionTwoActions = 1,
191 QuestionTwoActionsCancel = 2,
192 WarningTwoActions = 3,
193 WarningTwoActionsCancel = 4,
194 WarningContinueCancel = 5,
195 Information = 7,
196 Error = 9,
197 };
198
199 /*!
200 * This function allows for the delegation of user prompts from the KIO worker.
201 *
202 * \a type the desired type of message box, see the MessageDialogType enum
203 *
204 * \a text the message to show to the user
205 *
206 * \a title the title of the message dialog box
207 *
208 * \a primaryActionText the text for the primary action
209 *
210 * \a secondatyActionText the text for the secondary action
211 *
212 * \a primaryActionIconName the icon to show on the primary action
213 *
214 * \a secondatyActionIconName the icon to show on the secondary action
215 *
216 * \a dontAskAgainName the config key name used to store the result from
217 * 'Do not ask again' checkbox
218 *
219 * \a details more details about the message shown to the user
220 *
221 * \a parent the parent widget of the dialog
222 */
223 virtual void requestUserMessageBox(MessageDialogType type,
224 const QString &text,
225 const QString &title,
226 const QString &primaryActionText,
227 const QString &secondatyActionText,
228 const QString &primaryActionIconName = {},
229 const QString &secondatyActionIconName = {},
230 const QString &dontAskAgainName = {},
231 const QString &details = {},
232 QWidget *parent = nullptr) = 0; // TODO KF6: replace QWidget* with QObject*, document "widget or window"
233
234 /*!
235 * \since 6.0
236 */
237 virtual void askIgnoreSslErrors(const QVariantMap &sslErrorData, QWidget *parent) = 0;
238
239Q_SIGNALS:
240 /*!
241 * Implementations of this interface must emit this signal when the rename dialog
242 * finishes, to notify the caller of the dialog's result.
243 *
244 * \a result the exit code from the rename dialog, one of the KIO::RenameDialog_Result
245 * enum
246 *
247 * \a newUrl the new destination URL set by the user
248 *
249 * \a parentJob the job that invoked the dialog
250 */
251 void askUserRenameResult(KIO::RenameDialog_Result result, const QUrl &newUrl, KJob *parentJob);
252
253 /*!
254 * Implementations of this interface must emit this signal when the skip dialog
255 * finishes, to notify the caller of the dialog's result.
256 *
257 * \a result the exit code from the skip dialog, one of the KIO::SkipDialog_Result enum
258 *
259 * \a parentJob the job that invoked the dialog
260 */
261 void askUserSkipResult(KIO::SkipDialog_Result result, KJob *parentJob);
262
263 /*!
264 * Implementations of this interface must emit this signal when the dialog invoked
265 * by askUserDelete() finishes, to notify the caller of the user's decision.
266 *
267 * \a allowDelete set to true if the user confirmed the delete operation, otherwise
268 * set to false
269 *
270 * \a urls a list of urls to delete/trash
271 *
272 * \a deletionType the deletion type to use, one of KIO::AskUserActionInterface::DeletionType
273 *
274 * \a parent the parent widget passed to askUserDelete(), for request identification
275 */
276 void askUserDeleteResult(bool allowDelete,
277 const QList<QUrl> &urls,
278 KIO::AskUserActionInterface::DeletionType deletionType,
279 QWidget *parent); // TODO KF6: replace QWidget* with QObject*
280
281 /*!
282 * Implementations of this interface must emit this signal when the dialog invoked
283 * by requestUserMessageBox() finishes, to notify the caller of the dialog's result
284 * (exit code).
285 *
286 * \a result the exit code of the dialog, one of KIO::WorkerBase::ButtonCode enum
287 */
288 void messageBoxResult(int result); // TODO KF6: add a QObject* to identify requests? Or return an int from the request method and pass it back here?
289
290 /*!
291 *
292 */
293 void askIgnoreSslErrorsResult(int result);
294
295private:
296 std::unique_ptr<AskUserActionInterfacePrivate> d;
297};
298
299} // namespace KIO
300
301#endif // ASKUSERACTIONINTERFACE_H
302

source code of kio/src/core/askuseractioninterface.h