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.

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

Dragging

To start a drag, for example in a mouse motion event, 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:

void MyWidget::startDrag()
{
    QDragObject *d = new QTextDrag( myHighlightedText(), this );
    d->dragCopy();
    // do NOT delete d.
}

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.

Dropping

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

For example, to accept text and image drops:

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());
    }
}

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:

    setData(QMimeSource*)
    QMimeSource* data()const

With these functions you can trivially put your drag-and-drop oriented information on the clipboard:

void MyWidget::copy()
{
    QApplication::clipboard()->setData(
        new QTextDrag(myHighlightedText()) );
}

void MyWidget::paste()
{
    QString text;
    if ( QTextDrag::decode(QApplication::clipboard()->data(), text) )
        insertText( text );
}

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:

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)
            );
        }
    }
}

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.

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, 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 Advanced Drag-and-Drop 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.

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 MIME types: 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 "text/plain" MIME type (ordinary unformatted text), and the Unicode formats "text/utf16" and "text/utf8"; QImageDrag provides for "image/*", where * is any image format that QImageIO supports; and the QUriDrag subclass provides "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 (IANA) provides a hierarchical list of MIME media types at the Information Sciences Institute (ISI). 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 const char* format(int i) const and QByteArray encodedData(const char* mimetype) const members, and provide a set-method to encode the media data and static members canDecode() and decode() to decode incoming data, similar to bool canDecode(QMimeSource*) const and QByteArray decode(QMimeSource*) const 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.

Advanced Drag-and-Drop

In the clipboard model, the user can cut or copy the source information, then later paste it. Similarly in the drag-and-drop model, the user can drag a copy of the information or they can drag the information itself to a new place (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:

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());
        }
    }
}

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 dragMoveEvent() is used and an area is given for which the drag is accepted or ignored:

void MyWidget::dragMoveEvent(QDragMoveEvent* event)
{
    if ( QTextDrag::canDecode(event) ) {
        MyCadItem* item = findMyItemAt(event->pos());
        if ( item )
            event->accept();
    }
}

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:

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 );
        }
    }
}

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 qApp global) also provides some drag and drop related functions: QApplication::setStartDragTime(), QApplication::setStartDragDistance(), and their corresponding getters, QApplication::startDragTime() and QApplication::startDragDistance().

Inter-operating with Other Applications

On X11, the public XDND protocol 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 <[email protected]> and Trolltech. Here is the original copyright notice:

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.

Trademarks

Qt 3.3.8