|
1 /**************************************************************************** |
|
2 ** |
|
3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). |
|
4 ** All rights reserved. |
|
5 ** Contact: Nokia Corporation (qt-info@nokia.com) |
|
6 ** |
|
7 ** This file is part of the QtGui module of the Qt Toolkit. |
|
8 ** |
|
9 ** $QT_BEGIN_LICENSE:LGPL$ |
|
10 ** No Commercial Usage |
|
11 ** This file contains pre-release code and may not be distributed. |
|
12 ** You may use this file in accordance with the terms and conditions |
|
13 ** contained in the Technology Preview License Agreement accompanying |
|
14 ** this package. |
|
15 ** |
|
16 ** GNU Lesser General Public License Usage |
|
17 ** Alternatively, this file may be used under the terms of the GNU Lesser |
|
18 ** General Public License version 2.1 as published by the Free Software |
|
19 ** Foundation and appearing in the file LICENSE.LGPL included in the |
|
20 ** packaging of this file. Please review the following information to |
|
21 ** ensure the GNU Lesser General Public License version 2.1 requirements |
|
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. |
|
23 ** |
|
24 ** In addition, as a special exception, Nokia gives you certain additional |
|
25 ** rights. These rights are described in the Nokia Qt LGPL Exception |
|
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. |
|
27 ** |
|
28 ** If you have questions regarding the use of this file, please contact |
|
29 ** Nokia at qt-info@nokia.com. |
|
30 ** |
|
31 ** |
|
32 ** |
|
33 ** |
|
34 ** |
|
35 ** |
|
36 ** |
|
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 */ |
|
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 */ |
|
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 */ |
|
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 */ |
|
152 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 */ |
|
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 */ |
|
172 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 */ |
|
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 */ |
|
196 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 */ |
|
206 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 */ |
|
216 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 |
|
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 while during the operation. |
|
257 */ |
|
258 |
|
259 Qt::DropAction QDrag::exec(Qt::DropActions supportedActions, Qt::DropAction defaultDropAction) |
|
260 { |
|
261 Q_D(QDrag); |
|
262 if (!d->data) { |
|
263 qWarning("QDrag: No mimedata set before starting the drag"); |
|
264 return d->executed_action; |
|
265 } |
|
266 QDragManager *manager = QDragManager::self(); |
|
267 d->defaultDropAction = Qt::IgnoreAction; |
|
268 d->possible_actions = supportedActions; |
|
269 |
|
270 if (manager) { |
|
271 if (defaultDropAction == Qt::IgnoreAction) { |
|
272 if (supportedActions & Qt::MoveAction) { |
|
273 d->defaultDropAction = Qt::MoveAction; |
|
274 } else if (supportedActions & Qt::CopyAction) { |
|
275 d->defaultDropAction = Qt::CopyAction; |
|
276 } else if (supportedActions & Qt::LinkAction) { |
|
277 d->defaultDropAction = Qt::LinkAction; |
|
278 } |
|
279 } else { |
|
280 d->defaultDropAction = defaultDropAction; |
|
281 } |
|
282 d->executed_action = manager->drag(this); |
|
283 } |
|
284 |
|
285 return d->executed_action; |
|
286 } |
|
287 |
|
288 /*! |
|
289 \obsolete |
|
290 |
|
291 \bold{Note:} It is recommended to use exec() instead of this function. |
|
292 |
|
293 Starts the drag and drop operation and returns a value indicating the requested |
|
294 drop action when it is completed. The drop actions that the user can choose |
|
295 from are specified in \a request. Qt::CopyAction is always allowed. |
|
296 |
|
297 \bold{Note:} Although the drag and drop operation can take some time, this function |
|
298 does not block the event loop. Other events are still delivered to the application |
|
299 while the operation is performed. |
|
300 |
|
301 \sa exec() |
|
302 */ |
|
303 Qt::DropAction QDrag::start(Qt::DropActions request) |
|
304 { |
|
305 Q_D(QDrag); |
|
306 if (!d->data) { |
|
307 qWarning("QDrag: No mimedata set before starting the drag"); |
|
308 return d->executed_action; |
|
309 } |
|
310 QDragManager *manager = QDragManager::self(); |
|
311 d->defaultDropAction = Qt::IgnoreAction; |
|
312 d->possible_actions = request | Qt::CopyAction; |
|
313 if (manager) |
|
314 d->executed_action = manager->drag(this); |
|
315 return d->executed_action; |
|
316 } |
|
317 |
|
318 /*! |
|
319 Sets the drag \a cursor for the \a action. This allows you |
|
320 to override the default native cursors. To revert to using the |
|
321 native cursor for \a action pass in a null QPixmap as \a cursor. |
|
322 |
|
323 The \a action can only be CopyAction, MoveAction or LinkAction. |
|
324 All other values of DropAction are ignored. |
|
325 */ |
|
326 void QDrag::setDragCursor(const QPixmap &cursor, Qt::DropAction action) |
|
327 { |
|
328 Q_D(QDrag); |
|
329 if (action != Qt::CopyAction && action != Qt::MoveAction && action != Qt::LinkAction) |
|
330 return; |
|
331 if (cursor.isNull()) |
|
332 d->customCursors.remove(action); |
|
333 else |
|
334 d->customCursors[action] = cursor; |
|
335 } |
|
336 |
|
337 /*! |
|
338 \fn void QDrag::actionChanged(Qt::DropAction action) |
|
339 |
|
340 This signal is emitted when the \a action associated with the |
|
341 drag changes. |
|
342 |
|
343 \sa targetChanged() |
|
344 */ |
|
345 |
|
346 /*! |
|
347 \fn void QDrag::targetChanged(QWidget *newTarget) |
|
348 |
|
349 This signal is emitted when the target of the drag and drop |
|
350 operation changes, with \a newTarget the new target. |
|
351 |
|
352 \sa target(), actionChanged() |
|
353 */ |
|
354 |
|
355 QT_END_NAMESPACE |
|
356 |
|
357 #endif // QT_NO_DRAGANDDROP |