File indexing completed on 2024-07-14 14:33:56

0001 /*
0002     This file is part of the KDE project
0003     SPDX-FileCopyrightText: 2000 Simon Hausmann <hausmann@kde.org>
0004     SPDX-FileCopyrightText: 2006, 2008 David Faure <faure@kde.org>
0005 
0006     SPDX-License-Identifier: LGPL-2.0-or-later
0007 */
0008 
0009 #ifndef KIO_FILEUNDOMANAGER_H
0010 #define KIO_FILEUNDOMANAGER_H
0011 
0012 #include <QObject>
0013 #include <QUrl>
0014 
0015 #include "kiowidgets_export.h"
0016 
0017 #include <memory>
0018 
0019 class QDateTime;
0020 
0021 namespace KIO
0022 {
0023 class Job;
0024 class CopyJob;
0025 class FileUndoManagerPrivate;
0026 class FileUndoManagerSingleton;
0027 class CommandRecorder;
0028 class UndoCommand;
0029 class UndoJob;
0030 
0031 /**
0032  * @class KIO::FileUndoManager fileundomanager.h <KIO/FileUndoManager>
0033  *
0034  * FileUndoManager: makes it possible to undo kio jobs.
0035  * This class is a singleton, use self() to access its only instance.
0036  */
0037 class KIOWIDGETS_EXPORT FileUndoManager : public QObject
0038 {
0039     Q_OBJECT
0040 public:
0041     /**
0042      * @return the FileUndoManager instance
0043      */
0044     static FileUndoManager *self();
0045 
0046     /**
0047      * Interface for the gui handling of FileUndoManager.
0048      * This includes three events currently:
0049      * - error when undoing a job
0050      * - (until KF 5.78) confirm deletion before undoing a copy job
0051      * - confirm deletion when the copied file has been modified afterwards
0052      *
0053      * By default UiInterface shows message boxes in all three cases;
0054      * applications can reimplement this interface to provide different user interfaces.
0055      */
0056     class KIOWIDGETS_EXPORT UiInterface
0057     {
0058     public:
0059         UiInterface();
0060         virtual ~UiInterface();
0061 
0062         /**
0063          * Sets whether to show progress info when running the KIO jobs for undoing.
0064          */
0065         void setShowProgressInfo(bool b);
0066         /**
0067          * @returns whether progress info dialogs are shown while undoing.
0068          */
0069         bool showProgressInfo() const;
0070 
0071         /**
0072          * Sets the parent widget to use for message boxes.
0073          */
0074         void setParentWidget(QWidget *parentWidget);
0075 
0076         /**
0077          * @return the parent widget passed to the last call to undo(parentWidget), or @c nullptr.
0078          */
0079         QWidget *parentWidget() const;
0080 
0081         /**
0082          * Called when an undo job errors; default implementation displays a message box.
0083          */
0084         virtual void jobError(KIO::Job *job);
0085 
0086         /**
0087          * Called when we are about to remove those files.
0088          * Return true if we should proceed with deleting them.
0089          * Deprecated since 5.79, no longer called.
0090          */
0091         virtual bool confirmDeletion(const QList<QUrl> &files);
0092 
0093         /**
0094          * Called when dest was modified since it was copied from src.
0095          * Note that this is called after confirmDeletion.
0096          * Return true if we should proceed with deleting dest.
0097          */
0098         virtual bool copiedFileWasModified(const QUrl &src, const QUrl &dest, const QDateTime &srcTime, const QDateTime &destTime);
0099 
0100         // TODO KF6 replace hook with virtual AskUserActionInterface* askUserActionInterface(); // (does not take ownership)
0101         enum { HookGetAskUserActionInterface = 1 };
0102         /**
0103          * \internal, for future extensions
0104          */
0105         virtual void virtual_hook(int id, void *data);
0106 
0107     private:
0108         class UiInterfacePrivate;
0109         UiInterfacePrivate *d;
0110     };
0111 
0112     /**
0113      * Set a new UiInterface implementation.
0114      * This deletes the previous one.
0115      * @param ui the UiInterface instance, which becomes owned by the undo manager.
0116      */
0117     void setUiInterface(UiInterface *ui);
0118 
0119     /**
0120      * @return the UiInterface instance passed to setUiInterface.
0121      * This is useful for calling setParentWidget on it. Never delete it!
0122      */
0123     UiInterface *uiInterface() const;
0124 
0125     /**
0126      * The type of job.
0127      */
0128     enum CommandType {
0129         Copy,
0130         Move,
0131         Rename,
0132         Link,
0133         Mkdir,
0134         Trash,
0135         Put, ///< Represents the creation of a file from data in memory. Used when pasting data from clipboard or drag-n-drop. @since 4.7
0136         Mkpath, ///< Represents a KIO::mkpath() job. @since 5.4
0137         BatchRename ///< Represents a KIO::batchRename() job. Used when renaming multiple files. @since 5.42
0138     };
0139 
0140     /**
0141      * Record this job while it's happening and add a command for it so that the user can undo it.
0142      * The signal jobRecordingStarted() is emitted.
0143      * @param op the type of job - which is also the type of command that will be created for it
0144      * @param src list of source urls. This is empty for Mkdir, Mkpath, Put operations.
0145      * @param dst destination url
0146      * @param job the job to record
0147      */
0148     void recordJob(CommandType op, const QList<QUrl> &src, const QUrl &dst, KIO::Job *job);
0149 
0150     /**
0151      * Record this CopyJob while it's happening and add a command for it so that the user can undo it.
0152      * The signal jobRecordingStarted() is emitted.
0153      */
0154     void recordCopyJob(KIO::CopyJob *copyJob);
0155 
0156 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 79)
0157     /**
0158      * @return true if undo is possible. Usually used for enabling/disabling the undo action.
0159      *
0160      * @deprecated since 5.79, use KIO::FileUndoManager::isUndoAvailable()
0161      */
0162     KIOWIDGETS_DEPRECATED_VERSION(5, 79, "Use KIO::FileUndoManager::isUndoAvailable()")
0163     bool undoAvailable() const; // clazy:exclude=overloaded-signal
0164 #endif
0165 
0166     /**
0167      * @return true if undo is possible. Usually used for enabling/disabling the undo action.
0168      *
0169      * @since 5.79
0170      */
0171     bool isUndoAvailable() const;
0172 
0173     /**
0174      * @return the current text for the undo action.
0175      */
0176     QString undoText() const;
0177 
0178     /**
0179      * These two functions are useful when wrapping FileUndoManager and adding custom commands.
0180      * Each command has a unique ID. You can get a new serial number for a custom command
0181      * with newCommandSerialNumber(), and then when you want to undo, check if the command
0182      * FileUndoManager would undo is newer or older than your custom command.
0183      */
0184     quint64 newCommandSerialNumber();
0185     quint64 currentCommandSerialNumber() const;
0186 
0187 public Q_SLOTS:
0188     /**
0189      * Undoes the last command
0190      * Remember to call uiInterface()->setParentWidget(parentWidget) first,
0191      * if you have multiple mainwindows.
0192      *
0193      * This operation is asynchronous.
0194      * undoJobFinished will be emitted once the undo is complete.
0195      */
0196     void undo(); // TODO pass QWindow*, for askUserInterface->askUserDelete and error handling etc.
0197 
0198 Q_SIGNALS:
0199     /// Emitted when the value of isUndoAvailable() changes
0200     void undoAvailable(bool avail); // clazy:exclude=overloaded-signal
0201 
0202     /// Emitted when the value of undoText() changes
0203     void undoTextChanged(const QString &text);
0204 
0205     /// Emitted when an undo job finishes. Used for unit testing.
0206     void undoJobFinished();
0207 
0208     /**
0209      * Emitted when a job recording has been started by FileUndoManager::recordJob()
0210      * or FileUndoManager::recordCopyJob(). After the job recording has been finished,
0211      * the signal jobRecordingFinished() will be emitted.
0212      * @since 4.2
0213      */
0214     void jobRecordingStarted(CommandType op);
0215 
0216     /**
0217      * Emitted when a job that has been recorded by FileUndoManager::recordJob()
0218      * or FileUndoManager::recordCopyJob has been finished. The command
0219      * is now available for an undo-operation.
0220      * @since 4.2
0221      */
0222     // TODO KF6 signal arg should be fully-qualified
0223     void jobRecordingFinished(CommandType op); // clazy:exclude=fully-qualified-moc-types
0224 
0225 private:
0226     KIOWIDGETS_NO_EXPORT FileUndoManager();
0227     KIOWIDGETS_NO_EXPORT ~FileUndoManager() override;
0228     friend class FileUndoManagerSingleton;
0229 
0230     friend class UndoJob;
0231     friend class CommandRecorder;
0232 
0233     friend class FileUndoManagerPrivate;
0234     std::unique_ptr<FileUndoManagerPrivate> d;
0235 };
0236 
0237 } // namespace
0238 
0239 #endif