Qt Toolkit - QDragObject Class

# QDragObject Class Reference

The QDragObject encapsulates MIME-based drag-and-drop interaction. More...

`#include <qdragobject.h>`

Inherits QObject.

Inherited by QImageDrag and QStoredDrag.

List of all member functions.

## Public Members

- QDragObject ( QWidget * dragSource = 0, const char * name = 0 )
- ~QDragObject ()
- bool drag ()
- bool dragMove ()
- void dragCopy ()
- virtual bool provides ( const char * ) const
- virtual const char* format ( int ) const
- virtual QByteArray encodedData ( const char * ) const
- void setPixmap ( QPixmap )
- void setPixmap ( QPixmap, QPoint hotspot )
- QPixmap pixmap () const
- QPoint pixmapHotSpot () const
- QWidget* source ()

## Protected Members

- virtual bool drag ( DragMode )

## Detailed Description

The QDragObject encapsulates MIME-based drag-and-drop interaction.

Drag-and-drop in Qt uses the MIME open standard, to allow independently developers applications to exchange information.

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.

To be able to receive media dropped on a widget, multiply-inherit the QDropSite class and override the dragEnterEvent(), dragMoveEvent(), dragLeaveEvent(), and dropEvent() event handler methods.

Support for specific media types is provided by subclasses of QDragObject. For example, QTextDrag provides support for the "`text/plain`" MIME type (ordinary unformated text), QImageDrag provides for "`image/``*`", where `*` is all the image formats that Qt supports, and the QUrlDrag subclass provides "`url/url`", a standard format for transfering a list of filenames.

To implement drag-and-drop of some type of media 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). This maximizes inter-operability of your software.

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 format() and encodedData() members, and provide a set-method to encode the media data and static members canDecode() and decode() to decode incoming data. QImageDrag is an example of such a class in Qt. 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 static members canDecode() and decode() to decode incoming data. QTextDrag in Qt 1.x is an example of such a class in Qt.

### Inter-operating with existing applications

On X11, the public XDND protocol is used, while on Windows Qt uses the OLE standard. On X11, XDND uses MIME, so no translation is necessary. On Windows, MIME-aware applications can communicate by using clipboard format names that are MIME types. Internally, Qt has facilities for translating all proprietary clipboard formats to and from MIME. This interface will be made public at some time, but if you need to do such translations now, contact your Qt Technical Support service.

## Member Function Documentation

### QDragObject::QDragObject ( QWidget * dragSource = 0, const char * name = 0 )

Creates a drag object which is a child of dragSource and named name.

Note that the drag object will be deleted when dragSource is.

### QDragObject::~QDragObject ()

Deletes the drag object and frees up the storage used.

### bool QDragObject::drag ()

Starts a drag operation using the contents of this object, using DragDefault mode.

See drag(DragMove) for important further information.

### bool QDragObject::drag ( DragMode mode ) `[virtual protected]`

Starts a drag operation using the contents of this object.

At this point, the object becomes owned by Qt, not the source widget. You should not delete the drag object nor anything it references (unless you make provisions in the drag object to \link QObject::destroyed() deal with such deletion\enlink). Many drag objects, such as QTextDrag do not reference any other objects. The actual transfer of data to the target application may be done during future event processing - after that time the drag object will be deleted.

Returns TRUE if the dragged data was dragged as a move, indicating that the caller should remove the original source of the data (the drag object must continue to have a copy).

The mode is one of:

- `DragDefault` - the mode is determined heuristically.
- `DragCopy` - the data is copied, never moved.
- `DragMove` - the data is moved, if dragged at all.
- `DragCopyOrMove` - the user chooses the mode by using control key to switch from the default.

Normally one of simpler drag(), dragMove(), or dragCopy() functions would be used instead.

### void QDragObject::dragCopy ()

Starts a drag operation using the contents of this object, using DragCopy mode.

See drag(DragMove) for important further information.

### bool QDragObject::dragMove ()

Starts a drag operation using the contents of this object, using DragMove mode.

See drag(DragMove) for important further information.

### QByteArray QDragObject::encodedData ( const char * ) const `[virtual]`

Returns the encoded payload of this object. The drag manager calls this when the recipient needs to see the content of the drag; this generally doesn't happen until the actual drop.

Subclasses must override this function.

### const char * QDragObject::format ( int i ) const `[virtual]`

Returns the ith format, or NULL.

### QPixmap QDragObject::pixmap () const

Returns the currently set pixmap (which isNull() if none is set).

### QPoint QDragObject::pixmapHotSpot () const

Returns the currently set pixmap hitspot.

### bool QDragObject::provides ( const char * mimeType ) const `[virtual]`

Returns TRUE if the drag object can provide the data in format mimeType. The default implementation iterates over format().

### void QDragObject::setPixmap ( QPixmap pm, QPoint hotspot )

Set the pixmap pm to display while dragging the object. The platform-specific implementation will use this in a loose fashion - so provide a small masked pixmap, but do not require that the user ever sees it in all its splendour. In particular, cursors on Windows 95 are of limited size.

The hotspot is the point on (or off) the pixmap that should be under the cursor as it is dragged. It is relative to the top-left pixel of the pixmap.

### void QDragObject::setPixmap ( QPixmap pm )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Uses a hotspot that positions the pixmap below and to the right of the mouse pointer. This allows the user to clearly see the point on the window which they are dragging the data onto.

### QWidget * QDragObject::source ()

Returns a pointer to the drag source where this object originated.

Search the documentation, FAQ, qt-interest archive and more (uses www.troll.no):

This file is part of the Qt toolkit, copyright © 1995-99 Troll Tech, all rights reserved.

It was generated from the following files:

- qdragobject.h: 1998/08/19
- qdragobject.cpp: 1998/12/07