--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/porting/porting4-dnd.qdoc Thu Apr 08 14:19:33 2010 +0300
@@ -0,0 +1,152 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights. These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $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.qdoc 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.qdoc 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.qdoc 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.
+*/