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

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