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 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 78)
36  RenameDialog_IsDirectory KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 78, "Use RenameDialog_DestIsDirectory.") =
37  128, ///< @deprecated since 5.78, use RenameDialog_DestIsDirectory instead.
38 #endif
39  RenameDialog_DestIsDirectory = 128, ///< The destination is a directory, the dialog updates labels and tooltips accordingly. @since 5.78
40  RenameDialog_SourceIsDirectory = 256, ///< The source is a directory, the dialog updates labels and tooltips accordingly. @since 5.78
41 };
42 /**
43  * Stores a combination of #RenameDialog_Option values.
44  */
46 Q_DECLARE_OPERATORS_FOR_FLAGS(RenameDialog_Options)
47 
48 // For compat
49 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 0)
50 /**
51  * @deprecated since 5.0, use the RenameDialog_Option enum values
52  */
53 enum {
54  M_OVERWRITE KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use RenameDialog_Overwrite.") = RenameDialog_Overwrite,
55  M_OVERWRITE_ITSELF KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use RenameDialog_OverwriteItself.") = RenameDialog_OverwriteItself,
56  M_SKIP KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use RenameDialog_Skip.") = RenameDialog_Skip,
57  M_MULTI KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use RenameDialog_MultipleItems.") = RenameDialog_MultipleItems,
58  M_RESUME KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use RenameDialog_Resume.") = RenameDialog_Resume,
59  M_NORENAME KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use RenameDialog_NoRename.") = RenameDialog_NoRename,
60  M_ISDIR KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use RenameDialog_IsDirectory.") = RenameDialog_IsDirectory,
61 };
62 /**
63  * @deprecated since 5.0, use RenameDialog_Options
64  */
65 KIOCORE_DEPRECATED_VERSION(5, 0, "Use KIO::RenameDialog_Options")
67 #endif
68 
69 /**
70  * @see SkipDialog_Options
71  * @since 5.0
72  */
74  /**
75  * Set if the current operation concerns multiple files, so it makes sense
76  * to offer buttons that apply the user's choice to all files/folders.
77  */
79  /**
80  * Set if the current operation involves copying files/folders with certain
81  * characters in their names that are not supported by the destination
82  * filesystem (e.g.\ VFAT and NTFS disallow "*" in file/folder names).
83  *
84  * This will make the SkipDialog show a "Replace" button that can be used
85  * to instruct the underlying job to replace any problematic character with
86  * an underscore "_".
87  *
88  * @since 5.86
89  */
91 
92  /**
93  * Set if the current operation @e cannot be retried.
94  *
95  * For example if there is an issue that involves the destination filesystem
96  * support, e.g. VFAT and ExFat don't support symlinks, then retrying doesn't
97  * make sense.
98  *
99  * @since 5.88
100  */
102 };
103 /**
104  * Stores a combination of #SkipDialog_Option values.
105  */
107 Q_DECLARE_OPERATORS_FOR_FLAGS(SkipDialog_Options)
108 
109 /**
110  * The result of a rename or skip dialog
111  */
113  Result_Cancel = 0,
114  Result_Rename = 1,
115  Result_Skip = 2,
116  Result_AutoSkip = 3,
117  Result_Overwrite = 4,
118  Result_OverwriteAll = 5,
119  Result_Resume = 6,
120  Result_ResumeAll = 7,
121  Result_AutoRename = 8,
122  Result_Retry = 9,
123  /**
124  * Can be returned only when multiple files are passed, Option overwrite is passed
125  * And files modification times are valid
126  * @since 5.77
127  */
129  /**
130  * Can be returned if the user selects to replace any character disallowed
131  * by the destination filesystem with an underscore "_".
132  *
133  * See @ref SkipDialog_Option::SkipDialog_Replace_Invalid_Chars
134  *
135  * @since 5.86
136  */
138  /**
139  * The same as @c Result_ReplaceInvalidChars, but the user selected to
140  * automatically replace any invalid character, without being asked about
141  * every file/folder.
142  *
143  * @since 5.86
144  */
146 
147 // @deprecated since 5.0, use the undeprecated enum values
148 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 0)
149  R_CANCEL KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use Result_Cancel.") = Result_Cancel,
150  R_RENAME KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use Result_Rename.") = Result_Rename,
151  R_SKIP KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use Result_Skip.") = Result_Skip,
152  R_AUTO_SKIP KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use Result_AutoSkip.") = Result_AutoSkip,
153  R_OVERWRITE KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use Result_Overwrite.") = Result_Overwrite,
154  R_OVERWRITE_ALL KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use Result_OverwriteAll.") = Result_OverwriteAll,
155  R_RESUME KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use Result_Resume.") = Result_Resume,
156  R_RESUME_ALL KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use Result_ResumeAll.") = Result_ResumeAll,
157  R_AUTO_RENAME KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use Result_AutoRename.") = Result_AutoRename,
158  R_RETRY KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use Result_Retry.") = Result_Retry,
159 
160  S_CANCEL KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use Result_Cancel.") = Result_Cancel,
161  S_SKIP KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use Result_Skip.") = Result_Skip,
162  S_AUTO_SKIP KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use Result_AutoSkip.") = Result_AutoSkip,
163  S_RETRY KIOCORE_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 0, "Use Result_Retry.") = Result_Retry,
164 #endif
165 };
166 typedef RenameDialog_Result SkipDialog_Result;
167 
168 /**
169  * @class KIO::JobUiDelegateExtension jobuidelegateextension.h <KIO/JobUiDelegateExtension>
170  *
171  * An abstract class defining interaction with users from KIO jobs:
172  * \li asking what to do in case of a conflict while copying/moving files or directories
173  * \li asking what to do in case of an error while copying/moving files or directories
174  * \li asking for confirmation before deleting files or directories
175  * \li popping up message boxes when the worker requests it
176  * @since 5.0
177  */
178 class KIOCORE_EXPORT JobUiDelegateExtension
179 {
180 protected:
181  /**
182  * Constructor
183  */
185 
186  /**
187  * Destructor
188  */
189  virtual ~JobUiDelegateExtension();
190 
191 public:
192  /**
193  * \relates KIO::RenameDialog
194  * Construct a modal, parent-less "rename" dialog, and return
195  * a result code, as well as the new dest. Much easier to use than the
196  * class RenameDialog directly.
197  *
198  * @param title the title for the dialog box
199  * @param src the URL of the file/dir we're trying to copy, as it's part of the text message
200  * @param dest the URL of the destination file/dir, i.e. the one that already exists
201  * @param options parameters for the dialog (which buttons to show...)
202  * @param newDest the new destination path, valid if R_RENAME was returned.
203  * @param sizeSrc size of source file
204  * @param sizeDest size of destination file
205  * @param ctimeSrc creation time of source file
206  * @param ctimeDest creation time of destination file
207  * @param mtimeSrc modification time of source file
208  * @param mtimeDest modification time of destination file
209  * @return the result
210  */
211  virtual KIO::RenameDialog_Result askFileRename(KJob *job,
212  const QString &title,
213  const QUrl &src,
214  const QUrl &dest,
216  QString &newDest,
217  KIO::filesize_t sizeSrc = KIO::filesize_t(-1),
218  KIO::filesize_t sizeDest = KIO::filesize_t(-1),
219  const QDateTime &ctimeSrc = QDateTime(),
220  const QDateTime &ctimeDest = QDateTime(),
221  const QDateTime &mtimeSrc = QDateTime(),
222  const QDateTime &mtimeDest = QDateTime()) = 0;
223 
224  /**
225  * @internal
226  * See skipdialog.h
227  */
228  virtual KIO::SkipDialog_Result askSkip(KJob *job, KIO::SkipDialog_Options options, const QString &error_text) = 0;
229 
230  /**
231  * The type of deletion: real deletion, moving the files to the trash
232  * or emptying the trash
233  * Used by askDeleteConfirmation.
234  */
235  enum DeletionType { Delete, Trash, EmptyTrash };
236  /**
237  * ForceConfirmation: always ask the user for confirmation
238  * DefaultConfirmation: don't ask the user if he/she said "don't ask again".
239  *
240  * Used by askDeleteConfirmation.
241  */
242  enum ConfirmationType { DefaultConfirmation, ForceConfirmation };
243  /**
244  * Ask for confirmation before deleting/trashing @p urls.
245  *
246  * Note that this method is not called automatically by KIO jobs. It's the application's
247  * responsibility to ask the user for confirmation before calling KIO::del() or KIO::trash().
248  *
249  * @param urls the urls about to be deleted/trashed
250  * @param deletionType the type of deletion (Delete for real deletion, Trash otherwise)
251  * @param confirmationType see ConfirmationType. Normally set to DefaultConfirmation.
252  * Note: the window passed to setWindow is used as the parent for the message box.
253  * @return true if confirmed
254  */
255  virtual bool askDeleteConfirmation(const QList<QUrl> &urls, DeletionType deletionType, ConfirmationType confirmationType) = 0;
256 
257  /**
258  * Message box types.
259  *
260  * Should be kept in sync with WorkerBase::MessageBoxType.
261  *
262  * @since 4.11
263  */
265  QuestionTwoActions = 1, ///< @since 5.100
266  WarningTwoActions = 2, ///< @since 5.100
267  WarningContinueCancel = 3,
268  WarningTwoActionsCancel = 4, ///< @since 5.100
269  Information = 5,
270  SSLMessageBox = 6,
271  // In KMessageBox::DialogType; Sorry = 7, Error = 8, QuestionTwoActionsCancel = 9
272  WarningContinueCancelDetailed = 10,
273 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 100)
274  QuestionYesNo ///< @deprecated Since 5.100, use QuestionTwoActions.
275  KIOCORE_ENUMERATOR_DEPRECATED_VERSION(5, 100, "Use QuestionTwoActions.") = QuestionTwoActions,
276  WarningYesNo ///< @deprecated Since 5.100, use WarningTwoActions.
277  KIOCORE_ENUMERATOR_DEPRECATED_VERSION(5, 100, "Use WarningTwoActions.") = WarningTwoActions,
278  WarningYesNoCancel ///< @deprecated Since 5.100, use WarningTwoActionsCancel.
279  KIOCORE_ENUMERATOR_DEPRECATED_VERSION(5, 100, "Use WarningTwoActionsCancel.") = WarningTwoActionsCancel,
280 #endif
281  };
282 
283  /**
284  * This function allows for the delegation user prompts from the KIO workers.
285  *
286  * @param type the desired type of message box.
287  * @param text the message shown to the user.
288  * @param title the title of the message dialog box.
289  * @param primaryActionText the text for the primary action.
290  * @param secondaryActionText the text for the secondary action.
291  * @param primaryActionIconName the icon shown on the primary action.
292  * @param secondaryActionIconName the icon shown on the secondary action.
293  * @param dontAskAgainName the name used to store result from 'Do not ask again' checkbox.
294  * @param sslMetaData SSL information used by the SSLMessageBox.
295  */
296  virtual int requestMessageBox(MessageBoxType type,
297  const QString &text,
298  const QString &title,
299  const QString &primaryActionText,
300  const QString &secondaryActionText,
301  const QString &primaryActionIconName = QString(),
302  const QString &secondaryActionIconName = QString(),
303  const QString &dontAskAgainName = QString(),
304  const KIO::MetaData &sslMetaData = KIO::MetaData()) = 0;
305 
306  enum ClipboardUpdaterMode {
307  UpdateContent,
308  OverwriteContent,
309  RemoveContent,
310  };
311 
312  /**
313  * Creates a clipboard updater as a child of the given job.
314  */
315  virtual ClipboardUpdater *createClipboardUpdater(Job *job, ClipboardUpdaterMode mode);
316  /**
317  * Update URL in clipboard, if present
318  */
319  virtual void updateUrlInClipboard(const QUrl &src, const QUrl &dest);
320 
321  // TODO KF6: add virtual_hook
322 
323 private:
324  class Private;
325  Private *const d;
326 };
327 
328 /**
329  * Returns the default job UI delegate extension to be used by all KIO jobs (in which HideProgressInfo is not set)
330  * Can return nullptr, if no kio GUI library is loaded.
331  * @since 5.0
332  */
333 KIOCORE_EXPORT JobUiDelegateExtension *defaultJobUiDelegateExtension();
334 
335 /**
336  * Internal. Allows the KIO widgets library to register its widget-based job UI delegate extension
337  * automatically.
338  * @since 5.0
339  */
340 KIOCORE_EXPORT void setDefaultJobUiDelegateExtension(JobUiDelegateExtension *extension);
341 
342 } // namespace KIO
343 
344 #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...
@ RenameDialog_IsDirectory
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 Wed Sep 27 2023 03:49:35 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.