KIO

fileundomanager.h
1 /*
2  This file is part of the KDE project
3  SPDX-FileCopyrightText: 2000 Simon Hausmann <[email protected]>
4  SPDX-FileCopyrightText: 2006, 2008 David Faure <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-or-later
7 */
8 
9 #ifndef KIO_FILEUNDOMANAGER_H
10 #define KIO_FILEUNDOMANAGER_H
11 
12 #include <QObject>
13 #include <QUrl>
14 
15 #include "kiowidgets_export.h"
16 
17 #include <memory>
18 
19 class QDateTime;
20 
21 namespace KIO
22 {
23 class Job;
24 class CopyJob;
25 class FileUndoManagerPrivate;
26 class FileUndoManagerSingleton;
27 class CommandRecorder;
28 class UndoCommand;
29 class UndoJob;
30 
31 /**
32  * @class KIO::FileUndoManager fileundomanager.h <KIO/FileUndoManager>
33  *
34  * FileUndoManager: makes it possible to undo kio jobs.
35  * This class is a singleton, use self() to access its only instance.
36  */
37 class KIOWIDGETS_EXPORT FileUndoManager : public QObject
38 {
39  Q_OBJECT
40 public:
41  /**
42  * @return the FileUndoManager instance
43  */
44  static FileUndoManager *self();
45 
46  /**
47  * Interface for the gui handling of FileUndoManager.
48  * This includes three events currently:
49  * - error when undoing a job
50  * - (until KF 5.78) confirm deletion before undoing a copy job
51  * - confirm deletion when the copied file has been modified afterwards
52  *
53  * By default UiInterface shows message boxes in all three cases;
54  * applications can reimplement this interface to provide different user interfaces.
55  */
56  class KIOWIDGETS_EXPORT UiInterface
57  {
58  public:
59  UiInterface();
60  virtual ~UiInterface();
61 
62  /**
63  * Sets whether to show progress info when running the KIO jobs for undoing.
64  */
65  void setShowProgressInfo(bool b);
66  /**
67  * @returns whether progress info dialogs are shown while undoing.
68  */
69  bool showProgressInfo() const;
70 
71  /**
72  * Sets the parent widget to use for message boxes.
73  */
74  void setParentWidget(QWidget *parentWidget);
75 
76  /**
77  * @return the parent widget passed to the last call to undo(parentWidget), or @c nullptr.
78  */
79  QWidget *parentWidget() const;
80 
81  /**
82  * Called when an undo job errors; default implementation displays a message box.
83  */
84  virtual void jobError(KIO::Job *job);
85 
86  /**
87  * Called when we are about to remove those files.
88  * Return true if we should proceed with deleting them.
89  * Deprecated since 5.79, no longer called.
90  */
91  virtual bool confirmDeletion(const QList<QUrl> &files);
92 
93  /**
94  * Called when dest was modified since it was copied from src.
95  * Note that this is called after confirmDeletion.
96  * Return true if we should proceed with deleting dest.
97  */
98  virtual bool copiedFileWasModified(const QUrl &src, const QUrl &dest, const QDateTime &srcTime, const QDateTime &destTime);
99 
100  // TODO KF6 replace hook with virtual AskUserActionInterface* askUserActionInterface(); // (does not take ownership)
101  enum { HookGetAskUserActionInterface = 1 };
102  /**
103  * \internal, for future extensions
104  */
105  virtual void virtual_hook(int id, void *data);
106 
107  private:
108  class UiInterfacePrivate;
109  UiInterfacePrivate *d;
110  };
111 
112  /**
113  * Set a new UiInterface implementation.
114  * This deletes the previous one.
115  * @param ui the UiInterface instance, which becomes owned by the undo manager.
116  */
117  void setUiInterface(UiInterface *ui);
118 
119  /**
120  * @return the UiInterface instance passed to setUiInterface.
121  * This is useful for calling setParentWidget on it. Never delete it!
122  */
123  UiInterface *uiInterface() const;
124 
125  /**
126  * The type of job.
127  */
128  enum CommandType {
129  Copy,
130  Move,
131  Rename,
132  Link,
133  Mkdir,
134  Trash,
135  Put, ///< Represents the creation of a file from data in memory. Used when pasting data from clipboard or drag-n-drop. @since 4.7
136  Mkpath, ///< Represents a KIO::mkpath() job. @since 5.4
137  BatchRename ///< Represents a KIO::batchRename() job. Used when renaming multiple files. @since 5.42
138  };
139 
140  /**
141  * Record this job while it's happening and add a command for it so that the user can undo it.
142  * The signal jobRecordingStarted() is emitted.
143  * @param op the type of job - which is also the type of command that will be created for it
144  * @param src list of source urls. This is empty for Mkdir, Mkpath, Put operations.
145  * @param dst destination url
146  * @param job the job to record
147  */
148  void recordJob(CommandType op, const QList<QUrl> &src, const QUrl &dst, KIO::Job *job);
149 
150  /**
151  * Record this CopyJob while it's happening and add a command for it so that the user can undo it.
152  * The signal jobRecordingStarted() is emitted.
153  */
154  void recordCopyJob(KIO::CopyJob *copyJob);
155 
156 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 79)
157  /**
158  * @return true if undo is possible. Usually used for enabling/disabling the undo action.
159  *
160  * @deprecated since 5.79, use KIO::FileUndoManager::isUndoAvailable()
161  */
162  KIOWIDGETS_DEPRECATED_VERSION(5, 79, "Use KIO::FileUndoManager::isUndoAvailable()")
163  bool undoAvailable() const; // clazy:exclude=overloaded-signal
164 #endif
165 
166  /**
167  * @return true if undo is possible. Usually used for enabling/disabling the undo action.
168  *
169  * @since 5.79
170  */
171  bool isUndoAvailable() const;
172 
173  /**
174  * @return the current text for the undo action.
175  */
176  QString undoText() const;
177 
178  /**
179  * These two functions are useful when wrapping FileUndoManager and adding custom commands.
180  * Each command has a unique ID. You can get a new serial number for a custom command
181  * with newCommandSerialNumber(), and then when you want to undo, check if the command
182  * FileUndoManager would undo is newer or older than your custom command.
183  */
184  quint64 newCommandSerialNumber();
185  quint64 currentCommandSerialNumber() const;
186 
187 public Q_SLOTS:
188  /**
189  * Undoes the last command
190  * Remember to call uiInterface()->setParentWidget(parentWidget) first,
191  * if you have multiple mainwindows.
192  *
193  * This operation is asynchronous.
194  * undoJobFinished will be emitted once the undo is complete.
195  */
196  void undo(); // TODO pass QWindow*, for askUserInterface->askUserDelete and error handling etc.
197 
198 Q_SIGNALS:
199  /// Emitted when the value of isUndoAvailable() changes
200  void undoAvailable(bool avail); // clazy:exclude=overloaded-signal
201 
202  /// Emitted when the value of undoText() changes
203  void undoTextChanged(const QString &text);
204 
205  /// Emitted when an undo job finishes. Used for unit testing.
206  void undoJobFinished();
207 
208  /**
209  * Emitted when a job recording has been started by FileUndoManager::recordJob()
210  * or FileUndoManager::recordCopyJob(). After the job recording has been finished,
211  * the signal jobRecordingFinished() will be emitted.
212  * @since 4.2
213  */
214  void jobRecordingStarted(CommandType op);
215 
216  /**
217  * Emitted when a job that has been recorded by FileUndoManager::recordJob()
218  * or FileUndoManager::recordCopyJob has been finished. The command
219  * is now available for an undo-operation.
220  * @since 4.2
221  */
222  // TODO KF6 signal arg should be fully-qualified
223  void jobRecordingFinished(CommandType op); // clazy:exclude=fully-qualified-moc-types
224 
225 private:
226  FileUndoManager();
227  ~FileUndoManager() override;
228  friend class FileUndoManagerSingleton;
229 
230  friend class UndoJob;
231  friend class CommandRecorder;
232 
233  friend class FileUndoManagerPrivate;
234  std::unique_ptr<FileUndoManagerPrivate> d;
235 };
236 
237 } // namespace
238 
239 #endif
Interface for the gui handling of FileUndoManager.
@ Put
Represents the creation of a file from data in memory. Used when pasting data from clipboard or drag-...
CommandType
The type of job.
A namespace for KIO globals.
@ Mkpath
Represents a KIO::mkpath() job.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Feb 7 2023 04:00:35 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.