summaryrefslogtreecommitdiffstats
path: root/doc/dnd.doc
diff options
context:
space:
mode:
authorTimothy Pearson <kb9vqf@pearsoncomputing.net>2011-07-10 15:24:15 -0500
committerTimothy Pearson <kb9vqf@pearsoncomputing.net>2011-07-10 15:24:15 -0500
commitbd0f3345a938b35ce6a12f6150373b0955b8dd12 (patch)
tree7a520322212d48ebcb9fbe1087e7fca28b76185c /doc/dnd.doc
downloadqt3-bd0f3345a938b35ce6a12f6150373b0955b8dd12.tar.gz
qt3-bd0f3345a938b35ce6a12f6150373b0955b8dd12.zip
Add Qt3 development HEAD version
Diffstat (limited to 'doc/dnd.doc')
-rw-r--r--doc/dnd.doc383
1 files changed, 383 insertions, 0 deletions
diff --git a/doc/dnd.doc b/doc/dnd.doc
new file mode 100644
index 0000000..45acf8a
--- /dev/null
+++ b/doc/dnd.doc
@@ -0,0 +1,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.