KIO

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

KDE's Doxygen guidelines are available online.