QDrag Class Reference

\inmodule QtGui More...

#include <qdrag.h>

Inheritance diagram for QDrag:

Collaboration diagram for QDrag:

Signals
void	actionChanged (Qt::DropAction action)
	This signal is emitted when the action associated with the drag changes.
void	targetChanged (QObject *newTarget)
	This signal is emitted when the target of the drag and drop operation changes, with newTarget the new target.
Signals inherited from QObject
void	destroyed (QObject *=nullptr)
	This signal is emitted immediately before the object obj is destroyed, after any instances of QPointer have been notified, and cannot be blocked.
void	objectNameChanged (const QString &objectName, QPrivateSignal)
	This signal is emitted after the object's name has been changed.

Public Member Functions
	QDrag (QObject *dragSource)
	Constructs a new drag object for the widget specified by dragSource.
	~QDrag ()
	Destroys the drag object.
void	setMimeData (QMimeData *data)
	Sets the data to be sent to the given MIME data.
QMimeData *	mimeData () const
	Returns the MIME data that is encapsulated by the drag object.
void	setPixmap (const QPixmap &)
	Sets pixmap as the pixmap used to represent the data in a drag and drop operation.
QPixmap	pixmap () const
	Returns the pixmap used to represent the data in a drag and drop operation.
void	setHotSpot (const QPoint &hotspot)
	Sets the position of the hot spot relative to the top-left corner of the pixmap used to the point specified by hotspot.
QPoint	hotSpot () const
	Returns the position of the hot spot relative to the top-left corner of the cursor.
QObject *	source () const
	Returns the source of the drag object.
QObject *	target () const
	Returns the target of the drag and drop operation.
Qt::DropAction	exec (Qt::DropActions supportedActions=Qt::MoveAction)
Qt::DropAction	exec (Qt::DropActions supportedActions, Qt::DropAction defaultAction)
void	setDragCursor (const QPixmap &cursor, Qt::DropAction action)
	Sets the drag cursor for the action.
QPixmap	dragCursor (Qt::DropAction action) const
	Returns the drag cursor for the action.
Qt::DropActions	supportedActions () const
	Returns the set of possible drop actions for this drag operation.
Qt::DropAction	defaultAction () const
	Returns the default proposed drop action for this drag operation.
Public Member Functions inherited from QObject
Q_INVOKABLE	QObject (QObject *parent=nullptr)
	Constructs an object with parent object parent.
virtual	~QObject ()
	Destroys the object, deleting all its child objects.
virtual bool	event (QEvent *event)
	This virtual function receives events to an object and should return true if the event e was recognized and processed.
virtual bool	eventFilter (QObject *watched, QEvent *event)
	Filters events if this object has been installed as an event filter for the watched object.
QString	objectName () const
Q_WEAK_OVERLOAD void	setObjectName (const QString &name)
	Sets the object's name to name.
void	setObjectName (QAnyStringView name)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
QBindable< QString >	bindableObjectName ()
bool	isWidgetType () const
	Returns true if the object is a widget; otherwise returns false.
bool	isWindowType () const
	Returns true if the object is a window; otherwise returns false.
bool	isQuickItemType () const
	Returns true if the object is a QQuickItem; otherwise returns false.
bool	signalsBlocked () const noexcept
	Returns true if signals are blocked; otherwise returns false.
bool	blockSignals (bool b) noexcept
	If block is true, signals emitted by this object are blocked (i.e., emitting a signal will not invoke anything connected to it).
QThread *	thread () const
	Returns the thread in which the object lives.
void	moveToThread (QThread *thread)
	Changes the thread affinity for this object and its children.
int	startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)
	This is an overloaded function that will start a timer of type timerType and a timeout of interval milliseconds.
int	startTimer (std::chrono::milliseconds time, Qt::TimerType timerType=Qt::CoarseTimer)
void	killTimer (int id)
	Kills the timer with timer identifier, id.
