summaryrefslogtreecommitdiffstats
path: root/doc/dnd.doc
blob: 45acf8ad249b79186f1e307d830a741d3fb74fb1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
/****************************************************************************
**
** Drag and drop documentation
**
** Copyright (C) 1992-2008 Trolltech ASA.  All rights reserved.
**
** This file is part of the Qt GUI Toolkit.
**
** This file may be used under the terms of the GNU General
** Public License versions 2.0 or 3.0 as published by the Free
** Software Foundation and appearing in the files LICENSE.GPL2
** and LICENSE.GPL3 included in the packaging of this file.
** Alternatively you may (at your option) use any later version
** of the GNU General Public License if such license has been
** publicly approved by Trolltech ASA (or its successors, if any)
** and the KDE Free Qt Foundation.
**
** Please review the following information to ensure GNU General
** Public Licensing requirements will be met:
** http://trolltech.com/products/qt/licenses/licensing/opensource/.
** If you are unsure which license is appropriate for your use, please
** review the following information:
** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
** or contact the sales department at sales@trolltech.com.
**
** This file may be used under the terms of the Q Public License as
** defined by Trolltech ASA and appearing in the file LICENSE.QPL
** included in the packaging of this file.  Licensees holding valid Qt
** Commercial licenses may use this file in accordance with the Qt
** Commercial License Agreement provided with the Software.
**
** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted
** herein.
**
**********************************************************************/

