1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
/****************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see http://www.qt.io/terms-conditions. For further
** information use the contact form at http://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page porting4-dnd.html
\title Porting to Qt 4 - Drag and Drop
\contentspage {Porting Guides}{Contents}
\previouspage Porting to Qt 4 - Virtual Functions
\nextpage Porting UI Files to Qt 4
\ingroup porting
\brief An overview of the porting process for applications that use drag and drop.
Qt 4 introduces a new set of classes to handle drag and drop operations
that aim to be easier to use than their counterparts in Qt 3. As a result,
the way that drag and drop is performed is quite different to the way
developers of Qt 3 applications have come to expect. In this guide, we
show the differences between the old and new APIs and indicate where
applications need to be changed when they are ported to Qt 4.
\tableofcontents
\section1 Dragging
In Qt 3, drag operations are encapsulated by \c QDragObject (see Q3DragObject)
and its subclasses. These objects are typically constructed on the heap in
response to mouse click or mouse move events, and ownership of them is
transferred to Qt so that they can be deleted when the corresponding drag and
drop operations have been completed. The drag source has no control over how
the drag and drop operation is performed once the object's
\l{Q3DragObject::}{drag()} function is called, and it receives no information
about how the operation ended.
\snippet doc/src/snippets/code/doc_src_dnd.cpp 0
Similarly, in Qt 4, drag operations are also initiated when a QDrag object
is constructed and its \l{QDrag::}{exec()} function is called. In contrast,
these objects are typically constructed on the stack rather than the heap
since each drag and drop operation is performed synchronously as far as the
drag source is concerned. One key benefit of this is that the drag source
can receive information about how the operation ended from the value returned
by \l{QDrag::}{exec()}.
\snippet doc/src/snippets/porting4-dropevents/window.cpp 2
\snippet doc/src/snippets/porting4-dropevents/window.cpp 3
\dots 8
\snippet doc/src/snippets/porting4-dropevents/window.cpp 4
\snippet doc/src/snippets/porting4-dropevents/window.cpp 5
A key difference in the above code is the use of the QMimeData class to hold
information about the data that is transferred. Qt 3 relies on subclasses
of \c QDragObject to provide support for specific MIME types; in Qt 4, the
use of QMimeData as a generic container for data makes the relationship
between MIME type and data more tranparent. QMimeData is described in more
detail later in this document.
\section1 Dropping
In both Qt 3 and Qt 4, it is possible to prepare a custom widget to accept
dropped data by enabling the \l{QWidget::}{acceptDrops} property of a widget,
usually in the widget's constructor. As a result, the widget will receive
drag enter events that can be handled by its \l{QWidget::}{dragEnterEvent()}
function.
As in Qt 3, custom widgets in Qt 4 handle these events by determining
whether the data supplied by the drag and drop operation can be dropped onto
the widget. Since the classes used to encapsulate MIME data are different in
Qt 3 and Qt 4, the exact implementations differ.
In Qt 3, the drag enter event is handled by checking whether each of the
standard \c QDragObject subclasses can decode the data supplied, and
indicating success or failure of these checks via the event's
\l{QDragEnterEvent::}{accept()} function, as shown in this simple example:
\snippet doc/src/snippets/code/doc_src_dnd.cpp 1
In Qt 4, you can examine the MIME type describing the data to determine
whether the widget should accept the event or, for common data types, you
can use convenience functions:
\snippet doc/src/snippets/porting4-dropevents/window.cpp 0
The widget has some control over the type of drag and drop operation to be
performed. In the above code, the action proposed by the drag source is
accepted, but
\l{Drag and Drop#Overriding Proposed Actions}{this can be overridden} if
required.
In both Qt 3 and Qt 4, it is necessary to accept a given drag event in order
to receive the corresponding drop event. A custom widget in Qt 3 that can
accept dropped data in the form of text or images might provide an
implementation of \l{QWidget::}{dropEvent()} that looks like the following:
\snippet doc/src/snippets/code/doc_src_dnd.cpp 2
In Qt 4, the event is handled in a similar way:
\snippet doc/src/snippets/porting4-dropevents/window.cpp 1
It is also possible to extract data stored for a particular MIME type if it
was specified by the drag source.
\section1 MIME Types and Data
In Qt 3, data to be transferred in drag and drop operations is encapsulated
in instances of \c QDragObject and its subclasses, representing specific
data formats related to common MIME type and subtypes.
In Qt 4, only the QMimeData class is used to represent data, providing a
container for data stored in multiple formats, each associated with
a relevant MIME type. Since arbitrary MIME types can be specified, there is
no need for an extensive class hierarchy to represent different kinds of
information. Additionally, QMimeData it provides some convenience functions
to allow the most common data formats to be stored and retrieved with less
effort than for arbitrary MIME types.
*/
|
