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 */