Q3DragObject Class Reference

#include <q3dragobject.h>

Inheritance diagram for Q3DragObject:

Inheritance graph
[legend]
Collaboration diagram for Q3DragObject:

Collaboration graph
[legend]
List of all members.

Detailed Description

The Q3DragObject 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 the Drag and drop documentation for an overview of how to provide drag and drop in your application.

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

The drag() function is used to start a drag operation. You can specify the DragMode in the call or use one of the convenience functions dragCopy(), dragMove(), or dragLink(). The drag source where the data originated is retrieved with source(). 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 with setPixmap().

Definition at line 49 of file q3dragobject.h.

Public Types

enum  DragMode

Public Member Functions

 Q3DragObject (QWidget *dragSource=0, const char *name=0)
virtual ~Q3DragObject ()
bool drag ()
bool dragMove ()
void dragCopy ()
void dragLink ()
virtual void setPixmap (QPixmap)
virtual void setPixmap (QPixmap, const QPoint &hotspot)
QPixmap pixmap () const
QPoint pixmapHotSpot () const
QWidget * source ()

Static Public Member Functions

static QWidget * target ()

Protected Member Functions

 Q3DragObject (Q3DragObjectPrivate &, QWidget *dragSource=0)
virtual bool drag (DragMode)

Friends

class QDragMime

Member Enumeration Documentation

enum Q3DragObject::DragMode

This enum describes the possible drag modes.

DragDefault The mode is determined heuristically. DragCopy The data is copied. DragMove The data is moved. DragLink The data is linked. DragCopyOrMove The user chooses the mode by using the {Shift} key to switch from the default copy mode to move mode.

Definition at line 69 of file q3dragobject.h.

00069 { DragDefault, DragCopy, DragMove, DragLink, DragCopyOrMove };

Constructor & Destructor Documentation

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

Constructs a drag object called name with a parent dragSource.

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

Definition at line 144 of file q3dragobject.cpp.

References QObject::setObjectName().

00145     : QObject(*(new Q3DragObjectPrivate), dragSource)
00146 {
00147     setObjectName(QLatin1String(name));
00148 }

Here is the call graph for this function:

Q3DragObject::~Q3DragObject (  )  [virtual]

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

Definition at line 161 of file q3dragobject.cpp.

00162 {
00163 }

Q3DragObject::Q3DragObject ( Q3DragObjectPrivate &  ,
QWidget *  dragSource = 0 
) [protected]

Definition at line 151 of file q3dragobject.cpp.

00152     : QObject(dd, dragSource)
00153 {
00154 }

Member Function Documentation

bool Q3DragObject::drag (  ) 

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

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