template<typename T >
T	findChild (const QString &aName=QString(), Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
	Returns the child of this object that can be cast into type T and that is called name, or \nullptr if there is no such object.
template<typename T >
QList< T >	findChildren (const QString &aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
	Returns all children of this object with the given name that can be cast to type T, or an empty list if there are no such objects.
template<typename T >
QList< T >	findChildren (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
const QObjectList &	children () const
	Returns a list of child objects.
void	setParent (QObject *parent)
	Makes the object a child of parent.
void	installEventFilter (QObject *filterObj)
	Installs an event filter filterObj on this object.
void	removeEventFilter (QObject *obj)
	Removes an event filter object obj from this object.
QMetaObject::Connection	connect (const QObject *sender, const char *signal, const char *member, Qt::ConnectionType type=Qt::AutoConnection) const
bool	disconnect (const char *signal=nullptr, const QObject *receiver=nullptr, const char *member=nullptr) const
bool	disconnect (const QObject *receiver, const char *member=nullptr) const
void	dumpObjectTree () const
	Dumps a tree of children to the debug output.
void	dumpObjectInfo () const
	Dumps information about signal connections, etc.
bool	setProperty (const char *name, const QVariant &value)
	Sets the value of the object's name property to value.
bool	setProperty (const char *name, QVariant &&value)
QVariant	property (const char *name) const
	Returns the value of the object's name property.
QList< QByteArray >	dynamicPropertyNames () const
QBindingStorage *	bindingStorage ()
const QBindingStorage *	bindingStorage () const
QObject *	parent () const
	Returns a pointer to the parent object.
bool	inherits (const char *classname) const
	Returns true if this object is an instance of a class that inherits className or a QObject subclass that inherits className; otherwise returns false.

Static Public Member Functions
static void	cancel ()
	Cancels a drag operation initiated by Qt.
Static Public Member Functions inherited from QObject
static QMetaObject::Connection	connect (const QObject *sender, const char *signal, const QObject *receiver, const char *member, Qt::ConnectionType=Qt::AutoConnection)
	\threadsafe
static QMetaObject::Connection	connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type=Qt::AutoConnection)
template<typename Func1 , typename Func2 >
static QMetaObject::Connection	connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const typename QtPrivate::ContextTypeForFunctor< Func2 >::ContextType *context, Func2 &&slot, Qt::ConnectionType type=Qt::AutoConnection)
template<typename Func1 , typename Func2 >
static QMetaObject::Connection	connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, Func2 &&slot)
static bool	disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *member)
	\threadsafe
static bool	disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &member)
static bool	disconnect (const QMetaObject::Connection &)
	Disconnect a connection.
template<typename Func1 , typename Func2 >
static bool	disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const typename QtPrivate::FunctionPointer< Func2 >::Object *receiver, Func2 slot)
template<typename Func1 >
static bool	disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const QObject *receiver, void **zero)

Friends
class	QDragManager

Additional Inherited Members
Public Slots inherited from QObject
void	deleteLater ()
	\threadsafe
Protected Member Functions inherited from QObject
QObject *	sender () const
	Returns a pointer to the object that sent the signal, if called in a slot activated by a signal; otherwise it returns \nullptr.
int	senderSignalIndex () const
int	receivers (const char *signal) const
	Returns the number of receivers connected to the signal.
bool	isSignalConnected (const QMetaMethod &signal) const
virtual void	timerEvent (QTimerEvent *event)
	This event handler can be reimplemented in a subclass to receive timer events for the object.
virtual void	childEvent (QChildEvent *event)
	This event handler can be reimplemented in a subclass to receive child events.
virtual void	customEvent (QEvent *event)
	This event handler can be reimplemented in a subclass to receive custom events.
virtual void	connectNotify (const QMetaMethod &signal)
virtual void	disconnectNotify (const QMetaMethod &signal)
	QObject (QObjectPrivate &dd, QObject *parent=nullptr)
Protected Attributes inherited from QObject
QScopedPointer< QObjectData >	d_ptr
Properties inherited from QObject
QString	objectName
	the name of this object
