Contents

• Public Types
• Public Functions
• Static Public Members
• Protected Functions
• Detailed Description

Detailed Description

TheQ3DragObject class encapsulates MIME-based data transfer.

Q3DragObject is the base class for all data that needs to be transferred between and within applications, both for drag and drop and for the clipboard.

See theDrag and drop documentation for an overview of how to provide drag and drop in your application.

See theQClipboard documentation for an overview of how to provide cut and paste in your application.

Thedrag() function is used to start a drag operation. You can specify theDragMode in the call or use one of the convenience functionsdragCopy(),dragMove(), ordragLink(). The drag source where the data originated is retrieved withsource(). If the data was dropped on a widget within the application,target() will return a pointer to that widget. Specify the pixmap to display during the drag withsetPixmap().

Member Type Documentation

enum Q3DragObject::DragMode

This enum describes the possible drag modes.

Member Function Documentation

Q3DragObject::Q3DragObject(QWidget * dragSource = 0, constchar * name = 0)

Constructs a drag object calledname with a parentdragSource.

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

[virtual]Q3DragObject::~Q3DragObject()

Destroys the drag object, canceling any drag and drop operation in which it is involved.

bool Q3DragObject::drag()

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

The function returns true if the caller should delete the original copy of the dragged data (but seetarget()); otherwise returns false.

If the drag containsreferences to information (e.g. file names in aQ3UriDrag are references) then the return value should always be ignored, as the target is expected to directly manipulate the content referred to by the drag object. On X11 the return value should always be correct anyway, but on Windows this is not necessarily the case; e.g. the file manager starts a background process to move files, so the sourcemust not delete the files!

Note that on Windows the drag operation will start a blocking modal event loop that will not dispatch any QTimers.

[virtual protected]bool Q3DragObject::drag(DragMode mode)

This is an overloaded function.

Starts a drag operation using the contents of this object.

At this point, the object becomes owned by Qt, not the application. You should not delete the drag object or anything it references. The actual transfer of data to the target application will be done during future event processing - after that time the drag object will be deleted.

Returns true if the dragged data was dragged as amove, indicating that the caller should remove the original source of the data (the drag object must continue to have a copy); otherwise returns false.

Themode specifies the drag mode (seeQ3DragObject::DragMode.) Normally one of the simplerdrag(),dragMove(), ordragCopy() functions would be used instead.

void Q3DragObject::dragCopy()

Starts a drag operation using the contents of this object, usingDragCopy mode. Be sure to read the constraints described indrag().

See alsodrag(),dragMove(), anddragLink().

void Q3DragObject::dragLink()

Starts a drag operation using the contents of this object, usingDragLink mode. Be sure to read the constraints described indrag().

See alsodrag(),dragCopy(), anddragMove().

bool Q3DragObject::dragMove()

Starts a drag operation using the contents of this object, usingDragMove mode. Be sure to read the constraints described indrag().

Returns true if the data was dragged as amove, indicating that the caller should remove the original source of the data (the drag object must continue to have a copy); otherwise returns false.

See alsodrag(),dragCopy(), anddragLink().

QPixmap Q3DragObject::pixmap() const

Returns the currently set pixmap, or a null pixmap if none is set.

See alsosetPixmap() andQPixmap::isNull().

QPoint Q3DragObject::pixmapHotSpot() const

Returns the currently set pixmap hotspot.

See alsosetPixmap().

[virtual]void Q3DragObject::setPixmap(QPixmap pm, constQPoint & hotspot)

Set the pixmap,pm, to display while dragging the object. The platform-specific implementation will use this where it can - so provide a small masked pixmap, and do not assume that the user will actually see it.

Thehotspot 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.

Warning: We have seen problems with drag cursors on different graphics hardware and driver software on Windows. Setting the graphics acceleration in the display settings down one tick solved the problems in all cases.

See alsopixmap().

[virtual]void Q3DragObject::setPixmap(QPixmap pm)

This is an overloaded function.

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 where they are dragging the data.

QWidget * Q3DragObject::source()

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

[static]QWidget * Q3DragObject::target()

After the drag completes, this function will return theQWidget which received the drop, or 0 if the data was dropped on another application.

This can be useful for detecting the case where drag and drop is to and from the same widget.