diff -r dee5afe5301f -r 3f74d0d4af4c doc/src/porting/porting4-dnd.qdoc --- /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. +*/