|
1 /**************************************************************************** |
|
2 ** |
|
3 ** Copyright (C) 2010 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 documentation 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 /*! |
|
43 \page porting4-dnd.html |
|
44 \title Porting to Qt 4 - Drag and Drop |
|
45 \contentspage {Porting Guides}{Contents} |
|
46 \previouspage Porting to Qt 4 - Virtual Functions |
|
47 \nextpage Porting UI Files to Qt 4 |
|
48 \ingroup porting |
|
49 \brief An overview of the porting process for applications that use drag and drop. |
|
50 |
|
51 Qt 4 introduces a new set of classes to handle drag and drop operations |
|
52 that aim to be easier to use than their counterparts in Qt 3. As a result, |
|
53 the way that drag and drop is performed is quite different to the way |
|
54 developers of Qt 3 applications have come to expect. In this guide, we |
|
55 show the differences between the old and new APIs and indicate where |
|
56 applications need to be changed when they are ported to Qt 4. |
|
57 |
|
58 \tableofcontents |
|
59 |
|
60 \section1 Dragging |
|
61 |
|
62 In Qt 3, drag operations are encapsulated by \c QDragObject (see Q3DragObject) |
|
63 and its subclasses. These objects are typically constructed on the heap in |
|
64 response to mouse click or mouse move events, and ownership of them is |
|
65 transferred to Qt so that they can be deleted when the corresponding drag and |
|
66 drop operations have been completed. The drag source has no control over how |
|
67 the drag and drop operation is performed once the object's |
|
68 \l{Q3DragObject::}{drag()} function is called, and it receives no information |
|
69 about how the operation ended. |
|
70 |
|
71 \snippet doc/src/snippets/code/doc_src_dnd.qdoc 0 |
|
72 |
|
73 Similarly, in Qt 4, drag operations are also initiated when a QDrag object |
|
74 is constructed and its \l{QDrag::}{exec()} function is called. In contrast, |
|
75 these objects are typically constructed on the stack rather than the heap |
|
76 since each drag and drop operation is performed synchronously as far as the |
|
77 drag source is concerned. One key benefit of this is that the drag source |
|
78 can receive information about how the operation ended from the value returned |
|
79 by \l{QDrag::}{exec()}. |
|
80 |
|
81 \snippet doc/src/snippets/porting4-dropevents/window.cpp 2 |
|
82 \snippet doc/src/snippets/porting4-dropevents/window.cpp 3 |
|
83 \dots 8 |
|
84 \snippet doc/src/snippets/porting4-dropevents/window.cpp 4 |
|
85 \snippet doc/src/snippets/porting4-dropevents/window.cpp 5 |
|
86 |
|
87 A key difference in the above code is the use of the QMimeData class to hold |
|
88 information about the data that is transferred. Qt 3 relies on subclasses |
|
89 of \c QDragObject to provide support for specific MIME types; in Qt 4, the |
|
90 use of QMimeData as a generic container for data makes the relationship |
|
91 between MIME type and data more tranparent. QMimeData is described in more |
|
92 detail later in this document. |
|
93 |
|
94 \section1 Dropping |
|
95 |
|
96 In both Qt 3 and Qt 4, it is possible to prepare a custom widget to accept |
|
97 dropped data by enabling the \l{QWidget::}{acceptDrops} property of a widget, |
|
98 usually in the widget's constructor. As a result, the widget will receive |
|
99 drag enter events that can be handled by its \l{QWidget::}{dragEnterEvent()} |
|
100 function. |
|
101 As in Qt 3, custom widgets in Qt 4 handle these events by determining |
|
102 whether the data supplied by the drag and drop operation can be dropped onto |
|
103 the widget. Since the classes used to encapsulate MIME data are different in |
|
104 Qt 3 and Qt 4, the exact implementations differ. |
|
105 |
|
106 In Qt 3, the drag enter event is handled by checking whether each of the |
|
107 standard \c QDragObject subclasses can decode the data supplied, and |
|
108 indicating success or failure of these checks via the event's |
|
109 \l{QDragEnterEvent::}{accept()} function, as shown in this simple example: |
|
110 |
|
111 \snippet doc/src/snippets/code/doc_src_dnd.qdoc 1 |
|
112 |
|
113 In Qt 4, you can examine the MIME type describing the data to determine |
|
114 whether the widget should accept the event or, for common data types, you |
|
115 can use convenience functions: |
|
116 |
|
117 \snippet doc/src/snippets/porting4-dropevents/window.cpp 0 |
|
118 |
|
119 The widget has some control over the type of drag and drop operation to be |
|
120 performed. In the above code, the action proposed by the drag source is |
|
121 accepted, but |
|
122 \l{Drag and Drop#Overriding Proposed Actions}{this can be overridden} if |
|
123 required. |
|
124 |
|
125 In both Qt 3 and Qt 4, it is necessary to accept a given drag event in order |
|
126 to receive the corresponding drop event. A custom widget in Qt 3 that can |
|
127 accept dropped data in the form of text or images might provide an |
|
128 implementation of \l{QWidget::}{dropEvent()} that looks like the following: |
|
129 |
|
130 \snippet doc/src/snippets/code/doc_src_dnd.qdoc 2 |
|
131 |
|
132 In Qt 4, the event is handled in a similar way: |
|
133 |
|
134 \snippet doc/src/snippets/porting4-dropevents/window.cpp 1 |
|
135 |
|
136 It is also possible to extract data stored for a particular MIME type if it |
|
137 was specified by the drag source. |
|
138 |
|
139 \section1 MIME Types and Data |
|
140 |
|
141 In Qt 3, data to be transferred in drag and drop operations is encapsulated |
|
142 in instances of \c QDragObject and its subclasses, representing specific |
|
143 data formats related to common MIME type and subtypes. |
|
144 |
|
145 In Qt 4, only the QMimeData class is used to represent data, providing a |
|
146 container for data stored in multiple formats, each associated with |
|
147 a relevant MIME type. Since arbitrary MIME types can be specified, there is |
|
148 no need for an extensive class hierarchy to represent different kinds of |
|
149 information. Additionally, QMimeData it provides some convenience functions |
|
150 to allow the most common data formats to be stored and retrieved with less |
|
151 effort than for arbitrary MIME types. |
|
152 */ |