Related Symbols inherited from QObject
template< class T > T	qobject_cast (const QObject *object)
	Returns the given object cast to type T if the object is of type T (or of a subclass); otherwise returns \nullptr.
template< typename T > T	qFindChildqFindChildren (const QObject *obj, const QString &name)()
template< typename T > QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QString &name)()
	QObjectList
	\macro Q_CLASSINFO(Name, Value)

Detailed Description

\inmodule QtGui

The QDrag class provides support for MIME-based drag and drop data transfer.

Drag and drop is an intuitive way for users to copy or move data around in an application, and is used in many desktop environments as a mechanism for copying data between applications. Drag and drop support in Qt is centered around the QDrag class that handles most of the details of a drag and drop operation.

The data to be transferred by the drag and drop operation is contained in a QMimeData object. This is specified with the setMimeData() function in the following way:

        QDrag *drag = new QDrag(this);
        QMimeData *mimeData = new QMimeData;
 
        mimeData->setText(commentEdit->toPlainText());
        drag->setMimeData(mimeData);

Note that setMimeData() assigns ownership of the QMimeData object to the QDrag object. The QDrag must be constructed on the heap with a parent QObject to ensure that Qt can clean up after the drag and drop operation has been completed.

A pixmap can be used to represent the data while the drag is in progress, and will move with the cursor to the drop target. This pixmap typically shows an icon that represents the MIME type of the data being transferred, but any pixmap can be set with setPixmap(). The cursor's hot spot can be given a position relative to the top-left corner of the pixmap with the setHotSpot() function. The following code positions the pixmap so that the cursor's hot spot points to the center of its bottom edge:

    drag->setHotSpot(QPoint(drag->pixmap().width()/2,
                            drag->pixmap().height()));

Note

On X11, the pixmap may not be able to keep up with the mouse movements if the hot spot causes the pixmap to be displayed directly under the cursor.

The source and target widgets can be found with source() and target(). These functions are often used to determine whether drag and drop operations started and finished at the same widget, so that special behavior can be implemented.

QDrag only deals with the drag and drop operation itself. It is up to the developer to decide when a drag operation begins, and how a QDrag object should be constructed and used. For a given widget, it is often necessary to reimplement \l{QWidget::mousePressEvent()}{mousePressEvent()} to determine whether the user has pressed a mouse button, and reimplement \l{QWidget::mouseMoveEvent()}{mouseMoveEvent()} to check whether a QDrag is required.

See also

{Drag and Drop}, QClipboard, QMimeData, {Draggable Icons Example}, {Draggable Text Example}, {Drop Site Example}, {Fridge Magnets Example}

Definition at line 21 of file qdrag.h.

Constructor & Destructor Documentation

QDrag()

QDrag::QDrag ( QObject *  dragSource )

explicit

Constructs a new drag object for the widget specified by dragSource.

Definition at line 73 of file qdrag.cpp.

References d, and Qt::IgnoreAction.

~QDrag()

QDrag::~QDrag

(

)

Destroys the drag object.

Definition at line 89 of file qdrag.cpp.

References d.

Member Function Documentation

actionChanged

void QDrag::actionChanged ( Qt::DropAction  action )

signal

This signal is emitted when the action associated with the drag changes.

See also

targetChanged()

Referenced by QPlatformDrag::updateAction().

Here is the caller graph for this function:

cancel()

void QDrag::cancel ( )

static

Cancels a drag operation initiated by Qt.

Note

This is currently implemented on Windows and X11.

Since

5.7

See also

exec()

Definition at line 334 of file qdrag.cpp.

References QGuiApplicationPrivate::platformIntegration().

Here is the call graph for this function:

defaultAction()

Qt::DropAction QDrag::defaultAction

(

)

const

Returns the default proposed drop action for this drag operation.

See also

exec(), supportedActions()

Definition at line 320 of file qdrag.cpp.

References d.

Referenced by QPlatformDrag::defaultAction(), and QCocoaDrag::defaultAction().

Here is the caller graph for this function:

dragCursor()

QPixmap QDrag::dragCursor

