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 | |
16 | class QAction; |
17 | class QDropEvent; |
18 | class KFileItemListProperties; |
19 | |
20 | namespace 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 | */ |
30 | enum DropJobFlag { |
31 | DropJobDefaultFlags = 0, |
32 | = 1, |
33 | }; |
34 | Q_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 | */ |
44 | Q_NAMESPACE |
45 | enum DndBehavior : std::uint8_t { |
46 | AlwaysAsk = 0, |
47 | MoveIfSameDevice = 1, |
48 | }; |
49 | Q_ENUM_NS(DndBehavior) |
50 | Q_DECLARE_OPERATORS_FOR_FLAGS(DropJobFlags) |
51 | |
52 | class CopyJob; |
53 | class 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 | */ |
68 | class KIOWIDGETS_EXPORT DropJob : public Job |
69 | { |
70 | Q_OBJECT |
71 | |
72 | public: |
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 (const QPoint &p, QAction *atAction = nullptr); |
90 | |
91 | Q_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 (const KFileItemListProperties &itemProps); |
117 | |
118 | protected Q_SLOTS: |
119 | void slotResult(KJob *job) override; |
120 | |
121 | protected: |
122 | KIOWIDGETS_NO_EXPORT explicit DropJob(DropJobPrivate &dd); |
123 | |
124 | private: |
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 | */ |
158 | KIOWIDGETS_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 | */ |
179 | KIOWIDGETS_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 | |