/*!
\page dnd.html

\title Drag and Drop

Drag and drop provides a simple visual mechanism which users can use
to transfer information between and within applications. (In the
literature this is referred to as a "direct manipulation model".) Drag
and drop is similar in function to the clipboard's cut-and-paste
mechanism.

\tableofcontents

For drag and drop examples see (in increasing order of
sophistication): \c qt/examples/iconview/simple_dd, \c
qt/examples/dragdrop and \c qt/examples/fileiconview. See also the
QTextEdit widget source code.


\section1 Dragging

To start a drag, for example in a \link QWidget::mouseMoveEvent()
mouse motion event\endlink, create an object of the QDragObject
subclass appropriate for your media, such as QTextDrag for text and
QImageDrag for images. Then call the drag() method. This is all you
need for simple dragging of existing types.

For example, to start dragging some text from a widget:
\code
void MyWidget::startDrag()
{
    QDragObject *d = new QTextDrag( myHighlightedText(), this );
    d->dragCopy();
    // do NOT delete d.
}
\endcode

Note that the QDragObject is not deleted after the drag. The
QDragObject needs to persist after the drag is apparently finished
since it may still be communicating with another process. Eventually
Qt will delete the object. If the widget owning the drag object is
deleted before then, any pending drop will be canceled and the drag
object deleted. For this reason, you should be careful what the object
references.

\section1 Dropping

To be able to receive media dropped on a widget, call
\link QWidget::setAcceptDrops() setAcceptDrops(TRUE)\endlink
for the widget (e.g. in its constructor), and override the
event handler methods
\link QWidget::dragEnterEvent() dragEnterEvent()\endlink and
\link QWidget::dropEvent() dropEvent()\endlink.
For more sophisticated applications overriding
\link QWidget::dragMoveEvent() dragMoveEvent()\endlink and
\link QWidget::dragLeaveEvent() dragLeaveEvent()\endlink will also be
necessary.

For example, to accept text and image drops:
\code
MyWidget::MyWidget(...) :
    QWidget(...)
{
    ...
    setAcceptDrops(TRUE);
}

void MyWidget::dragEnterEvent(QDragEnterEvent* event)
{
    event->accept(
	QTextDrag::canDecode(event) ||
	QImageDrag::canDecode(event)
    );
}

void MyWidget::dropEvent(QDropEvent* event)
{
    QImage image;
    QString text;

    if ( QImageDrag::decode(event, image) ) {
	insertImageAt(image, event->pos());
    } else if ( QTextDrag::decode(event, text) ) {
	insertTextAt(text, event->pos());
    }
}
\endcode

\section1 The Clipboard

The QDragObject, QDragEnterEvent, QDragMoveEvent, and QDropEvent
classes are all subclasses of QMimeSource: the class of objects which
provide typed information. If you base your data transfers on
QDragObject, you not only get drag-and-drop, but you also get
traditional cut-and-paste for free. The QClipboard has two functions:
\code
    setData(QMimeSource*)
    QMimeSource* data()const
\endcode
With these functions you can trivially put your drag-and-drop oriented
information on the clipboard:
\code
void MyWidget::copy()
{
    QApplication::clipboard()->setData(
	new QTextDrag(myHighlightedText()) );
}

void MyWidget::paste()
{
    QString text;
    if ( QTextDrag::decode(QApplication::clipboard()->data(), text) )
	insertText( text );
}
\endcode
You can even use QDragObject subclasses as part of file IO. For
example, if your application has a subclass of QDragObject that
encodes CAD designs in DXF format, your saving and loading code might
be:
\code
void MyWidget::save()
{
    QFile out(current_file_name);
    if ( out.open(IO_WriteOnly) ) {
	MyCadDrag tmp(current_design);
	out.writeBlock( tmp->encodedData( "image/x-dxf" ) );
    }
}

void MyWidget::load()
{
    QFile in(current_file_name);
    if ( in.open(IO_ReadOnly) ) {
	if ( !MyCadDrag::decode(in.readAll(), current_design) ) {
	    QMessageBox::warning( this, "Format error",
		tr("The file \"%1\" is not in any supported format")
		    .arg(current_file_name)
	    );
	}
    }
}
\endcode
Note how the QDragObject subclass is called "MyCadDrag", not
"MyDxfDrag": because in the future you might extend it to provide
DXF, DWG, SVF, WMF, or even QPicture data to other applications.

\section1 Drag and Drop Actions

In the simpler cases, the target of a drag-and-drop receives a copy of
the data being dragged and the source decides whether to delete the
original. This is the "Copy" action in QDropEvent. The target may also
choose to understand other actions, specifically the Move and Link
actions. If the target understands the Move action, \e{the
target} is responsible for both the copy and delete operations and
the source will not attempt to delete the data itself. If the target
understands the Link, it stores its own reference to the original
information, and again the source does not delete the original. The
most common use of drag-and-drop actions is when performing a Move
within the same widget: see the \link #advanced Advanced
Drag-and-Drop\endlink section below.

The other major use of drag actions is when using a reference type
such as text/uri-list, where the dragged data are actually references
to files or objects.

\section1 Adding New Drag and Drop Types

As suggested in the DXF example above, drag-and-drop is not limited to
text and images. Any information can be dragged and dropped. To drag
information between applications, the applications must be able to
indicate to each other which data formats they can accept and which
they can produce. This is achieved using \link
http://www.rfc-editor.org/rfc/rfc1341.txt MIME types\endlink: the drag
source provides a list of MIME types that it can produce (ordered from
most appropriate to least appropriate), and the drop target chooses
which of those it can accept. For example, QTextDrag provides support
for the "\c{text/plain}" MIME type (ordinary unformatted text), and
the Unicode formats "\c{text/utf16}" and "\c{text/utf8}"; QImageDrag
provides for "\c{image/*}", where \c{*} is any image format that
\l QImageIO supports; and the QUriDrag subclass provides
"\c{text/uri-list}", a standard format for transferring a list of
filenames (or URLs).

To implement drag-and-drop of some type of information for which there
is no available QDragObject subclass, the first and most important
step is to look for existing formats that are appropriate: the
Internet Assigned Numbers Authority (\link http://www.iana.org
IANA\endlink) provides a \link
http://www.isi.edu/in-notes/iana/assignments/media-types/ hierarchical
list of MIME media types\endlink at the Information Sciences Institute
(\link http://www.isi.edu ISI\endlink). Using standard MIME types
maximizes the inter-operability of your application with other
software now and in the future.

To support an additional media type, subclass either QDragObject or
QStoredDrag. Subclass QDragObject when you need to provide support for
multiple media types. Subclass the simpler QStoredDrag when one type
is sufficient.

Subclasses of QDragObject will override the
\link QDragObject::format()
const char* format(int i) const
\endlink and
\link QDragObject::encodedData()
QByteArray encodedData(const char* mimetype) const
\endlink
members, and provide a set-method to encode the media data and static
members canDecode() and decode() to decode incoming data, similar to
\link QImageDrag::canDecode()
bool canDecode(QMimeSource*) const
\endlink and
\link QImageDrag::decode()
QByteArray decode(QMimeSource*) const
\endlink
of QImageDrag.
Of course, you can provide drag-only or drop-only support for a media
type by omitting some of these methods.

Subclasses of QStoredDrag provide a set-method to encode the media
data and the same static members canDecode() and decode() to decode
incoming data.

\target advanced
\section1 Advanced Drag-and-Drop

In the clipboard model, the user can \e cut or \e copy the source
information, then later paste it. Similarly in the drag-and-drop
model, the user can drag a \e copy of the information or they can drag
the information itself to a new place (\e moving it). The
drag-and-drop model however has an additional complication for the
programmer: the program doesn't know whether the user wants to cut or
copy until the drop (paste) is done! For dragging between
applications, it makes no difference, but for dragging within an
application, the application must take a little extra care not to
tread on its own feet. For example, to drag text around in a document,
the drag start point and the drop event might look like this:

\code
void MyEditor::startDrag()
{
    QDragObject *d = new QTextDrag(myHighlightedText(), this);
    if ( d->drag() && d->target() != this )
	cutMyHighlightedText();
}

void MyEditor::dropEvent(QDropEvent* event)
{
    QString text;

    if ( QTextDrag::decode(event, text) ) {
	if ( event->source() == this && event->action() == QDropEvent::Move ) {
	    // Careful not to tread on my own feet
	    event->acceptAction();
	    moveMyHighlightedTextTo(event->pos());
	} else {
	    pasteTextAt(text, event->pos());
	}
    }
}
\endcode

Some widgets are more specific than just a "yes" or "no" response when
data is dragged onto them. For example, a CAD program might only
accept drops of text onto text objects in the view. In these cases,
the \link QWidget::dragMoveEvent() dragMoveEvent()\endlink is used and
an \e area is given for which the drag is accepted or ignored:
\code
void MyWidget::dragMoveEvent(QDragMoveEvent* event)
{
    if ( QTextDrag::canDecode(event) ) {
	MyCadItem* item = findMyItemAt(event->pos());
	if ( item )
	    event->accept();
    }
}
\endcode
If the computations to find objects are particularly slow, you might
achieve improved performance if you tell the system an area for which
you promise the acceptance persists:
\code
void MyWidget::dragMoveEvent(QDragMoveEvent* event)
{
    if ( QTextDrag::canDecode(event) ) {
	MyCadItem* item = findMyItemAt(event->pos());
	if ( item ) {
	    QRect r = item->areaRelativeToMeClippedByAnythingInTheWay();
	    if ( item->type() == MyTextType )
		event->accept( r );
	    else
		event->ignore( r );
	}
    }
}
\endcode

The dragMoveEvent() can also be used if you need to give visual
feedback as the drag progresses, to start timers, to scroll the
window, or whatever is appropriate (don't forget to stop the scrolling
and timers in a dragLeaveEvent() though).

The QApplication object (available as the \c qApp global) also
provides some drag and drop related functions:
\l{QApplication::setStartDragTime()},
\l{QApplication::setStartDragDistance()}, and their corresponding
getters, \l{QApplication::startDragTime()} and
\l{QApplication::startDragDistance()}.

\section1 Inter-operating with Other Applications

On X11, the public <a class="r"
href="http://www.newplanetsoftware.com/xdnd/">XDND protocol</a> is
used, while on Windows Qt uses the OLE standard, and Qt/Mac uses the
Carbon Drag Manager. On X11, XDND uses MIME, so no translation is
necessary. The Qt API is the same regardless of the platform. On
Windows, MIME-aware applications can communicate by using clipboard
format names that are MIME types. Already some Windows applications
use MIME naming conventions for their clipboard formats. Internally,
Qt has facilities for translating proprietary clipboard formats to and
from MIME types. This interface will be made public at some time, but
if you need to do such translations now, contact your Qt Technical
Support service.

On X11, Qt also supports drops via the Motif Drag\&Drop Protocol. The
implementation incorporates some code that was originally written by
Daniel Dardailler, and adapted for Qt by Matt Koss \<koss@napri.sk\>
and Trolltech. Here is the original copyright notice:

\legalese

Copyright 1996 Daniel Dardailler.

Permission to use, copy, modify, distribute, and sell this software
for any purpose is hereby granted without fee, provided that the above
copyright notice appear in all copies and that both that copyright
notice and this permission notice appear in supporting documentation,
and that the name of Daniel Dardailler not be used in advertising or
publicity pertaining to distribution of the software without specific,
written prior permission. Daniel Dardailler makes no representations
about the suitability of this software for any purpose. It is
provided "as is" without express or implied warranty.

Modifications Copyright 1999 Matt Koss, under the same license as
above.

*/ // NOTE: That notice is from qmotifdnd_x11.cpp.