Класс QDrag

Класс QDrag предоставляет поддержку передачи данных методом перетаскивания и опускания, основанной на MIME. Подробнее...

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

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

Сигналы

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

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

Перетаскивание и опускание — интуитивный способ для пользователей копировать или перемещать данные в приложении, и используется во многих настольных средах как механизм копирования данных между приложениями. Поддержка перетаскивания и опускания в 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 может очистить после завершения операции перетаскивания и опускания.

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

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

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

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

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

См. также Перетаскивание и опускание, QClipboard, QMimeData, Пример перетаскиваемых значков, Пример перетаскиваемого текста, Пример сайта опускания и Пример магнитов холодильника.

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

QDrag::QDrag(QObject *dragSource)

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

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

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

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

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

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

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

[virtual] QDrag::~QDrag()

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

[static, since 5.7] void QDrag::cancel()

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

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

Функция была введена в Qt 5.7.

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

Qt::DropAction QDrag::defaultAction() const

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

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

[since 5.0] QPixmap QDrag::dragCursor(Qt::DropAction action) const

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

Функция была введена в Qt 5.0.

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

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

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

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

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

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

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

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

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

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, передайте пустое растровое изображение QPixmap в качестве cursor.

Примечание: установка курсора перетаскивания для IgnoreAction может не работать на всех платформах. Тестировалось на X11 и macOS. Windows не поддерживает эту функцию.

См. также 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

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