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 caption 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 &caption,
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 
118  /**
119  * Deletion confirmation type.
120  *
121  * Used by askUserDelete().
122  */
124  DefaultConfirmation, ///< Do not ask if the user has previously set the "Do not ask again"
125  ///< checkbox (which is is shown in the message dialog invoked by askUserDelete())
126  ForceConfirmation, ///< Always ask the user for confirmation
127  };
128 
129  /**
130  * Ask for confirmation before moving @p urls (files/directories) to the Trash,
131  * emptying the Trash, or directly deleting files (i.e. without moving to Trash).
132  *
133  * Note that this method is not called automatically by KIO jobs. It's the
134  * application's responsibility to ask the user for confirmation before calling
135  * KIO::del() or KIO::trash().
136  *
137  * You need to connect to the askUserDeleteResult signal to get the dialog's result
138  * (exit code).
139  *
140  * @param urls the urls about to be moved to the Trash or deleted directly
141  * @param deletionType the type of deletion (Delete for real deletion, Trash otherwise),
142  * see the DeletionType enum
143  * @param confirmationType The type of deletion confirmation, see the ConfirmationType enum.
144  * Normally set to DefaultConfirmation
145  * @param parent the parent widget of the message box
146  */
147  virtual void askUserDelete(const QList<QUrl> &urls,
148  DeletionType deletionType,
149  ConfirmationType confirmationType,
150  QWidget *parent = nullptr) = 0; // TODO KF6: replace QWidget* with QObject*
151 
152  enum MessageDialogType {
153  QuestionYesNo = 1,
154  QuestionYesNoCancel = 2,
155  WarningYesNo = 3,
156  WarningYesNoCancel = 4,
157  WarningContinueCancel = 5,
158  SSLMessageBox = 6,
159  Information = 7,
160  Sorry = 8,
161  Error = 9,
162  };
163 
164  /**
165  * This function allows for the delegation of user prompts from the ioslaves.
166  *
167  * @param type the desired type of message box, see the MessageDialogType enum
168  * @param text the message to show to the user
169  * @param caption the title of the message dialog box
170  * @param buttonYes the text for the YES button
171  * @param buttonNo the text for the NO button
172  * @param iconYes the icon to show on the YES button
173  * @param iconNo the icon to show on the NO button
174  * @param dontAskAgainName the config key name used to store the result from
175  * 'Do not ask again' checkbox
176  * @param details more details about the message shown to the user
177  * @param sslMetaData SSL information primarily used by the SSLMessageBox dialog
178  * @param parent the parent widget of the dialog
179  */
180  virtual void requestUserMessageBox(MessageDialogType type,
181  const QString &text,
182  const QString &caption,
183  const QString &buttonYes,
184  const QString &buttonNo,
185  const QString &iconYes = {},
186  const QString &iconNo = {},
187  const QString &dontAskAgainName = {},
188  const QString &details = {},
189  const KIO::MetaData &sslMetaData = {},
190  QWidget *parent = nullptr) = 0; // TODO KF6: replace QWidget* with QObject*, document "widget or window"
191 
192 Q_SIGNALS:
193  /**
194  * Implementations of this interface must emit this signal when the rename dialog
195  * finishes, to notify the caller of the dialog's result.
196  *
197  * @param result the exit code from the rename dialog, one of the KIO::RenameDialog_Result
198  * enum
199  * @param newUrl the new destination URL set by the user
200  * @param parentJob the job that invoked the dialog
201  */
202  void askUserRenameResult(KIO::RenameDialog_Result result, const QUrl &newUrl, KJob *parentJob);
203 
204  /**
205  * Implementations of this interface must emit this signal when the skip dialog
206  * finishes, to notify the caller of the dialog's result.
207  *
208  * @param result the exit code from the skip dialog, one of the KIO::SkipDialog_Result enum
209  * @param parentJob the job that invoked the dialog
210  */
211  void askUserSkipResult(KIO::SkipDialog_Result result, KJob *parentJob);
212 
213  /**
214  * Implementations of this interface must emit this signal when the dialog invoked
215  * by askUserDelete() finishes, to notify the caller of the user's decision.
216  *
217  * @param allowDelete set to true if the user confirmed the delete operation, otherwise
218  * set to false
219  * @param urls a list of urls to delete/trash
220  * @param deletionType the deletion type to use, one of KIO::AskUserActionInterface::DeletionType
221  * @param parent the parent widget passed to askUserDelete(), for request identification
222  */
223  void askUserDeleteResult(bool allowDelete,
224  const QList<QUrl> &urls,
226  QWidget *parent); // TODO KF6: replace QWidget* with QObject*
227 
228  /**
229  * Implementations of this interface must emit this signal when the dialog invoked
230  * by requestUserMessageBox() finishes, to notify the caller of the dialog's result
231  * (exit code).
232  *
233  * @param result the exit code of the dialog, one of KIO::SlaveBase::ButtonCode enum
234  */
235  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?
236 
237 private:
238  std::unique_ptr<AskUserActionInterfacePrivate> d;
239 };
240 
241 } // namespace KIO
242 
243 #endif // ASKUSERACTIONINTERFACE_H
qulonglong filesize_t
64-bit file size
Definition: global.h:39
A namespace for KIO globals.
ConfirmationType
Deletion confirmation type.
Error
Error codes that can be emitted by KIO.
Definition: global.h:144
MetaData is a simple map of key/value strings.
Definition: metadata.h:22
Move the files/directories to Trash.
Always ask the user for confirmation.
PartitionTable::TableType type
Delete the files/directories directly, i.e. without moving them to Trash.
The AskUserActionInterface class allows a KIO::Job to prompt the user for a decision when e...
RenameDialog_Result
The result of a rename or skip dialog.
DeletionType
The type of deletion.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Mon Jan 17 2022 22:53:32 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.