(

Qt::DropAction

action

)

const

Returns the drag cursor for the action.

Since

5.0

Definition at line 277 of file qdrag.cpp.

References Qt::CopyAction, d, Qt::DragCopyCursor, Qt::DragLinkCursor, Qt::DragMoveCursor, Qt::ForbiddenCursor, QGuiApplicationPrivate::getPixmapCursor(), QGuiApplicationPrivate::instance(), it, Qt::LinkAction, and Qt::MoveAction.

Referenced by QWindowsOleDropSource::createCursors(), QWindowsOleDropSource::GiveFeedback(), and QBasicDrag::updateCursor().

Here is the call graph for this function:

Here is the caller graph for this function:

exec() [1/2]

Qt::DropAction QDrag::exec	(	Qt::DropActions	supportedActions,
		Qt::DropAction	defaultDropAction
	)

Since

4.3

Starts the drag and drop operation and returns a value indicating the requested drop action when it is completed. The drop actions that the user can choose from are specified in supportedActions.

The defaultDropAction determines which action will be proposed when the user performs a drag without using modifier keys.

{Note:} On Linux and \macos, the drag and drop operation can take some time, but this function does not block the event loop. Other events are still delivered to the application while the operation is performed. On Windows, the Qt event loop is blocked during the operation. However, QDrag::exec() on Windows causes processEvents() to be called frequently to keep the GUI responsive. If any loops or operations are called while a drag operation is active, it will block the drag operation.

Definition at line 223 of file qdrag.cpp.

References Qt::CopyAction, d, QString::data(), QDragManager::drag(), Qt::IgnoreAction, QString::isNull(), Qt::LinkAction, Qt::MoveAction, qWarning, QDragManager::self(), and supportedActions().

Here is the call graph for this function:

exec() [2/2]

Qt::DropAction QDrag::exec

(

Qt::DropActions

supportedActions = Qt::MoveAction

)

Since

4.3

Starts the drag and drop operation and returns a value indicating the requested drop action when it is completed. The drop actions that the user can choose from are specified in supportedActions. The default proposed action will be selected among the allowed actions in the following order: Move, Copy and Link.

{Note:} On Linux and \macos, the drag and drop operation can take some time, but this function does not block the event loop. Other events are still delivered to the application while the operation is performed. On Windows, the Qt event loop is blocked during the operation.

See also

cancel()

Definition at line 199 of file qdrag.cpp.

References exec(), Qt::IgnoreAction, and supportedActions().

Referenced by QtPrivate::QColorWell::mouseMoveEvent(), QtPrivate::QColorShowLabel::mouseMoveEvent(), DragWidget::mouseMoveEvent(), CustomItem::mousePressEvent(), MainWindow::mousePressEvent(), QWidgetTextControlPrivate::startDrag(), and QQuickDragAttachedPrivate::startDrag().

Here is the call graph for this function:

Here is the caller graph for this function:

hotSpot()

QPoint QDrag::hotSpot

(

)

const

Returns the position of the hot spot relative to the top-left corner of the cursor.

Definition at line 156 of file qdrag.cpp.

References d.

Referenced by QWindowsOleDropSource::createCursors(), QCocoaDrag::drag(), and QBasicDrag::recreateShapedPixmapWindow().

Here is the caller graph for this function:

mimeData()

QMimeData * QDrag::mimeData

(

)

const

Returns the MIME data that is encapsulated by the drag object.

Definition at line 112 of file qdrag.cpp.

References d.

Referenced by QCocoaDrag::drag(), QCocoaDrag::dragMimeData(), QXcbDrag::handleDrop(), QXcbDrag::handleSelectionRequest(), and QXcbDropData::xdndObtainData().

Here is the caller graph for this function:

pixmap()

QPixmap QDrag::pixmap

(

)

const

Returns the pixmap used to represent the data in a drag and drop operation.

Definition at line 132 of file qdrag.cpp.

References d.

Referenced by QWindowsOleDropSource::createCursors(), FinalWidget::mouseMoveEvent(), QBasicDrag::recreateShapedPixmapWindow(), and setPixmap().

