1/* This file is part of the KDE project
2 Copyright (C) 2000 Simon Hausmann <hausmann@kde.org>
3 Copyright (C) 2006, 2008 David Faure <faure@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20#ifndef KIO_FILEUNDOMANAGER_H
21#define KIO_FILEUNDOMANAGER_H
22
23#include <QtCore/QObject>
24#include <kurl.h>
25
26#include <kio/kio_export.h>
27
28class KDateTime;
29
30namespace KIO
31{
32class Job;
33class CopyJob;
34class FileUndoManagerPrivate;
35class FileUndoManagerSingleton;
36class CommandRecorder;
37class UndoCommand;
38class UndoJob;
39
40/**
41 * FileUndoManager: makes it possible to undo kio jobs.
42 * This class is a singleton, use self() to access its only instance.
43 */
44class KIO_EXPORT FileUndoManager : public QObject
45{
46 Q_OBJECT
47public:
48 /**
49 * @return the FileUndoManager instance
50 */
51 static FileUndoManager *self();
52
53 /**
54 * Interface for the gui handling of FileUndoManager.
55 * This includes three events currently:
56 * - error when undoing a job
57 * - confirm deletion before undoing a copy job
58 * - confirm deletion when the copied file has been modified afterwards
59 *
60 * By default UiInterface shows message boxes in all three cases;
61 * applications can reimplement this interface to provide different user interfaces.
62 */
63 class KIO_EXPORT UiInterface
64 {
65 public:
66 UiInterface();
67 virtual ~UiInterface();
68
69 /**
70 * Sets whether to show progress info when running the KIO jobs for undoing.
71 */
72 void setShowProgressInfo(bool b);
73 /**
74 * @returns whether progress info dialogs are shown while undoing.
75 */
76 bool showProgressInfo() const;
77
78 /**
79 * Sets the parent widget to use for message boxes.
80 */
81 void setParentWidget(QWidget* parentWidget);
82
83 /**
84 * @return the parent widget passed to the last call to undo(parentWidget), or 0.
85 */
86 QWidget* parentWidget() const;
87
88 /**
89 * Called when an undo job errors; default implementation displays a message box.
90 */
91 virtual void jobError(KIO::Job* job);
92
93 /**
94 * Called when we are about to remove those files.
95 * Return true if we should proceed with deleting them.
96 */
97 virtual bool confirmDeletion(const KUrl::List& files);
98
99 /**
100 * Called when dest was modified since it was copied from src.
101 * Note that this is called after confirmDeletion.
102 * Return true if we should proceed with deleting dest.
103 */
104 virtual bool copiedFileWasModified(const KUrl& src, const KUrl& dest, const KDateTime& srcTime, const KDateTime& destTime);
105
106 /**
107 * \internal, for future extensions
108 */
109 virtual void virtual_hook(int id, void* data);
110
111 private:
112 class UiInterfacePrivate;
113 UiInterfacePrivate *d;
114 };
115
116 /**
117 * Set a new UiInterface implementation.
118 * This deletes the previous one.
119 * @param ui the UiInterface instance, which becomes owned by the undo manager.
120 */
121 void setUiInterface(UiInterface* ui);
122
123 /**
124 * @return the UiInterface instance passed to setUiInterface.
125 * This is useful for calling setParentWidget on it. Never delete it!
126 */
127 UiInterface* uiInterface() const;
128
129 /**
130 * The type of job.
131 *
132 * Put: @since 4.7, represents the creation of a file from data in memory.
133 * Used when pasting data from clipboard or drag-n-drop.
134 */
135 enum CommandType { Copy, Move, Rename, Link, Mkdir, Trash, Put };
136
137 /**
138 * Record this job while it's happening and add a command for it so that the user can undo it.
139 * The signal jobRecordingStarted() is emitted.
140 * @param op the type of job - which is also the type of command that will be created for it
141 * @param src list of source urls
142 * @param dst destination url
143 * @param job the job to record
144 */
145 void recordJob(CommandType op, const KUrl::List &src, const KUrl &dst, KIO::Job *job);
146
147 /**
148 * Record this CopyJob while it's happening and add a command for it so that the user can undo it.
149 * The signal jobRecordingStarted() is emitted.
150 */
151 void recordCopyJob(KIO::CopyJob* copyJob);
152
153 /**
154 * @return true if undo is possible. Usually used for enabling/disabling the undo action.
155 */
156 bool undoAvailable() const;
157 /**
158 * @return the current text for the undo action.
159 */
160 QString undoText() const;
161
162 /**
163 * These two functions are useful when wrapping FileUndoManager and adding custom commands.
164 * Each command has a unique ID. You can get a new serial number for a custom command
165 * with newCommandSerialNumber(), and then when you want to undo, check if the command
166 * FileUndoManager would undo is newer or older than your custom command.
167 */
168 quint64 newCommandSerialNumber();
169 quint64 currentCommandSerialNumber() const;
170
171public Q_SLOTS:
172 /**
173 * Undoes the last command
174 * Remember to call uiInterface()->setParentWidget(parentWidget) first,
175 * if you have multiple mainwindows.
176 */
177 void undo();
178
179Q_SIGNALS:
180 /// Emitted when the value of undoAvailable() changes
181 void undoAvailable(bool avail);
182
183 /// Emitted when the value of undoText() changes
184 void undoTextChanged(const QString &text);
185
186 /// Emitted when an undo job finishes. Used for unit testing.
187 void undoJobFinished();
188
189 /**
190 * Emitted when a job recording has been started by FileUndoManager::recordJob()
191 * or FileUndoManager::recordCopyJob(). After the job recording has been finished,
192 * the signal jobRecordingFinished() will be emitted.
193 * @since 4.2
194 */
195 void jobRecordingStarted(CommandType op);
196
197 /**
198 * Emitted when a job that has been recorded by FileUndoManager::recordJob()
199 * or FileUndoManager::recordCopyJob has been finished. The command
200 * is now available for an undo-operation.
201 * @since 4.2
202 */
203 void jobRecordingFinished(CommandType op);
204
205private:
206 FileUndoManager();
207 virtual ~FileUndoManager();
208 friend class FileUndoManagerSingleton;
209
210 friend class UndoJob;
211 friend class CommandRecorder;
212
213 friend class FileUndoManagerPrivate;
214 FileUndoManagerPrivate *d;
215};
216
217} // namespace
218
219#endif
220