1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the QtGui module of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Lesser General Public License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Lesser
19 ** General Public License version 2.1 or version 3 as published by the Free
20 ** Software Foundation and appearing in the file LICENSE.LGPLv21 and
21 ** LICENSE.LGPLv3 included in the packaging of this file. Please review the
22 ** following information to ensure the GNU Lesser General Public License
23 ** requirements will be met: https://www.gnu.org/licenses/lgpl.html and
24 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
25 **
26 ** As a special exception, The Qt Company gives you certain additional
27 ** rights. These rights are described in The Qt Company LGPL Exception
28 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
29 **
30 ** GNU General Public License Usage
31 ** Alternatively, this file may be used under the terms of the GNU
32 ** General Public License version 3.0 as published by the Free Software
33 ** Foundation and appearing in the file LICENSE.GPL included in the
34 ** packaging of this file. Please review the following information to
35 ** ensure the GNU General Public License version 3.0 requirements will be
36 ** met: http://www.gnu.org/copyleft/gpl.html.
37 **
38 ** $QT_END_LICENSE$
39 **
40 ****************************************************************************/
41
42 #include <qwidget.h>
43 #include <qdrag.h>
44 #include <qpixmap.h>
45 #include <qpoint.h>
46 #include "qdnd_p.h"
47
48 #ifndef QT_NO_DRAGANDDROP
49
50 QT_BEGIN_NAMESPACE
51
52 /*!
53 \class QDrag
54 \brief The QDrag class provides support for MIME-based drag and drop data
55 transfer.
56
57 Drag and drop is an intuitive way for users to copy or move data around in an
58 application, and is used in many desktop environments as a mechanism for copying
59 data between applications. Drag and drop support in Qt is centered around the
60 QDrag class that handles most of the details of a drag and drop operation.
61
62 The data to be transferred by the drag and drop operation is contained in a
63 QMimeData object. This is specified with the setMimeData() function in the
64 following way:
65
66 \snippet doc/src/snippets/dragging/mainwindow.cpp 1
67
68 Note that setMimeData() assigns ownership of the QMimeData object to the
69 QDrag object. The QDrag must be constructed on the heap with a parent QWidget
70 to ensure that Qt can clean up after the drag and drop operation has been
71 completed.
72
73 A pixmap can be used to represent the data while the drag is in
74 progress, and will move with the cursor to the drop target. This
75 pixmap typically shows an icon that represents the MIME type of
76 the data being transferred, but any pixmap can be set with
77 setPixmap(). The cursor's hot spot can be given a position
78 relative to the top-left corner of the pixmap with the
79 setHotSpot() function. The following code positions the pixmap so
80 that the cursor's hot spot points to the center of its bottom
81 edge:
82
83 \snippet doc/src/snippets/separations/finalwidget.cpp 2
84
85 \note On X11, the pixmap may not be able to keep up with the mouse
86 movements if the hot spot causes the pixmap to be displayed
87 directly under the cursor.
88
89 The source and target widgets can be found with source() and target().
90 These functions are often used to determine whether drag and drop operations
91 started and finished at the same widget, so that special behavior can be
92 implemented.
93
94 QDrag only deals with the drag and drop operation itself. It is up to the
95 developer to decide when a drag operation begins, and how a QDrag object should
96 be constructed and used. For a given widget, it is often necessary to
97 reimplement \l{QWidget::mousePressEvent()}{mousePressEvent()} to determine
98 whether the user has pressed a mouse button, and reimplement
99 \l{QWidget::mouseMoveEvent()}{mouseMoveEvent()} to check whether a QDrag is
100 required.
101
102 \sa {Drag and Drop}, QClipboard, QMimeData, QWindowsMime, QMacPasteboardMime,
103 {Draggable Icons Example}, {Draggable Text Example}, {Drop Site Example},
104 {Fridge Magnets Example}
105 */
106
107 /*!
108 Constructs a new drag object for the widget specified by \a dragSource.
109 */
QDrag(QWidget * dragSource)110 QDrag::QDrag(QWidget *dragSource)
111 : QObject(*new QDragPrivate, dragSource)
112 {
113 Q_D(QDrag);
114 d->source = dragSource;
115 d->target = 0;
116 d->data = 0;
117 d->hotspot = QPoint(-10, -10);
118 d->possible_actions = Qt::CopyAction;
119 d->executed_action = Qt::IgnoreAction;
120 d->defaultDropAction = Qt::IgnoreAction;
121 }
122
123 /*!
124 Destroys the drag object.
125 */
~QDrag()126 QDrag::~QDrag()
127 {
128 Q_D(QDrag);
129 delete d->data;
130 QDragManager *manager = QDragManager::self();
131 if (manager && manager->object == this)
132 manager->cancel(false);
133 }
134
135 /*!
136 Sets the data to be sent to the given MIME \a data. Ownership of the data is
137 transferred to the QDrag object.
138 */
setMimeData(QMimeData * data)139 void QDrag::setMimeData(QMimeData *data)
140 {
141 Q_D(QDrag);
142 if (d->data == data)
143 return;
144 if (d->data != 0)
145 delete d->data;
146 d->data = data;
147 }
148
149 /*!
150 Returns the MIME data that is encapsulated by the drag object.
151 */
mimeData() const152 QMimeData *QDrag::mimeData() const
153 {
154 Q_D(const QDrag);
155 return d->data;
156 }
157
158 /*!
159 Sets \a pixmap as the pixmap used to represent the data in a drag
160 and drop operation. You can only set a pixmap before the drag is
161 started.
162 */
setPixmap(const QPixmap & pixmap)163 void QDrag::setPixmap(const QPixmap &pixmap)
164 {
165 Q_D(QDrag);
166 d->pixmap = pixmap;
167 }
168
169 /*!
170 Returns the pixmap used to represent the data in a drag and drop operation.
171 */
pixmap() const172 QPixmap QDrag::pixmap() const
173 {
174 Q_D(const QDrag);
175 return d->pixmap;
176 }
177
178 /*!
179 Sets the position of the hot spot relative to the top-left corner of the
180 pixmap used to the point specified by \a hotspot.
181
182 \bold{Note:} on X11, the pixmap may not be able to keep up with the mouse
183 movements if the hot spot causes the pixmap to be displayed
184 directly under the cursor.
185 */
setHotSpot(const QPoint & hotspot)186 void QDrag::setHotSpot(const QPoint& hotspot)
187 {
188 Q_D(QDrag);
189 d->hotspot = hotspot;
190 }
191
192 /*!
193 Returns the position of the hot spot relative to the top-left corner of the
194 cursor.
195 */
hotSpot() const196 QPoint QDrag::hotSpot() const
197 {
198 Q_D(const QDrag);
199 return d->hotspot;
200 }
201
202 /*!
203 Returns the source of the drag object. This is the widget where the drag
204 and drop operation originated.
205 */
source() const206 QWidget *QDrag::source() const
207 {
208 Q_D(const QDrag);
209 return d->source;
210 }
211
212 /*!
213 Returns the target of the drag and drop operation. This is the widget where
214 the drag object was dropped.
215 */
target() const216 QWidget *QDrag::target() const
217 {
218 Q_D(const QDrag);
219 return d->target;
220 }
221
222 /*!
223 \since 4.3
224
225 Starts the drag and drop operation and returns a value indicating the requested
226 drop action when it is completed. The drop actions that the user can choose
227 from are specified in \a supportedActions. The default proposed action will be selected
228 among the allowed actions in the following order: Move, Copy and Link.
229
230 \bold{Note:} On Linux and Mac OS X, the drag and drop operation
231 can take some time, but this function does not block the event
232 loop. Other events are still delivered to the application while
233 the operation is performed. On Windows, the Qt event loop is
234 blocked while during the operation.
235 */
236
exec(Qt::DropActions supportedActions)237 Qt::DropAction QDrag::exec(Qt::DropActions supportedActions)
238 {
239 return exec(supportedActions, Qt::IgnoreAction);
240 }
241
242 /*!
243 \since 4.3
244
245 Starts the drag and drop operation and returns a value indicating the requested
246 drop action when it is completed. The drop actions that the user can choose
247 from are specified in \a supportedActions.
248
249 The \a defaultDropAction determines which action will be proposed when the user performs a
250 drag without using modifier keys.
251
252 \bold{Note:} On Linux and Mac OS X, the drag and drop operation
253 can take some time, but this function does not block the event
254 loop. Other events are still delivered to the application while
255 the operation is performed. On Windows, the Qt event loop is
256 blocked during the operation. However, QDrag::exec() on
257 Windows causes processEvents() to be called frequently to keep the GUI responsive.
258 If any loops or operations are called while a drag operation is active, it will block the drag operation.
259 */
260
exec(Qt::DropActions supportedActions,Qt::DropAction defaultDropAction)261 Qt::DropAction QDrag::exec(Qt::DropActions supportedActions, Qt::DropAction defaultDropAction)
262 {
263 Q_D(QDrag);
264 if (!d->data) {
265 qWarning("QDrag: No mimedata set before starting the drag");
266 return d->executed_action;
267 }
268 QDragManager *manager = QDragManager::self();
269 d->defaultDropAction = Qt::IgnoreAction;
270 d->possible_actions = supportedActions;
271
272 if (manager) {
273 if (defaultDropAction == Qt::IgnoreAction) {
274 if (supportedActions & Qt::MoveAction) {
275 d->defaultDropAction = Qt::MoveAction;
276 } else if (supportedActions & Qt::CopyAction) {
277 d->defaultDropAction = Qt::CopyAction;
278 } else if (supportedActions & Qt::LinkAction) {
279 d->defaultDropAction = Qt::LinkAction;
280 }
281 } else {
282 d->defaultDropAction = defaultDropAction;
283 }
284 d->executed_action = manager->drag(this);
285 }
286
287 return d->executed_action;
288 }
289
290 /*!
291 \obsolete
292
293 \bold{Note:} It is recommended to use exec() instead of this function.
294
295 Starts the drag and drop operation and returns a value indicating the requested
296 drop action when it is completed. The drop actions that the user can choose
297 from are specified in \a request. Qt::CopyAction is always allowed.
298
299 \bold{Note:} Although the drag and drop operation can take some time, this function
300 does not block the event loop. Other events are still delivered to the application
301 while the operation is performed.
302
303 \sa exec()
304 */
start(Qt::DropActions request)305 Qt::DropAction QDrag::start(Qt::DropActions request)
306 {
307 Q_D(QDrag);
308 if (!d->data) {
309 qWarning("QDrag: No mimedata set before starting the drag");
310 return d->executed_action;
311 }
312 QDragManager *manager = QDragManager::self();
313 d->defaultDropAction = Qt::IgnoreAction;
314 d->possible_actions = request | Qt::CopyAction;
315 if (manager)
316 d->executed_action = manager->drag(this);
317 return d->executed_action;
318 }
319
320 /*!
321 Sets the drag \a cursor for the \a action. This allows you
322 to override the default native cursors. To revert to using the
323 native cursor for \a action pass in a null QPixmap as \a cursor.
324
325 The \a action can only be CopyAction, MoveAction or LinkAction.
326 All other values of DropAction are ignored.
327 */
setDragCursor(const QPixmap & cursor,Qt::DropAction action)328 void QDrag::setDragCursor(const QPixmap &cursor, Qt::DropAction action)
329 {
330 Q_D(QDrag);
331 if (action != Qt::CopyAction && action != Qt::MoveAction && action != Qt::LinkAction)
332 return;
333 if (cursor.isNull())
334 d->customCursors.remove(action);
335 else
336 d->customCursors[action] = cursor;
337 }
338
339 /*!
340 \fn void QDrag::actionChanged(Qt::DropAction action)
341
342 This signal is emitted when the \a action associated with the
343 drag changes.
344
345 \sa targetChanged()
346 */
347
348 /*!
349 \fn void QDrag::targetChanged(QWidget *newTarget)
350
351 This signal is emitted when the target of the drag and drop
352 operation changes, with \a newTarget the new target.
353
354 \sa target(), actionChanged()
355 */
356
357 QT_END_NAMESPACE
358
359 #endif // QT_NO_DRAGANDDROP
360