Класс QDrag

Класс QDrag предоставляет поддержку передачи данных методом перетаскивания (drag and drop) на основе MIME. Подробнее...

• Список всех членов, включая унаследованные
• Устаревшие члены

Открытые функции

• 32 открытых функций, унаследованных от QObject

Сигналы

• 2 сигнала, унаследованных от QObject

Статические открытые члены

• 11 статических открытых членов, унаследованных от QObject

Дополнительные унаследованные члены

• 1 свойство, унаследованное от QObject
• 1 открытый слот, унаследованный от QObject
• 9 защищённых функций, унаследованных от QObject

Подробное описание

Класс QDrag предоставляет поддержку передачи данных методом перетаскивания (drag and drop) на основе MIME.

Перетаскивание (drag and drop) — интуитивный способ копирования или перемещения данных в приложении. В многих настольных средах он используется для копирования данных между приложениями. Поддержка перетаскивания в Qt основана на классе QDrag, который обрабатывает большинство деталей операции перетаскивания.

Данные, передаваемые при перетаскивании, содержатся в объекте QMimeData. Это задается функцией setMimeData() следующим образом:

        QDrag *drag = new QDrag(this);
        QMimeData *mimeData = new QMimeData;

        mimeData->setText(commentEdit->toPlainText());
        drag->setMimeData(mimeData);

Обратите внимание, что setMimeData() передает владение объектом QMimeData объекту QDrag. Объект QDrag должен быть создан динамически с родительским объектом QObject, чтобы Qt мог произвести очистку после завершения операции перетаскивания.

Изображение (pixmap) может использоваться для представления данных во время перетаскивания и будет перемещаться вместе с курсором к целевому элементу. Это изображение обычно отображает иконку, представляющую тип MIME передаваемых данных, но может быть установлено любое изображение с помощью setPixmap(). Смещение курсора относительно верхнего левого угла изображения можно задать с помощью функции setHotSpot(). Следующий код позиционирует изображение таким образом, чтобы точка смещения курсора указывала на центр нижнего края:

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

Примечание: В X11 изображение может не успевать за перемещениями мыши, если точка смещения курсора расположена таким образом, что изображение отображается прямо под курсором.

Источник и целевой виджеты можно найти с помощью source() и target(). Эти функции часто используются для определения, начались ли операции перетаскивания и завершились ли в одном и том же виджете, чтобы можно было реализовать специальное поведение.

Класс QDrag занимается только самой операцией перетаскивания. Разработчик должен решить, когда начинается операция перетаскивания и как объект QDrag должен быть создан и использован. Для данного виджета часто необходимо переопределить mousePressEvent() для определения нажатия пользователем кнопки мыши и переопределить mouseMoveEvent() для проверки необходимости объекта QDrag.

См. также Перетаскивание и падение (Drag and Drop), QClipboard, QMimeData, QMacPasteboardMime, Пример Перетаскиваемых Иконок, Пример Перетаскиваемого Текста, Пример Места Приемника и Пример Магнитов Холодильника.

Документация функций-членов

QDrag::QDrag(QObject *dragSource)

Создает новый объект перетаскивания для виджета, указанного параметром dragSource.

QDrag::~QDrag()

Уничтожает объект перетаскивания.

[signal] void QDrag::actionChanged(Qt::DropAction action)

Этот сигнал излучается, когда действие, связанное с перетаскиванием, изменяется.

См. также targetChanged().

[static] void QDrag::cancel()

Отменяет операцию перетаскивания, инициированную Qt.

Примечание: В настоящее время реализовано в Windows и X11.

Эта функция была добавлена в Qt 5.7.

См. также exec().

Qt::DropAction QDrag::defaultAction() const

Возвращает предлагаемое по умолчанию действие падения для этой операции перетаскивания.

См. также exec() и supportedActions().

QPixmap QDrag::dragCursor(Qt::DropAction action) const

Возвращает курсор перетаскивания для action.

