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