File indexing completed on 2024-07-14 03:53:46

0001 /*
0002     This file is part of the KDE libraries
0003     SPDX-FileCopyrightText: 2020 Ahmad Samir <a.samirh78@gmail.com>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
0006 */
0007 
0008 #ifndef ASKUSERACTIONINTERFACE_H
0009 #define ASKUSERACTIONINTERFACE_H
0010 
0011 #include <kio/jobuidelegateextension.h> // RenameDialog_Result, SkipDialog_Result
0012 #include <kiocore_export.h>
0013 
0014 #include <QObject>
0015 #include <QUrl>
0016 
0017 #include <QSsl>
0018 
0019 #include <memory>
0020 
0021 class KJob;
0022 
0023 namespace KIO
0024 {
0025 class AskUserActionInterfacePrivate;
0026 
0027 /**
0028  * @class KIO::AskUserActionInterface askuseractioninterface.h <KIO/AskUserActionInterface>
0029  *
0030  * @brief The AskUserActionInterface class allows a KIO::Job to prompt the user
0031  * for a decision when e.g.\ copying directories/files and there is a conflict
0032  * (e.g.\ a file with the same name already exists at the destination).
0033  *
0034  * The methods in this interface are similar to their counterparts in
0035  * KIO::JobUiDelegateExtension, the main difference is that AskUserActionInterface
0036  * shows the dialogs using show() or open(), rather than exec(), the latter creates
0037  * a nested event loop which could lead to crashes.
0038  *
0039  * @sa KIO::JobUiDelegateExtension
0040  *
0041  * @since 5.78
0042  */
0043 class KIOCORE_EXPORT AskUserActionInterface : public QObject
0044 {
0045     Q_OBJECT
0046 
0047 protected:
0048     /**
0049      * Constructor
0050      */
0051     explicit AskUserActionInterface(QObject *parent = nullptr);
0052 
0053 public:
0054     /**
0055      * Destructor
0056      */
0057     ~AskUserActionInterface() override;
0058 
0059     /**
0060      * @relates KIO::RenameDialog
0061      *
0062      * Constructs a modal, parent-less "rename" dialog, to prompt the user for a decision
0063      * in case of conflicts, while copying/moving files. The dialog is shown using open(),
0064      * rather than exec() (the latter creates a nested eventloop which could lead to crashes).
0065      * You will need to connect to the askUserRenameResult() signal to get the dialog's result
0066      * (exit code). The exit code is one of KIO::RenameDialog_Result.
0067      *
0068      * @see KIO::RenameDialog_Result enum.
0069      *
0070      * @param job the job that called this method
0071      * @param title the title for the dialog box
0072      * @param src the URL of the file/dir being copied/moved
0073      * @param dest the URL of the destination file/dir, i.e. the one that already exists
0074      * @param options parameters for the dialog (which buttons to show... etc), OR'ed values
0075      *            from the KIO::RenameDialog_Options enum
0076      * @param sizeSrc size of the source file
0077      * @param sizeDest size of the destination file
0078      * @param ctimeSrc creation time of the source file
0079      * @param ctimeDest creation time of the destination file
0080      * @param mtimeSrc modification time of the source file
0081      * @param mtimeDest modification time of the destination file
0082      */
0083     virtual void askUserRename(KJob *job,
0084                                const QString &title,
0085                                const QUrl &src,
0086                                const QUrl &dest,
0087                                KIO::RenameDialog_Options options,
0088                                KIO::filesize_t sizeSrc,
0089                                KIO::filesize_t sizeDest,
0090                                const QDateTime &ctimeSrc = {},
0091                                const QDateTime &ctimeDest = {},
0092                                const QDateTime &mtimeSrc = {},
0093                                const QDateTime &mtimeDest = {}) = 0;
0094 
0095     /**
0096      * @relates KIO::SkipDialog
0097      *
0098      * You need to connect to the askUserSkipResult signal to get the dialog's
0099      * result.
0100      *
0101      * @param job the job that called this method
0102      * @param options parameters for the dialog (which buttons to show... etc), OR'ed
0103      *            values from the KIO::SkipDialog_Options enum
0104      * @param error_text the error text to show to the user (usually the string returned
0105      *               by KJob::errorText())
0106      */
0107     virtual void askUserSkip(KJob *job, KIO::SkipDialog_Options options, const QString &errorText) = 0;
0108 
0109     /**
0110      * The type of deletion.
0111      *
0112      * Used by askUserDelete().
0113      */
0114     enum DeletionType {
0115         Delete, /// Delete the files/directories directly, i.e. without moving them to Trash
0116         Trash, /// Move the files/directories to Trash
0117         EmptyTrash, /// Empty the Trash
0118         /**
0119          * This is the same as Delete, but more text is added to the message to inform
0120          * the user that moving to Trash was tried but failed due to size constraints.
0121          * Typical use case is re-asking the user about deleting instead of Trashing.
0122          * @since 5.100
0123          */
0124         DeleteInsteadOfTrash,
0125     };
0126 
0127     /**
0128      * Deletion confirmation type.
0129      *
0130      * Used by askUserDelete().
0131      */
0132     enum ConfirmationType {
0133         DefaultConfirmation, ///< Do not ask if the user has previously set the "Do not ask again"
0134                              ///< checkbox (which is is shown in the message dialog invoked by askUserDelete())
0135         ForceConfirmation, ///< Always ask the user for confirmation
0136     };
0137 
0138     /**
0139      * Ask for confirmation before moving @p urls (files/directories) to the Trash,
0140      * emptying the Trash, or directly deleting files (i.e. without moving to Trash).
0141      *
0142      * Note that this method is not called automatically by KIO jobs. It's the
0143      * application's responsibility to ask the user for confirmation before calling
0144      * KIO::del() or KIO::trash().
0145      *
0146      * You need to connect to the askUserDeleteResult signal to get the dialog's result
0147      * (exit code).
0148      *
0149      * @param urls the urls about to be moved to the Trash or deleted directly
0150      * @param deletionType the type of deletion (Delete for real deletion, Trash otherwise),
0151      *                 see the DeletionType enum
0152      * @param confirmationType The type of deletion confirmation, see the ConfirmationType enum.
0153      *                     Normally set to DefaultConfirmation
0154      * @param parent the parent widget of the message box
0155      */
0156     virtual void askUserDelete(const QList<QUrl> &urls,
0157                                DeletionType deletionType,
0158                                ConfirmationType confirmationType,
0159                                QWidget *parent = nullptr) = 0; // TODO KF6: replace QWidget* with QObject*
0160 
0161     enum MessageDialogType {
0162         QuestionTwoActions = 1, ///< @since 5.100
0163         QuestionTwoActionsCancel = 2, ///< @since 5.100
0164         WarningTwoActions = 3, ///< @since 5.100
0165         WarningTwoActionsCancel = 4, ///< @since 5.100
0166         WarningContinueCancel = 5,
0167         Information = 7,
0168         Error = 9,
0169     };
0170 
0171     /**
0172      * This function allows for the delegation of user prompts from the KIO worker.
0173      *
0174      * @param type the desired type of message box, see the MessageDialogType enum
0175      * @param text the message to show to the user
0176      * @param title the title of the message dialog box
0177      * @param primaryActionText the text for the primary action
0178      * @param secondatyActionText the text for the secondary action
0179      * @param primaryActionIconName the icon to show on the primary action
0180      * @param secondatyActionIconName the icon to show on the secondary action
0181      * @param dontAskAgainName the config key name used to store the result from
0182      *                     'Do not ask again' checkbox
0183      * @param details more details about the message shown to the user
0184      * @param parent the parent widget of the dialog
0185      */
0186     virtual void requestUserMessageBox(MessageDialogType type,
0187                                        const QString &text,
0188                                        const QString &title,
0189                                        const QString &primaryActionText,
0190                                        const QString &secondatyActionText,
0191                                        const QString &primaryActionIconName = {},
0192                                        const QString &secondatyActionIconName = {},
0193                                        const QString &dontAskAgainName = {},
0194                                        const QString &details = {},
0195                                        QWidget *parent = nullptr) = 0; // TODO KF6: replace QWidget* with QObject*, document "widget or window"
0196 
0197     virtual void askIgnoreSslErrors(const QVariantMap &sslErrorData, QWidget *parent) = 0;
0198 
0199 Q_SIGNALS:
0200     /**
0201      * Implementations of this interface must emit this signal when the rename dialog
0202      * finishes, to notify the caller of the dialog's result.
0203      *
0204      * @param result the exit code from the rename dialog, one of the KIO::RenameDialog_Result
0205      *           enum
0206      * @param newUrl the new destination URL set by the user
0207      * @param parentJob the job that invoked the dialog
0208      */
0209     void askUserRenameResult(KIO::RenameDialog_Result result, const QUrl &newUrl, KJob *parentJob);
0210 
0211     /**
0212      * Implementations of this interface must emit this signal when the skip dialog
0213      * finishes, to notify the caller of the dialog's result.
0214      *
0215      * @param result the exit code from the skip dialog, one of the KIO::SkipDialog_Result enum
0216      * @param parentJob the job that invoked the dialog
0217      */
0218     void askUserSkipResult(KIO::SkipDialog_Result result, KJob *parentJob);
0219 
0220     /**
0221      * Implementations of this interface must emit this signal when the dialog invoked
0222      * by askUserDelete() finishes, to notify the caller of the user's decision.
0223      *
0224      * @param allowDelete set to true if the user confirmed the delete operation, otherwise
0225      * set to false
0226      * @param urls a list of urls to delete/trash
0227      * @param deletionType the deletion type to use, one of KIO::AskUserActionInterface::DeletionType
0228      * @param parent the parent widget passed to askUserDelete(), for request identification
0229      */
0230     void askUserDeleteResult(bool allowDelete,
0231                              const QList<QUrl> &urls,
0232                              KIO::AskUserActionInterface::DeletionType deletionType,
0233                              QWidget *parent); // TODO KF6: replace QWidget* with QObject*
0234 
0235     /**
0236      * Implementations of this interface must emit this signal when the dialog invoked
0237      * by requestUserMessageBox() finishes, to notify the caller of the dialog's result
0238      * (exit code).
0239      *
0240      * @param result the exit code of the dialog, one of KIO::WorkerBase::ButtonCode enum
0241      */
0242     void messageBoxResult(int result); // TODO KF6: add a QObject* to identify requests? Or return an int from the request method and pass it back here?
0243 
0244     void askIgnoreSslErrorsResult(int result);
0245 
0246 private:
0247     std::unique_ptr<AskUserActionInterfacePrivate> d;
0248 };
0249 
0250 } // namespace KIO
0251 
0252 #endif // ASKUSERACTIONINTERFACE_H