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 | |
21 | class KJob; |
22 | |
23 | namespace KIO |
24 | { |
25 | class 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 | */ |
45 | class KIOCORE_EXPORT AskUserActionInterface : public QObject |
46 | { |
47 | Q_OBJECT |
48 | |
49 | protected: |
50 | /*! |
51 | * Constructor |
52 | */ |
53 | explicit AskUserActionInterface(QObject *parent = nullptr); |
54 | |
55 | public: |
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 | |
239 | Q_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 | |
295 | private: |
296 | std::unique_ptr<AskUserActionInterfacePrivate> d; |
297 | }; |
298 | |
299 | } // namespace KIO |
300 | |
301 | #endif // ASKUSERACTIONINTERFACE_H |
302 | |