KIO

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

KDE's Doxygen guidelines are available online.