Эта функция была добавлена в Qt 5.0.

См. также setDragCursor().

Qt::DropAction QDrag::exec(Qt::DropActions supportedActions = Qt::MoveAction)

Запускает операцию перетаскивания и падения и возвращает значение, указывающее выбранное действие падения при завершении. Действия падения, которые может выбрать пользователь, задаются в supportedActions. Предлагаемое по умолчанию действие будет выбрано из разрешённых действий в следующем порядке: Переместить, Скопировать и Связать.

Примечание: В Linux и macOS операция перетаскивания может занять некоторое время, но эта функция не блокирует цикл событий. Другие события всё ещё доставляются приложению, пока выполняется операция. В Windows цикл событий Qt заблокирован во время выполнения операции.

Эта функция была добавлена в Qt 4.3.

См. также cancel().

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

Запускает операцию перетаскивания и падения и возвращает значение, указывающее выбранное действие падения при завершении. Действия падения, которые может выбрать пользователь, задаются в supportedActions.

defaultDropAction определяет действие, которое будет предложено пользователю при выполнении перетаскивания без использования модификаторов.

Примечание: В Linux и macOS операция перетаскивания и выкладывания может занять некоторое время, но эта функция не блокирует цикл событий. Другие события всё равно доставляются в приложение во время выполнения операции. В Windows цикл событий Qt блокируется во время операции. Однако QDrag::exec() в Windows вызывает процесс processEvents() часто, чтобы сохранить отзывчивость графического интерфейса. Если какие-либо циклы или операции вызываются во время активной операции перетаскивания, это заблокирует операцию перетаскивания.

Данная функция была представлена в Qt 4.3.

QPoint QDrag::hotSpot() const

Возвращает положение горячей точки относительно левого верхнего угла курсора.

См. также setHotSpot().

QMimeData *QDrag::mimeData() const

Возвращает данные MIME, инкапсулированные объектом перетаскивания.

См. также setMimeData().

QPixmap QDrag::pixmap() const

Возвращает пиктограмму, используемую для представления данных в операции перетаскивания и выкладывания.

См. также setPixmap().

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

Устанавливает курсор перетаскивания cursor для action. Это позволяет переопределять стандартные системные курсоры. Для возврата к использованию системного курсора для action передайте в cursor значение nullptr.

action может быть только CopyAction, MoveAction или LinkAction. Все остальные значения DropAction игнорируются.

См. также dragCursor().

void QDrag::setHotSpot(const QPoint &hotspot)

Устанавливает положение горячей точки относительно левого верхнего угла пиктограммы в точке, указанной hotspot.

Примечание: в X11 пиктограмма может не успевать за перемещением мыши, если горячая точка приводит к отображению пиктограммы непосредственно под курсором.

См. также hotSpot().

void QDrag::setMimeData(QMimeData *data)

Устанавливает данные, которые должны быть отправлены заданным данным MIME data. Владение данными передаётся объекту QDrag.

См. также mimeData().

void QDrag::setPixmap(const QPixmap &pixmap)

Устанавливает pixmap как пиктограмму, используемую для представления данных в операции перетаскивания и выкладывания. Вы можете установить пиктограмму только до начала перетаскивания.

См. также pixmap().

QObject *QDrag::source() const

Возвращает источник объекта перетаскивания. Это виджет, из которого началась операция перетаскивания и выкладывания.

Qt::DropActions QDrag::supportedActions() const

Возвращает набор возможных действий выкладывания для данной операции перетаскивания.

См. также exec() и defaultAction().

QObject *QDrag::target() const

Возвращает целевой объект операции перетаскивания и выкладывания. Это виджет, в который был выложен объект перетаскивания.

[signal] void QDrag::targetChanged(QObject *newTarget)

Этот сигнал излучается, когда целевой объект операции перетаскивания и выкладывания изменяется, причём newTarget — новая цель.

См. также target() и actionChanged().