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 * \value DropJobDefaultFlags
26 * \value ShowMenuManually Show the menu manually with DropJob::showMenu
27 *
28 * \since 5.67
29 */
30enum DropJobFlag {
31 DropJobDefaultFlags = 0,
32 ShowMenuManually = 1,
33};
34Q_DECLARE_FLAGS(DropJobFlags, DropJobFlag)
35
36/*!
37 * Setting flag to determine what the default behaviour should be when dropping items.
38 *
39 * \value AlwaysAsk
40 * \value MoveIfSameDevice Move the dragged items without showing the options menu they are on the same device
41 *
42 * \since 6.14
43 */
44Q_NAMESPACE
45enum DndBehavior : std::uint8_t {
46 AlwaysAsk = 0,
47 MoveIfSameDevice = 1,
48};
49Q_ENUM_NS(DndBehavior)
50Q_DECLARE_OPERATORS_FOR_FLAGS(DropJobFlags)
51
52class CopyJob;
53class DropJobPrivate;
54
55/*!
56 * \class KIO::DropJob
57 * \inheaderfile KIO/DropJob
58 * \inmodule KIOWidgets
59 *
60 * \brief A KIO job that handles dropping into a file-manager-like view.
61 * \sa KIO::drop
62 *
63 * The popupmenu that can appear on drop, can be customized with plugins,
64 * see KIO::DndPopupMenuPlugin.
65 *
66 * \since 5.6
67 */
68class KIOWIDGETS_EXPORT DropJob : public Job
69{
70 Q_OBJECT
71
72public:
73 ~DropJob() override;
74
75 /*!
76 * Allows the application to set additional actions in the drop popup menu.
77 * For instance, the application handling the desktop might want to add
78 * "set as wallpaper" if the dropped url is an image file.
79 * This can be called upfront, or for convenience, when popupMenuAboutToShow is emitted.
80 */
81 void setApplicationActions(const QList<QAction *> &actions);
82
83 /*!
84 * Allows the application to show the menu manually.
85 * DropJob instance has to be created with the KIO::ShowMenuManually flag
86 *
87 * \since 5.67
88 */
89 void showMenu(const QPoint &p, QAction *atAction = nullptr);
90
91Q_SIGNALS:
92 /*!
93 * Signals that a file or directory was created.
94 */
95 void itemCreated(const QUrl &url);
96
97 /*!
98 * Emitted when a copy job was started as subjob after user selection.
99 *
100 * You can use \a job to monitor the progress of the copy/move/link operation. Note that a
101 * CopyJob isn't always started by DropJob. For instance dropping files onto an executable will
102 * simply launch the executable.
103 *
104 * \a job the job started for moving, copying or symlinking files
105 * \since 5.30
106 */
107 void copyJobStarted(KIO::CopyJob *job);
108
109 /*!
110 * Signals that the popup menu is about to be shown.
111 * Applications can use the information provided about the dropped URLs
112 * (e.g. the MIME type) to decide whether to call setApplicationActions.
113 *
114 * \a itemProps properties of the dropped items
115 */
116 void popupMenuAboutToShow(const KFileItemListProperties &itemProps);
117
118protected Q_SLOTS:
119 void slotResult(KJob *job) override;
120
121protected:
122 KIOWIDGETS_NO_EXPORT explicit DropJob(DropJobPrivate &dd);
123
124private:
125 Q_DECLARE_PRIVATE(DropJob)
126};
127
128/*!
129 * \relates KIO::DropJob
130 *
131 * Drops the clipboard contents.
132 *
133 * If the mime data contains URLs, a popup appears to choose between
134 * Move, Copy, Link and Cancel
135 * which is then implemented by the job, using KIO::move, KIO::copy or KIO::link
136 * Additional actions provided by the application or by plugins can be shown in the popup.
137 *
138 * If the mime data contains data other than URLs, it is saved into a file after asking
139 * the user to choose a filename and the preferred data format.
140 *
141 * This job takes care of recording the subjob in the FileUndoManager, and emits
142 * itemCreated for every file or directory being created, so that the view can select
143 * these items.
144 *
145 * \a dropEvent the drop event, from which the job will extract mimeData, dropAction, etc.
146 * The application should take care of calling dropEvent->acceptProposedAction().
147 *
148 * \a destUrl The URL of the target file or directory
149 *
150 * \a flags passed to the sub job
151 *
152 * Returns A pointer to the job handling the operation.
153 *
154 * \warning Don't forget to call KJobWidgets::setWindow() on this job, otherwise the popup
155 * menu won't be properly positioned with Wayland compositors.
156 * \since 5.4
157 */
158KIOWIDGETS_EXPORT DropJob *drop(const QDropEvent *dropEvent, const QUrl &destUrl, JobFlags flags = DefaultFlags);
159
160/*!
161 * \relates KIO::DropJob
162 *
163 * Similar to KIO::drop
164 *
165 * \a dropEvent the drop event, from which the job will extract mimeData, dropAction, etc.
166 * The application should take care of calling dropEvent->acceptProposedAction().
167 *
168 * \a destUrl The URL of the target file or directory
169 *
170 * \a dropjobFlags Show the menu immediately or manually.
171 *
172 * \a flags passed to the sub job
173 *
174 * Returns A pointer to the job handling the operation.
175 * \warning Don't forget to call DropJob::showMenu on this job, otherwise the popup will never be shown
176 *
177 * \since 5.67
178 */
179KIOWIDGETS_EXPORT DropJob *drop(const QDropEvent *dropEvent,
180 const QUrl &destUrl,
181 DropJobFlags dropjobFlags,
182 JobFlags flags = DefaultFlags); // TODO KF6: merge with DropJobFlags dropjobFlag = DropJobDefaultFlags
183
184}
185
186#endif
187

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