<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- porting4-dnd.qdoc -->
<title>Qt 4.8: Porting to Qt 4 - Drag and Drop</title>
<link rel="stylesheet" type="text/css" href="style/style.css" />
<script src="scripts/jquery.js" type="text/javascript"></script>
<script src="scripts/functions.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="style/superfish.css" />
<link rel="stylesheet" type="text/css" href="style/narrow.css" />
<!--[if IE]>
<meta name="MSSmartTagsPreventParsing" content="true">
<meta http-equiv="imagetoolbar" content="no">
<![endif]-->
<!--[if lt IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie6.css">
<![endif]-->
<!--[if IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie7.css">
<![endif]-->
<!--[if IE 8]>
<link rel="stylesheet" type="text/css" href="style/style_ie8.css">
<![endif]-->
<script src="scripts/superfish.js" type="text/javascript"></script>
<script src="scripts/narrow.js" type="text/javascript"></script>
</head>
<body class="" onload="CheckEmptyAndLoadList();">
<div class="header" id="qtdocheader">
<div class="content">
<div id="nav-logo">
<a href="index.html">Home</a></div>
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
<div id="narrowsearch"></div>
<div id="nav-topright">
<ul>
<li class="nav-topright-home"><a href="http://qt.digia.com/">Qt HOME</a></li>
<li class="nav-topright-dev"><a href="http://qt-project.org/">DEV</a></li>
<li class="nav-topright-doc nav-topright-doc-active"><a href="http://qt-project.org/doc/">
DOC</a></li>
<li class="nav-topright-blog"><a href="http://blog.qt.digia.com/">BLOG</a></li>
</ul>
</div>
<div id="shortCut">
<ul>
<li class="shortCut-topleft-inactive"><span><a href="index.html">Qt 4.8</a></span></li>
<li class="shortCut-topleft-active"><a href="http://qt-project.org/doc/">ALL VERSIONS </a></li>
</ul>
</div>
<ul class="sf-menu" id="narrowmenu">
<li><a href="#">API Lookup</a>
<ul>
<li><a href="classes.html">Class index</a></li>
<li><a href="functions.html">Function index</a></li>
<li><a href="modules.html">Modules</a></li>
<li><a href="namespaces.html">Namespaces</a></li>
<li><a href="qtglobal.html">Global Declarations</a></li>
<li><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</li>
<li><a href="#">Qt Topics</a>
<ul>
<li><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li><a href="supported-platforms.html">Supported Platforms</a></li>
<li><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</li>
<li><a href="#">Examples</a>
<ul>
<li><a href="all-examples.html">Examples</a></li>
<li><a href="tutorials.html">Tutorials</a></li>
<li><a href="demos.html">Demos</a></li>
<li><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="wrapper">
<div class="hd">
<span></span>
</div>
<div class="bd group">
<div class="sidebar">
<div class="searchlabel">
Search index:</div>
<div class="search" id="sidebarsearch">
<form id="qtdocsearch" action="" onsubmit="return false;">
<fieldset>
<input type="text" name="searchstring" id="pageType" value="" />
<div id="resultdialog">
<a href="#" id="resultclose">Close</a>
<p id="resultlinks" class="all"><a href="#" id="showallresults">All</a> | <a href="#" id="showapiresults">API</a> | <a href="#" id="showarticleresults">Articles</a> | <a href="#" id="showexampleresults">Examples</a></p>
<p id="searchcount" class="all"><span id="resultcount"></span><span id="apicount"></span><span id="articlecount"></span><span id="examplecount"></span> results:</p>
<ul id="resultlist" class="all">
</ul>
</div>
</fieldset>
</form>
</div>
<div class="box first bottombar" id="lookup">
<h2 title="API Lookup"><span></span>
API Lookup</h2>
<div id="list001" class="list">
<ul id="ul001" >
<li class="defaultLink"><a href="classes.html">Class index</a></li>
<li class="defaultLink"><a href="functions.html">Function index</a></li>
<li class="defaultLink"><a href="modules.html">Modules</a></li>
<li class="defaultLink"><a href="namespaces.html">Namespaces</a></li>
<li class="defaultLink"><a href="qtglobal.html">Global Declarations</a></li>
<li class="defaultLink"><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</div>
</div>
<div class="box bottombar" id="topics">
<h2 title="Qt Topics"><span></span>
Qt Topics</h2>
<div id="list002" class="list">
<ul id="ul002" >
<li class="defaultLink"><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li class="defaultLink"><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li class="defaultLink"><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li class="defaultLink"><a href="supported-platforms.html">Supported Platforms</a></li>
<li class="defaultLink"><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li class="defaultLink"><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</div>
</div>
<div class="box" id="examples">
<h2 title="Examples"><span></span>
Examples</h2>
<div id="list003" class="list">
<ul id="ul003">
<li class="defaultLink"><a href="all-examples.html">Examples</a></li>
<li class="defaultLink"><a href="tutorials.html">Tutorials</a></li>
<li class="defaultLink"><a href="demos.html">Demos</a></li>
<li class="defaultLink"><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</div>
</div>
</div>
<div class="wrap">
<div class="toolbar">
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li>Porting to Qt 4 - Drag and Drop</li>
</ul>
</div>
<div class="toolbuttons toolblock">
<ul>
<li id="smallA" class="t_button">A</li>
<li id="medA" class="t_button active">A</li>
<li id="bigA" class="t_button">A</li>
<li id="print" class="t_button"><a href="javascript:this.print();">
<span>Print</span></a></li>
</ul>
</div>
</div>
<div class="content mainContent">
<link rel="prev" href="porting4-virtual-functions.html" />
<link rel="next" href="porting4-designer.html" />
<p class="naviNextPrevious headerNavi">
<a class="prevPage" href="porting4-virtual-functions.html">Porting to Qt 4 - Virtual Functions</a>
<a class="nextPage" href="porting4-designer.html">Porting UI Files to Qt 4</a>
</p><p/>
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#dragging">Dragging</a></li>
<li class="level1"><a href="#dropping">Dropping</a></li>
<li class="level1"><a href="#mime-types-and-data">MIME Types and Data</a></li>
</ul>
</div>
<h1 class="title">Porting to Qt 4 - Drag and Drop</h1>
<span class="subtitle"></span>
<!-- $$$porting4-dnd.html-description -->
<div class="descr"> <a name="details"></a>
<p>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.</p>
<a name="dragging"></a>
<h2>Dragging</h2>
<p>In Qt 3, drag operations are encapsulated by <tt>QDragObject</tt> (see <a href="q3dragobject.html" class="compat">Q3DragObject</a>) 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 <a href="q3dragobject.html#drag">drag()</a> function is called, and it receives no information about how the operation ended.</p>
<pre class="cpp"> <span class="type">void</span> MyQt3Widget<span class="operator">::</span>customStartDragFunction()
{
<span class="type">QDragObject</span> <span class="operator">*</span>d <span class="operator">=</span> <span class="keyword">new</span> <span class="type">QTextDrag</span>( myHighlightedText()<span class="operator">,</span> <span class="keyword">this</span> );
d<span class="operator">-</span><span class="operator">></span>dragCopy();
<span class="comment">// do NOT delete d.</span>
}</pre>
<p>Similarly, in Qt 4, drag operations are also initiated when a <a href="qdrag.html">QDrag</a> object is constructed and its <a href="qdrag.html#exec">exec()</a> 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 <a href="qdrag.html#exec">exec()</a>.</p>
<pre class="cpp"> <span class="type">void</span> MyWidget<span class="operator">::</span>mousePressEvent(<span class="type"><a href="qmouseevent.html">QMouseEvent</a></span> <span class="operator">*</span>event)
{
<span class="keyword">if</span> (event<span class="operator">-</span><span class="operator">></span>button() <span class="operator">=</span><span class="operator">=</span> <span class="type"><a href="qt.html">Qt</a></span><span class="operator">::</span>LeftButton) {
<span class="type"><a href="qdrag.html">QDrag</a></span> <span class="operator">*</span>drag <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qdrag.html">QDrag</a></span>(<span class="keyword">this</span>);
<span class="type"><a href="qmimedata.html">QMimeData</a></span> <span class="operator">*</span>mimeData <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qmimedata.html">QMimeData</a></span>;
mimeData<span class="operator">-</span><span class="operator">></span>setText(text);
mimeData<span class="operator">-</span><span class="operator">></span>setImageData(image);
drag<span class="operator">-</span><span class="operator">></span>setMimeData(mimeData);
drag<span class="operator">-</span><span class="operator">></span>setPixmap(iconPixmap);
<span class="type"><a href="qt.html">Qt</a></span><span class="operator">::</span>DropAction dropAction <span class="operator">=</span> drag<span class="operator">-</span><span class="operator">></span>exec();
...
event<span class="operator">-</span><span class="operator">></span>accept();
}
}</pre>
<p>A key difference in the above code is the use of the <a href="qmimedata.html">QMimeData</a> class to hold information about the data that is transferred. Qt 3 relies on subclasses of <tt>QDragObject</tt> to provide support for specific MIME types; in Qt 4, the use of <a href="qmimedata.html">QMimeData</a> as a generic container for data makes the relationship between MIME type and data more tranparent. <a href="qmimedata.html">QMimeData</a> is described in more detail later in this document.</p>
<a name="dropping"></a>
<h2>Dropping</h2>
<p>In both Qt 3 and Qt 4, it is possible to prepare a custom widget to accept dropped data by enabling the <a href="qwidget.html#acceptDrops-prop">acceptDrops</a> 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 <a href="qwidget.html#dragEnterEvent">dragEnterEvent()</a> 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.</p>
<p>In Qt 3, the drag enter event is handled by checking whether each of the standard <tt>QDragObject</tt> subclasses can decode the data supplied, and indicating success or failure of these checks via the event's <a href="qdragmoveevent.html#accept">accept()</a> function, as shown in this simple example:</p>
<pre class="cpp"> <span class="type">void</span> MyQt3Widget<span class="operator">::</span>dragEnterEvent(<span class="type"><a href="qdragenterevent.html">QDragEnterEvent</a></span><span class="operator">*</span> event)
{
event<span class="operator">-</span><span class="operator">></span>accept(
<span class="type">QTextDrag</span><span class="operator">::</span>canDecode(event) <span class="operator">|</span><span class="operator">|</span>
<span class="type">QImageDrag</span><span class="operator">::</span>canDecode(event)
);
}</pre>
<p>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:</p>
<pre class="cpp"> <span class="type">void</span> MyWidget<span class="operator">::</span>dragEnterEvent(<span class="type"><a href="qdragenterevent.html">QDragEnterEvent</a></span> <span class="operator">*</span>event)
{
<span class="keyword">if</span> (event<span class="operator">-</span><span class="operator">></span>mimeData()<span class="operator">-</span><span class="operator">></span>hasText() <span class="operator">|</span><span class="operator">|</span> event<span class="operator">-</span><span class="operator">></span>mimeData()<span class="operator">-</span><span class="operator">></span>hasImage())
event<span class="operator">-</span><span class="operator">></span>acceptProposedAction();
}</pre>
<p>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 <a href="dnd.html#overriding-proposed-actions">this can be overridden</a> if required.</p>
<p>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 <a href="qwidget.html#dropEvent">dropEvent()</a> that looks like the following:</p>
<pre class="cpp"> <span class="type">void</span> MyQt3Widget<span class="operator">::</span>dropEvent(<span class="type"><a href="qdropevent.html">QDropEvent</a></span><span class="operator">*</span> event)
{
<span class="type"><a href="qimage.html">QImage</a></span> image;
<span class="type"><a href="qstring.html">QString</a></span> text;
<span class="keyword">if</span> ( <span class="type">QImageDrag</span><span class="operator">::</span>decode(event<span class="operator">,</span> image) ) {
insertImageAt(image<span class="operator">,</span> event<span class="operator">-</span><span class="operator">></span>pos());
} <span class="keyword">else</span> <span class="keyword">if</span> ( <span class="type">QTextDrag</span><span class="operator">::</span>decode(event<span class="operator">,</span> text) ) {
insertTextAt(text<span class="operator">,</span> event<span class="operator">-</span><span class="operator">></span>pos());
}
}</pre>
<p>In Qt 4, the event is handled in a similar way:</p>
<pre class="cpp"> <span class="type">void</span> MyWidget<span class="operator">::</span>dropEvent(<span class="type"><a href="qdropevent.html">QDropEvent</a></span> <span class="operator">*</span>event)
{
<span class="keyword">if</span> (event<span class="operator">-</span><span class="operator">></span>mimeData()<span class="operator">-</span><span class="operator">></span>hasText())
dataLabel<span class="operator">-</span><span class="operator">></span>setText(event<span class="operator">-</span><span class="operator">></span>mimeData()<span class="operator">-</span><span class="operator">></span>text());
<span class="keyword">else</span> <span class="keyword">if</span> (event<span class="operator">-</span><span class="operator">></span>mimeData()<span class="operator">-</span><span class="operator">></span>hasImage()) {
<span class="type"><a href="qvariant.html">QVariant</a></span> imageData <span class="operator">=</span> event<span class="operator">-</span><span class="operator">></span>mimeData()<span class="operator">-</span><span class="operator">></span>imageData();
dataLabel<span class="operator">-</span><span class="operator">></span>setPixmap(qvariant_cast<span class="operator"><</span><span class="type"><a href="qpixmap.html">QPixmap</a></span><span class="operator">></span>(imageData));
}
event<span class="operator">-</span><span class="operator">></span>acceptProposedAction();
}</pre>
<p>It is also possible to extract data stored for a particular MIME type if it was specified by the drag source.</p>
<a name="mime-types-and-data"></a>
<h2>MIME Types and Data</h2>
<p>In Qt 3, data to be transferred in drag and drop operations is encapsulated in instances of <tt>QDragObject</tt> and its subclasses, representing specific data formats related to common MIME type and subtypes.</p>
<p>In Qt 4, only the <a href="qmimedata.html">QMimeData</a> 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, <a href="qmimedata.html">QMimeData</a> 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.</p>
</div>
<!-- @@@porting4-dnd.html -->
<p class="naviNextPrevious footerNavi">
<a class="prevPage" href="porting4-virtual-functions.html">Porting to Qt 4 - Virtual Functions</a>
<a class="nextPage" href="porting4-designer.html">Porting UI Files to Qt 4</a>
</p>
</div>
</div>
</div>
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2013 Digia Plc and/or its
subsidiaries. Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
The documentation provided herein is licensed under the terms of the
<a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation
License version 1.3</a> as published by the Free Software Foundation.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
Digia, Qt and their respective logos are trademarks of Digia Plc
in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
<script src="scripts/functions.js" type="text/javascript"></script>
</body>
</html>