If the drag contains references to information (e.g. file names in a Q3UriDrag 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 source {must not} delete the files!

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

Definition at line 245 of file q3dragobject.cpp.

References DragDefault.

Referenced by drag(), dragCopy(), dragLink(), dragMove(), Q3Table::startDrag(), Q3TextEdit::startDrag(), Q3IconView::startDrag(), Q3ListView::startDrag(), QFileListBox::viewportMouseMoveEvent(), and Q3FileDialogQFileListView::viewportMouseMoveEvent().

00246 {
00247     return drag(DragDefault);
00248 }

bool Q3DragObject::dragMove (  ) 

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

See also:
drag() dragCopy() dragLink()

Definition at line 270 of file q3dragobject.cpp.

References drag(), and DragMove.

00271 {
00272     return drag(DragMove);
00273 }

Here is the call graph for this function:

void Q3DragObject::dragCopy (  ) 

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

See also:
drag() dragMove() dragLink()

Definition at line 283 of file q3dragobject.cpp.

References drag(), and DragCopy.

Referenced by Q3TextEdit::startDrag().

00284 {
00285     (void)drag(DragCopy);
00286 }

Here is the call graph for this function:

void Q3DragObject::dragLink (  ) 

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

See also:
drag() dragCopy() dragMove()

Definition at line 295 of file q3dragobject.cpp.

References drag(), and DragLink.

00296 {
00297     (void)drag(DragLink);
00298 }

Here is the call graph for this function:

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

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

Definition at line 201 of file q3dragobject.cpp.

Referenced by Q3IconView::dragObject().

00202 {
00203     setPixmap(pm,QPoint(-10, -10));
00204 }

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

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. For example, 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.

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.

Definition at line 182 of file q3dragobject.cpp.

References d, QDragManager::object, QDragManager::self(), and QDragManager::updatePixmap().

00183 {
00184     Q_D(Q3DragObject);
00185     d->pixmap = pm;
00186     d->hot = hotspot;
00187 #if 0
00188     QDragManager *manager = QDragManager::self();
00189     if (manager && manager->object == d->data)
00190         manager->updatePixmap();
00191 #endif
00192 }

Here is the call graph for this function:

QPixmap Q3DragObject::pixmap (  )  const

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

See also:
QPixmap::isNull()

Definition at line 211 of file q3dragobject.cpp.

00212 {
00213     return d_func()->pixmap;
00214 }

QPoint Q3DragObject::pixmapHotSpot (  )  const

Returns the currently set pixmap hotspot.

See also:
setPixmap()

Definition at line 221 of file q3dragobject.cpp.

00222 {
00223     return d_func()->hot;
00224 }

QWidget * Q3DragObject::source (  ) 

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

Definition at line 381 of file q3dragobject.cpp.

References QObject::isWidgetType(), and QObject::parent().

00382 {
00383     if (parent() && parent()->isWidgetType())
00384         return (QWidget *)parent();
00385     else
00386         return 0;
00387 }

Here is the call graph for this function:

QWidget * Q3DragObject::target (  )  [static]

After the drag completes, this function will return the QWidget 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.

Definition at line 258 of file q3dragobject.cpp.

References last_target.

Referenced by Q3TextEdit::startDrag(), and Q3IconView::startDrag().

00259 {
00260     return last_target;
00261 }

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

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. 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 a move, indicating that the caller should remove the original source of the data (the drag object must continue to have a copy); otherwise returns false.

The mode specifies the drag mode (see {Q3DragObject::DragMode}.) Normally one of the simpler drag(), dragMove(), or dragCopy() functions would be used instead.

Definition at line 335 of file q3dragobject.cpp.

References Qt::CopyAction, d, data, drag(), DragCopy, DragCopyOrMove, DragDefault, DragLink, DragMove, QMimeSource::encodedData(), QMimeSource::format(), i, last_target, Qt::LinkAction, Qt::MoveAction, QObject::parent(), QDragMime, and qobject_cast< QWidget * >().

00336 {
00337     Q_D(Q3DragObject);
00338     QDragMime *data = new QDragMime(this);
00339     int i = 0;
00340     const char *fmt;
00341     while ((fmt = format(i))) {
00342         data->setData(QLatin1String(fmt), encodedData(fmt));
00343         ++i;
00344     }
00345 
00346     QDrag *drag = new QDrag(qobject_cast<QWidget *>(parent()));
00347     drag->setMimeData(data);
00348     drag->setPixmap(d->pixmap);
00349     drag->setHotSpot(d->hot);
00350 
00351     Qt::DropActions op;
00352     switch(mode) {
00353     case DragDefault:
00354     case DragCopyOrMove:
00355         op = Qt::CopyAction|Qt::MoveAction;
00356         break;
00357     case DragCopy:
00358         op = Qt::CopyAction;
00359         break;
00360     case DragMove:
00361         op = Qt::MoveAction;
00362         break;
00363     case DragLink:
00364         op = Qt::LinkAction;
00365         break;
00366     }
00367     bool retval = (drag->start(op) == Qt::MoveAction);
00368     last_target = drag->target();
00369 
00370     return retval;
00371 }

Here is the call graph for this function:

Friends And Related Function Documentation

friend class QDragMime [friend]

Definition at line 76 of file q3dragobject.h.

Referenced by drag().

The documentation for this class was generated from the following files:
Generated on Thu Mar 15 15:54:08 2007 for Qt 4.2 User's Guide by  doxygen 1.5.1