KIO

jobuidelegateextension.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 2000 Stephan Kulow <[email protected]>
4  SPDX-FileCopyrightText: 2000-2013 David Faure <[email protected]>
5  SPDX-FileCopyrightText: 2006 Kevin Ottens <[email protected]>
6 
7  SPDX-License-Identifier: LGPL-2.0-or-later
8 */
9 
10 #ifndef KIO_JOBUIDELEGATEEXTENSION_H
11 #define KIO_JOBUIDELEGATEEXTENSION_H
12 
13 #include "kiocore_export.h"
14 #include <QDateTime>
15 #include <kio/global.h>
16 
17 class KJob;
18 namespace KIO
19 {
20 class Job;
21 class ClipboardUpdater;
22 
23 /**
24  * @see RenameDialog_Options
25  * @since 5.0
26  */
28  RenameDialog_Overwrite = 1, ///< We have an existing destination, show details about it and offer to overwrite it.
29  RenameDialog_OverwriteItself = 2, ///< Warn that the current operation would overwrite a file with itself, which is not allowed.
30  RenameDialog_Skip = 4, ///< Offer a "Skip" button, to skip other files too. Requires RenameDialog_MultipleItems.
32  8, ///< Set if the current operation concerns multiple files, so it makes sense to offer buttons that apply the user's choice to all files/folders.
33  RenameDialog_Resume = 16, ///< Offer a "Resume" button (plus "Resume All" if RenameDialog_MultipleItems).
34  RenameDialog_NoRename = 64, ///< Don't offer a "Rename" button.
35  RenameDialog_DestIsDirectory = 128, ///< The destination is a directory, the dialog updates labels and tooltips accordingly. @since 5.78
36  RenameDialog_SourceIsDirectory = 256, ///< The source is a directory, the dialog updates labels and tooltips accordingly. @since 5.78
37 };
38 /**
39  * Stores a combination of #RenameDialog_Option values.
40  */
42 Q_DECLARE_OPERATORS_FOR_FLAGS(RenameDialog_Options)
43 
44 /**
45  * @see SkipDialog_Options
46  * @since 5.0
47  */
49  /**
50  * Set if the current operation concerns multiple files, so it makes sense
51  * to offer buttons that apply the user's choice to all files/folders.
52  */
54  /**
55  * Set if the current operation involves copying files/folders with certain
56  * characters in their names that are not supported by the destination
57  * filesystem (e.g.\ VFAT and NTFS disallow "*" in file/folder names).
58  *
59  * This will make the SkipDialog show a "Replace" button that can be used
60  * to instruct the underlying job to replace any problematic character with
61  * an underscore "_".
62  *
63  * @since 5.86
64  */
66 
67  /**
68  * Set if the current operation @e cannot be retried.
69  *
70  * For example if there is an issue that involves the destination filesystem
71  * support, e.g. VFAT and ExFat don't support symlinks, then retrying doesn't
72  * make sense.
73  *
74  * @since 5.88
75  */
77 };
78 /**
79  * Stores a combination of #SkipDialog_Option values.
80  */
82 Q_DECLARE_OPERATORS_FOR_FLAGS(SkipDialog_Options)
83 
84 /**
85  * The result of a rename or skip dialog
86  */
88  Result_Cancel = 0,
89  Result_Rename = 1,
90  Result_Skip = 2,
91  Result_AutoSkip = 3,
92  Result_Overwrite = 4,
93  Result_OverwriteAll = 5,
94  Result_Resume = 6,
95  Result_ResumeAll = 7,
96  Result_AutoRename = 8,
97  Result_Retry = 9,
98  /**
99  * Can be returned only when multiple files are passed, Option overwrite is passed
100  * And files modification times are valid
101  * @since 5.77
102  */
104  /**
105  * Can be returned if the user selects to replace any character disallowed
106  * by the destination filesystem with an underscore "_".
107  *
108  * See @ref SkipDialog_Option::SkipDialog_Replace_Invalid_Chars
109  *
110  * @since 5.86
111  */
113  /**
114  * The same as @c Result_ReplaceInvalidChars, but the user selected to
115  * automatically replace any invalid character, without being asked about
116  * every file/folder.
117  *
118  * @since 5.86
119  */
121 };
122 typedef RenameDialog_Result SkipDialog_Result;
123 
124 /**
125  * @class KIO::JobUiDelegateExtension jobuidelegateextension.h <KIO/JobUiDelegateExtension>
126  *
127  * An abstract class defining interaction with users from KIO jobs:
128  * \li asking what to do in case of a conflict while copying/moving files or directories
129  * \li asking what to do in case of an error while copying/moving files or directories
130  * \li asking for confirmation before deleting files or directories
131  * \li popping up message boxes when the worker requests it
132  * @since 5.0
133  */
134 class KIOCORE_EXPORT JobUiDelegateExtension
135 {
136 protected:
137  /**
138  * Constructor
139  */
141 
142  /**
143  * Destructor
144  */
145  virtual ~JobUiDelegateExtension();
146 
147 public:
148  /**
149  * \relates KIO::RenameDialog
150  * Construct a modal, parent-less "rename" dialog, and return
151  * a result code, as well as the new dest. Much easier to use than the
152  * class RenameDialog directly.
153  *
154  * @param title the title for the dialog box
155  * @param src the URL of the file/dir we're trying to copy, as it's part of the text message
156  * @param dest the URL of the destination file/dir, i.e. the one that already exists
157  * @param options parameters for the dialog (which buttons to show...)
158  * @param newDest the new destination path, valid if R_RENAME was returned.
159  * @param sizeSrc size of source file
160  * @param sizeDest size of destination file
161  * @param ctimeSrc creation time of source file
162  * @param ctimeDest creation time of destination file
163  * @param mtimeSrc modification time of source file
164  * @param mtimeDest modification time of destination file
165  * @return the result
166  */
167  virtual KIO::RenameDialog_Result askFileRename(KJob *job,
168  const QString &title,
169  const QUrl &src,
170  const QUrl &dest,
172  QString &newDest,
173  KIO::filesize_t sizeSrc = KIO::filesize_t(-1),
174  KIO::filesize_t sizeDest = KIO::filesize_t(-1),
175  const QDateTime &ctimeSrc = QDateTime(),
176  const QDateTime &ctimeDest = QDateTime(),
177  const QDateTime &mtimeSrc = QDateTime(),
178  const QDateTime &mtimeDest = QDateTime()) = 0;
179 
180  /**
181  * @internal
182  * See skipdialog.h
183  */
184  virtual KIO::SkipDialog_Result askSkip(KJob *job, KIO::SkipDialog_Options options, const QString &error_text) = 0;
185 
186  /**
187  * The type of deletion: real deletion, moving the files to the trash
188  * or emptying the trash
189  * Used by askDeleteConfirmation.
190  */
191  enum DeletionType { Delete, Trash, EmptyTrash };
192  /**
193  * ForceConfirmation: always ask the user for confirmation
194  * DefaultConfirmation: don't ask the user if he/she said "don't ask again".
195  *
196  * Used by askDeleteConfirmation.
197  */
198  enum ConfirmationType { DefaultConfirmation, ForceConfirmation };
199  /**
200  * Ask for confirmation before deleting/trashing @p urls.
201  *
202  * Note that this method is not called automatically by KIO jobs. It's the application's
203  * responsibility to ask the user for confirmation before calling KIO::del() or KIO::trash().
204  *
205  * @param urls the urls about to be deleted/trashed
206  * @param deletionType the type of deletion (Delete for real deletion, Trash otherwise)
207  * @param confirmationType see ConfirmationType. Normally set to DefaultConfirmation.
208  * Note: the window passed to setWindow is used as the parent for the message box.
209  * @return true if confirmed
210  */
211  virtual bool askDeleteConfirmation(const QList<QUrl> &urls, DeletionType deletionType, ConfirmationType confirmationType) = 0;
212 
213  /**
214  * Message box types.
215  *
216  * Should be kept in sync with WorkerBase::MessageBoxType.
217  *
218  * @since 4.11
219  */
221  QuestionTwoActions = 1, ///< @since 5.100
222  WarningTwoActions = 2, ///< @since 5.100
223  WarningContinueCancel = 3,
224  WarningTwoActionsCancel = 4, ///< @since 5.100
225  Information = 5,
226  SSLMessageBox = 6,
227  // In KMessageBox::DialogType; <unused> = 7, Error = 8,
228  // QuestionTwoActionsCancel = 9
229  WarningContinueCancelDetailed = 10,
230  };
231 
232  /**
233  * This function allows for the delegation user prompts from the KIO workers.
234  *
235  * @param type the desired type of message box.
236  * @param text the message shown to the user.
237  * @param title the title of the message dialog box.
238  * @param primaryActionText the text for the primary action.
239  * @param secondaryActionText the text for the secondary action.
240  * @param primaryActionIconName the icon shown on the primary action.
241  * @param secondaryActionIconName the icon shown on the secondary action.
242  * @param dontAskAgainName the name used to store result from 'Do not ask again' checkbox.
243  * @param sslMetaData SSL information used by the SSLMessageBox.
244  */
245  virtual int requestMessageBox(MessageBoxType type,
246  const QString &text,
247  const QString &title,
248  const QString &primaryActionText,
249  const QString &secondaryActionText,
250  const QString &primaryActionIconName = QString(),
251  const QString &secondaryActionIconName = QString(),
252  const QString &dontAskAgainName = QString(),
253  const KIO::MetaData &sslMetaData = KIO::MetaData()) = 0;
254 
255  enum ClipboardUpdaterMode {
256  UpdateContent,
257  OverwriteContent,
258  RemoveContent,
259  };
260 
261  /**
262  * Creates a clipboard updater as a child of the given job.
263  */
264  virtual ClipboardUpdater *createClipboardUpdater(Job *job, ClipboardUpdaterMode mode);
265  /**
266  * Update URL in clipboard, if present
267  */
268  virtual void updateUrlInClipboard(const QUrl &src, const QUrl &dest);
269 
270  // TODO KF6: add virtual_hook
271 
272 private:
273  class Private;
274  Private *const d;
275 };
276 
277 /**
278  * Returns the default job UI delegate extension to be used by all KIO jobs (in which HideProgressInfo is not set)
279  * Can return nullptr, if no kio GUI library is loaded.
280  * @since 5.0
281  */
282 KIOCORE_EXPORT JobUiDelegateExtension *defaultJobUiDelegateExtension();
283 
284 /**
285  * Internal. Allows the KIO widgets library to register its widget-based job UI delegate extension
286  * automatically.
287  * @since 5.0
288  */
289 KIOCORE_EXPORT void setDefaultJobUiDelegateExtension(JobUiDelegateExtension *extension);
290 
291 } // namespace KIO
292 
293 #endif
DeletionType
The type of deletion: real deletion, moving the files to the trash or emptying the trash Used by askD...
qulonglong filesize_t
64-bit file size
Definition: global.h:39
@ RenameDialog_NoRename
Don't offer a "Rename" button.
@ Result_OverwriteWhenOlder
Can be returned only when multiple files are passed, Option overwrite is passed And files modificatio...
KIOCORE_EXPORT void setDefaultJobUiDelegateExtension(JobUiDelegateExtension *extension)
Internal.
@ RenameDialog_SourceIsDirectory
The source is a directory, the dialog updates labels and tooltips accordingly.
@ SkipDialog_Replace_Invalid_Chars
Set if the current operation involves copying files/folders with certain characters in their names th...
@ SkipDialog_Hide_Retry
Set if the current operation cannot be retried.
@ RenameDialog_DestIsDirectory
The destination is a directory, the dialog updates labels and tooltips accordingly.
@ RenameDialog_Overwrite
We have an existing destination, show details about it and offer to overwrite it.
ConfirmationType
ForceConfirmation: always ask the user for confirmation DefaultConfirmation: don't ask the user if he...
@ RenameDialog_OverwriteItself
Warn that the current operation would overwrite a file with itself, which is not allowed.
@ Result_ReplaceAllInvalidChars
The same as Result_ReplaceInvalidChars, but the user selected to automatically replace any invalid ch...
@ SkipDialog_MultipleItems
Set if the current operation concerns multiple files, so it makes sense to offer buttons that apply t...
A namespace for KIO globals.
KIOCORE_EXPORT JobUiDelegateExtension * defaultJobUiDelegateExtension()
Returns the default job UI delegate extension to be used by all KIO jobs (in which HideProgressInfo i...
@ RenameDialog_MultipleItems
Set if the current operation concerns multiple files, so it makes sense to offer buttons that apply t...
RenameDialog_Result
The result of a rename or skip dialog.
@ RenameDialog_Skip
Offer a "Skip" button, to skip other files too. Requires RenameDialog_MultipleItems.
@ RenameDialog_Resume
Offer a "Resume" button (plus "Resume All" if RenameDialog_MultipleItems).
@ Result_ReplaceInvalidChars
Can be returned if the user selects to replace any character disallowed by the destination filesystem...
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Jun 9 2023 03:52:42 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.