File indexing completed on 2024-06-16 10:06:11

0001 /*
0002     This file is part of the KDE libraries
0003     SPDX-FileCopyrightText: 2014 David Faure <faure@kde.org>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
0006 */
0007 
0008 #ifndef DROPJOB_H
0009 #define DROPJOB_H
0010 
0011 #include <QUrl>
0012 
0013 #include "kiowidgets_export.h"
0014 #include <kio/job_base.h>
0015 
0016 class QAction;
0017 class QDropEvent;
0018 class KFileItemListProperties;
0019 
0020 namespace KIO
0021 {
0022 /**
0023  * Special flag of DropJob in addition to KIO::JobFlag
0024  *
0025  * @see DropJobFlags
0026  * @since 5.67
0027  */
0028 enum DropJobFlag {
0029     DropJobDefaultFlags = 0,
0030     ShowMenuManually = 1, ///< show the menu manually with DropJob::showMenu
0031 };
0032 /**
0033  * Stores a combination of #DropJobFlag values.
0034  */
0035 Q_DECLARE_FLAGS(DropJobFlags, DropJobFlag)
0036 Q_DECLARE_OPERATORS_FOR_FLAGS(DropJobFlags)
0037 
0038 class CopyJob;
0039 class DropJobPrivate;
0040 
0041 /**
0042  * @class KIO::DropJob dropjob.h <KIO/DropJob>
0043  *
0044  * A KIO job that handles dropping into a file-manager-like view.
0045  * @see KIO::drop
0046  *
0047  * The popupmenu that can appear on drop, can be customized with plugins,
0048  * see KIO::DndPopupMenuPlugin.
0049  *
0050  * @since 5.6
0051  */
0052 class KIOWIDGETS_EXPORT DropJob : public Job
0053 {
0054     Q_OBJECT
0055 
0056 public:
0057     ~DropJob() override;
0058 
0059     /**
0060      * Allows the application to set additional actions in the drop popup menu.
0061      * For instance, the application handling the desktop might want to add
0062      * "set as wallpaper" if the dropped url is an image file.
0063      * This can be called upfront, or for convenience, when popupMenuAboutToShow is emitted.
0064      */
0065     void setApplicationActions(const QList<QAction *> &actions);
0066 
0067     /**
0068      * Allows the application to show the menu manually.
0069      * DropJob instance has to be created with the KIO::ShowMenuManually flag
0070      *
0071      * @since 5.67
0072      */
0073     void showMenu(const QPoint &p, QAction *atAction = nullptr);
0074 
0075 Q_SIGNALS:
0076     /**
0077      * Signals that a file or directory was created.
0078      */
0079     void itemCreated(const QUrl &url);
0080 
0081     /**
0082      * Emitted when a copy job was started as subjob after user selection.
0083      *
0084      * You can use @p job to monitor the progress of the copy/move/link operation. Note that a
0085      * CopyJob isn't always started by DropJob. For instance dropping files onto an executable will
0086      * simply launch the executable.
0087      *
0088      * @param job the job started for moving, copying or symlinking files
0089      * @since 5.30
0090      */
0091     void copyJobStarted(KIO::CopyJob *job);
0092 
0093     /**
0094      * Signals that the popup menu is about to be shown.
0095      * Applications can use the information provided about the dropped URLs
0096      * (e.g. the MIME type) to decide whether to call setApplicationActions.
0097      * @param itemProps properties of the dropped items
0098      */
0099     void popupMenuAboutToShow(const KFileItemListProperties &itemProps);
0100 
0101 protected Q_SLOTS:
0102     void slotResult(KJob *job) override;
0103 
0104 protected:
0105     KIOWIDGETS_NO_EXPORT explicit DropJob(DropJobPrivate &dd);
0106 
0107 private:
0108     Q_DECLARE_PRIVATE(DropJob)
0109 };
0110 
0111 /**
0112  * Drops the clipboard contents.
0113  *
0114  * If the mime data contains URLs, a popup appears to choose between
0115  *  Move, Copy, Link and Cancel
0116  * which is then implemented by the job, using KIO::move, KIO::copy or KIO::link
0117  * Additional actions provided by the application or by plugins can be shown in the popup.
0118  *
0119  * If the mime data contains data other than URLs, it is saved into a file after asking
0120  * the user to choose a filename and the preferred data format.
0121  *
0122  * This job takes care of recording the subjob in the FileUndoManager, and emits
0123  * itemCreated for every file or directory being created, so that the view can select
0124  * these items.
0125  *
0126  * @param dropEvent the drop event, from which the job will extract mimeData, dropAction, etc.
0127          The application should take care of calling dropEvent->acceptProposedAction().
0128  * @param destUrl The URL of the target file or directory
0129  * @param flags passed to the sub job
0130  *
0131  * @return A pointer to the job handling the operation.
0132  * @warning Don't forget to call KJobWidgets::setWindow() on this job, otherwise the popup
0133  *          menu won't be properly positioned with Wayland compositors.
0134  * @since 5.4
0135  */
0136 KIOWIDGETS_EXPORT DropJob *drop(const QDropEvent *dropEvent, const QUrl &destUrl, JobFlags flags = DefaultFlags);
0137 
0138 /**
0139  * Similar to KIO::drop
0140  *
0141  * @param dropEvent the drop event, from which the job will extract mimeData, dropAction, etc.
0142          The application should take care of calling dropEvent->acceptProposedAction().
0143  * @param destUrl The URL of the target file or directory
0144  * @param dropjobFlags Show the menu immediately or manually.
0145  * @param flags passed to the sub job
0146  *
0147  * @return A pointer to the job handling the operation.
0148  * @warning Don't forget to call DropJob::showMenu on this job, otherwise the popup will never be shown
0149  *
0150  * @since 5.67
0151  */
0152 KIOWIDGETS_EXPORT DropJob *drop(const QDropEvent *dropEvent,
0153                                 const QUrl &destUrl,
0154                                 DropJobFlags dropjobFlags,
0155                                 JobFlags flags = DefaultFlags); // TODO KF6: merge with DropJobFlags dropjobFlag = DropJobDefaultFlags
0156 
0157 }
0158 
0159 #endif