1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2014 David Faure <faure@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
6*/
7
8#ifndef DROPJOB_H
9#define DROPJOB_H
10
11#include <QUrl>
12
13#include "kiowidgets_export.h"
14#include <kio/job_base.h>
15
16class QAction;
17class QDropEvent;
18class KFileItemListProperties;
19
20namespace KIO
21{
22/**
23 * Special flag of DropJob in addition to KIO::JobFlag
24 *
25 * @see DropJobFlags
26 * @since 5.67
27 */
28enum DropJobFlag {
29 DropJobDefaultFlags = 0,
30 ShowMenuManually = 1, ///< show the menu manually with DropJob::showMenu
31};
32/**
33 * Stores a combination of #DropJobFlag values.
34 */
35Q_DECLARE_FLAGS(DropJobFlags, DropJobFlag)
36Q_DECLARE_OPERATORS_FOR_FLAGS(DropJobFlags)
37
38class CopyJob;
39class DropJobPrivate;
40
41/**
42 * @class KIO::DropJob dropjob.h <KIO/DropJob>
43 *
44 * A KIO job that handles dropping into a file-manager-like view.
45 * @see KIO::drop
46 *
47 * The popupmenu that can appear on drop, can be customized with plugins,
48 * see KIO::DndPopupMenuPlugin.
49 *
50 * @since 5.6
51 */
52class KIOWIDGETS_EXPORT DropJob : public Job
53{
54 Q_OBJECT
55
56public:
57 ~DropJob() override;
58
59 /**
60 * Allows the application to set additional actions in the drop popup menu.
61 * For instance, the application handling the desktop might want to add
62 * "set as wallpaper" if the dropped url is an image file.
63 * This can be called upfront, or for convenience, when popupMenuAboutToShow is emitted.
64 */
65 void setApplicationActions(const QList<QAction *> &actions);
66
67 /**
68 * Allows the application to show the menu manually.
69 * DropJob instance has to be created with the KIO::ShowMenuManually flag
70 *
71 * @since 5.67
72 */
73 void showMenu(const QPoint &p, QAction *atAction = nullptr);
74
75Q_SIGNALS:
76 /**
77 * Signals that a file or directory was created.
78 */
79 void itemCreated(const QUrl &url);
80
81 /**
82 * Emitted when a copy job was started as subjob after user selection.
83 *
84 * You can use @p job to monitor the progress of the copy/move/link operation. Note that a
85 * CopyJob isn't always started by DropJob. For instance dropping files onto an executable will
86 * simply launch the executable.
87 *
88 * @param job the job started for moving, copying or symlinking files
89 * @since 5.30
90 */
91 void copyJobStarted(KIO::CopyJob *job);
92
93 /**
94 * Signals that the popup menu is about to be shown.
95 * Applications can use the information provided about the dropped URLs
96 * (e.g. the MIME type) to decide whether to call setApplicationActions.
97 * @param itemProps properties of the dropped items
98 */
99 void popupMenuAboutToShow(const KFileItemListProperties &itemProps);
100
101protected Q_SLOTS:
102 void slotResult(KJob *job) override;
103
104protected:
105 KIOWIDGETS_NO_EXPORT explicit DropJob(DropJobPrivate &dd);
106
107private:
108 Q_DECLARE_PRIVATE(DropJob)
109};
110
111/**
112 * Drops the clipboard contents.
113 *
114 * If the mime data contains URLs, a popup appears to choose between
115 * Move, Copy, Link and Cancel
116 * which is then implemented by the job, using KIO::move, KIO::copy or KIO::link
117 * Additional actions provided by the application or by plugins can be shown in the popup.
118 *
119 * If the mime data contains data other than URLs, it is saved into a file after asking
120 * the user to choose a filename and the preferred data format.
121 *
122 * This job takes care of recording the subjob in the FileUndoManager, and emits
123 * itemCreated for every file or directory being created, so that the view can select
124 * these items.
125 *
126 * @param dropEvent the drop event, from which the job will extract mimeData, dropAction, etc.
127 The application should take care of calling dropEvent->acceptProposedAction().
128 * @param destUrl The URL of the target file or directory
129 * @param flags passed to the sub job
130 *
131 * @return A pointer to the job handling the operation.
132 * @warning Don't forget to call KJobWidgets::setWindow() on this job, otherwise the popup
133 * menu won't be properly positioned with Wayland compositors.
134 * @since 5.4
135 */
136KIOWIDGETS_EXPORT DropJob *drop(const QDropEvent *dropEvent, const QUrl &destUrl, JobFlags flags = DefaultFlags);
137
138/**
139 * Similar to KIO::drop
140 *
141 * @param dropEvent the drop event, from which the job will extract mimeData, dropAction, etc.
142 The application should take care of calling dropEvent->acceptProposedAction().
143 * @param destUrl The URL of the target file or directory
144 * @param dropjobFlags Show the menu immediately or manually.
145 * @param flags passed to the sub job
146 *
147 * @return A pointer to the job handling the operation.
148 * @warning Don't forget to call DropJob::showMenu on this job, otherwise the popup will never be shown
149 *
150 * @since 5.67
151 */
152KIOWIDGETS_EXPORT DropJob *drop(const QDropEvent *dropEvent,
153 const QUrl &destUrl,
154 DropJobFlags dropjobFlags,
155 JobFlags flags = DefaultFlags); // TODO KF6: merge with DropJobFlags dropjobFlag = DropJobDefaultFlags
156
157}
158
159#endif
160

source code of kio/src/widgets/dropjob.h