Here is the caller graph for this function:

setDragCursor()

void QDrag::setDragCursor	(	const QPixmap &	cursor,
		Qt::DropAction	action
	)

Sets the drag cursor for the action.

This allows you to override the default native cursors. To revert to using the native cursor for action pass in a null QPixmap as cursor.

Note: setting the drag cursor for IgnoreAction may not work on all platforms. X11 and macOS has been tested to work. Windows does not support it.

Definition at line 262 of file qdrag.cpp.

References cursor, and d.

setHotSpot()

void QDrag::setHotSpot

(

const QPoint &

hotspot

)

Sets the position of the hot spot relative to the top-left corner of the pixmap used to the point specified by hotspot.

{Note:} on X11, the pixmap may not be able to keep up with the mouse movements if the hot spot causes the pixmap to be displayed directly under the cursor.

Definition at line 146 of file qdrag.cpp.

References d.

Referenced by FinalWidget::mouseMoveEvent(), and QQuickDragAttachedPrivate::startDrag().

Here is the caller graph for this function:

setMimeData()

void QDrag::setMimeData

(

QMimeData *

data

)

Sets the data to be sent to the given MIME data.

Ownership of the data is transferred to the QDrag object.

Definition at line 99 of file qdrag.cpp.

References d.

Referenced by QtPrivate::QColorWell::mouseMoveEvent(), QtPrivate::QColorShowLabel::mouseMoveEvent(), DragWidget::mouseMoveEvent(), FinalWidget::mouseMoveEvent(), CustomItem::mousePressEvent(), MainWindow::mousePressEvent(), QWidgetTextControlPrivate::startDrag(), and QQuickDragAttachedPrivate::startDrag().

Here is the caller graph for this function:

setPixmap()

void QDrag::setPixmap

(

const QPixmap &

pixmap

)

Sets pixmap as the pixmap used to represent the data in a drag and drop operation.

You can only set a pixmap before the drag is started.

Definition at line 123 of file qdrag.cpp.

References d, and pixmap().

Referenced by QtPrivate::QColorWell::mouseMoveEvent(), QtPrivate::QColorShowLabel::mouseMoveEvent(), FinalWidget::mouseMoveEvent(), MainWindow::mousePressEvent(), and QQuickDragAttachedPrivate::startDrag().

Here is the call graph for this function:

Here is the caller graph for this function:

source()

QObject * QDrag::source

(

)

const

Returns the source of the drag object.

This is the widget where the drag and drop operation originated.

Definition at line 166 of file qdrag.cpp.

References d.

Referenced by QDragManager::source().

Here is the caller graph for this function:

supportedActions()

Qt::DropActions QDrag::supportedActions

(

)

const

Returns the set of possible drop actions for this drag operation.

See also

exec(), defaultAction()

Definition at line 308 of file qdrag.cpp.

References d.

Referenced by QCocoaDrag::defaultAction(), QXcbDrag::drop(), exec(), exec(), and QXcbDrag::move().

Here is the caller graph for this function:

target()

QObject * QDrag::target

(

)

const

Returns the target of the drag and drop operation.

This is the widget where the drag object was dropped.

Definition at line 176 of file qdrag.cpp.

References d.

Referenced by QDragManager::drag(), QDragManager::setCurrentTarget(), and QWidgetTextControlPrivate::startDrag().

Here is the caller graph for this function:

targetChanged

void QDrag::targetChanged ( QObject *  newTarget )

signal

This signal is emitted when the target of the drag and drop operation changes, with newTarget the new target.

See also

target(), actionChanged()

Referenced by QDragManager::setCurrentTarget().

Here is the caller graph for this function:

Friends And Related Symbol Documentation

QDragManager

friend class QDragManager

friend

Definition at line 57 of file qdrag.h.

---

The documentation for this class was generated from the following files:

• qtbase/src/gui/kernel/qdrag.h
• qtbase/src/gui/kernel/qdrag.cpp