Класс QMimeData

Класс QMimeData предоставляет контейнер для данных, которые записывают информацию о типе MIME. Подробнее...

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

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

Защищенные функции

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

QMimeData используется для описания информации, которая может храниться в буфере обмена и передаваться с помощью механизма перетаскивания. Объекты QMimeData связывают хранящиеся в них данные с соответствующими типами MIME, чтобы гарантировать безопасный обмен информацией между приложениями и копирование в пределах одного приложения.

Объекты QMimeData обычно создаются с помощью new и передаются в объекты QDrag или QClipboard. Это позволяет Qt управлять используемой ими памятью.

Один объект QMimeData может хранить одни и те же данные в нескольких форматах одновременно. Функция formats() возвращает список доступных форматов в порядке предпочтения. Функция data() возвращает исходные данные, связанные с типом MIME, а функция setData() позволяет задать данные для типа MIME.

Для наиболее распространённых типов MIME QMimeData предоставляет удобные функции для доступа к данным:

Например, если вы создаёте виджет, принимающий перетаскивание URL, ваш код будет выглядеть примерно так:

void MyWidget::dragEnterEvent(QDragEnterEvent *event)
{
    if (event->mimeData()->hasUrls())
        event->acceptProposedAction();
}

void MyWidget::dropEvent(QDropEvent *event)
{
    if (event->mimeData()->hasUrls()) {
        foreach (QUrl url, event->mimeData()->urls()) {
            ...
        }
    }
}

Существует три подхода к хранению пользовательских данных в объекте QMimeData:

1. Пользовательские данные могут храниться непосредственно в объекте QMimeData как QByteArray с помощью setData(). Например:

   QByteArray csvData = ...;
   
   QMimeData *mimeData = new QMimeData;
   mimeData->setData("text/csv", csvData);

2. Можно создать подкласс QMimeData и переопределить hasFormat(), formats() и retrieveData().
3. Если операция перетаскивания происходит внутри одного приложения, можно создать подкласс QMimeData, добавить дополнительные данные и использовать qobject_cast() в обработчике события отпускания.

Типы MIME, специфичные для платформы

В Windows функция formats() также вернёт пользовательские форматы, доступные в данных MIME, используя подтип x-qt-windows-mime для указания, что они представляют данные в нестандартных форматах. Форматы будут иметь следующий вид:

application/x-qt-windows-mime;value="<custom type>"

Вот примеры пользовательских типов MIME:

application/x-qt-windows-mime;value="FileGroupDescriptor"
application/x-qt-windows-mime;value="FileContents"

Описание каждого формата value описывает способ кодирования данных.

В некоторых случаях (например, при перетаскивании нескольких вложений почтовых сообщений) доступно несколько значений данных. К ним можно получить доступ, добавив значение index.

application/x-qt-windows-mime;value="FileContents";index=0
application/x-qt-windows-mime;value="FileContents";index=1

В Windows формат MIME не всегда напрямую отображается в форматах буфера обмена. Qt предоставляет QWinMime для сопоставления форматов буфера обмена с открытыми стандартными форматами MIME. Аналогично, QMacPasteboardMime сопоставляет MIME с Mac-форматами.

См. также QClipboard, QDragEnterEvent, QDragMoveEvent, QDropEvent, QDrag и Перетаскивание.

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

QMimeData::QMimeData()

Создаёт новый объект данных MIME без данных.

[virtual] QMimeData::~QMimeData()

Удаляет объект данных MIME.

void QMimeData::clear()

Удаляет все записи типов MIME и данных в объекте.

QVariant QMimeData::colorData() const

Возвращает цвет, если хранящиеся в объекте данные представляют цвет (тип MIME application/x-color); в противном случае возвращает нулевую переменную.

Используется QVariant, потому что QMimeData принадлежит модулю Qt Core, а QColor — модулю Qt GUI. Для преобразования QVariant в QColor используйте qvariant_cast(). Например:

if (event->mimeData()->hasColor()) {
    QColor color = qvariant_cast<QColor>(event->mimeData()->colorData());
    ...
}

См. также hasColor(), setColorData() и data().

QByteArray QMimeData::data(const QString &mimeType) const

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

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

[virtual] QStringList QMimeData::formats() const

Возвращает список поддерживаемых объектом форматов. Это список MIME-типов, для которых объект может вернуть соответствующие данные. Форматы в списке упорядочены по приоритету.

Для самых распространённых типов данных вы можете вызвать функции более высокого уровня hasText(), hasHtml(), hasUrls(), hasImage() и hasColor() вместо этого.

См. также hasFormat(), setData() и data().

bool QMimeData::hasColor() const

Возвращает true, если объект может вернуть цвет (MIME-тип application/x-color); в противном случае возвращает false.

См. также setColorData(), colorData() и hasFormat().

[virtual] bool QMimeData::hasFormat(const QString &mimeType) const

Возвращает true, если объект может вернуть данные для указанного MIME-типа mimeType; в противном случае возвращает false.

Для самых распространённых типов данных вы можете вызвать функции более высокого уровня hasText(), hasHtml(), hasUrls(), hasImage() и hasColor() вместо этого.

См. также formats(), setData() и data().

bool QMimeData::hasHtml() const

Возвращает true, если объект может вернуть HTML (MIME-тип text/html); в противном случае возвращает false.

См. также setHtml(), html() и hasFormat().

bool QMimeData::hasImage() const

Возвращает true, если объект может вернуть изображение; в противном случае возвращает false.

См. также setImageData(), imageData() и hasFormat().

bool QMimeData::hasText() const

Возвращает true, если объект может вернуть обычный текст (MIME-тип text/plain); в противном случае возвращает false.

См. также setText(), text(), hasHtml() и hasFormat().

bool QMimeData::hasUrls() const

Возвращает true, если объект может вернуть список URL-адресов; в противном случае возвращает false.

URL-адреса соответствуют MIME-типу text/uri-list.

См. также setUrls(), urls() и hasFormat().

QString QMimeData::html() const

Возвращает строку, если данные, хранящиеся в объекте, представляют собой HTML (MIME-тип text/html); в противном случае возвращает пустую строку.

См. также setHtml(), hasHtml() и setData().

QVariant QMimeData::imageData() const

Возвращает QVariant, хранящий QImage, если объект может вернуть изображение; в противном случае возвращает нулевой вариант.

Используется QVariant, потому что QMimeData принадлежит модулю Qt Core, а QImage — модулю Qt GUI. Для преобразования QVariant в QImage просто используйте qvariant_cast(). Например:

if (event->mimeData()->hasImage()) {
    QImage image = qvariant_cast<QImage>(event->mimeData()->imageData());
    ...
}

См. также setImageData() и hasImage().

void QMimeData::removeFormat(const QString &mimeType)

Удаляет запись данных для mimeType в объекте.

[virtual protected] QVariant QMimeData::retrieveData(const QString &mimeType, QMetaType type) const

Возвращает вариант с заданным type, содержащий данные для MIME-типа, указанного параметром mimeType. Если объект не поддерживает указанный MIME-тип или тип варианта, вместо этого возвращается нулевой вариант.

Эта функция вызывается общим методом data() и удобными методами-получателями (text(), html(), urls(), imageData() и colorData()). Вы можете переопределить его, если хотите хранить свои данные с помощью пользовательской структуры данных (вместо QByteArray, что предоставляет setData()). В этом случае вам также потребуется переопределить hasFormat() и formats().

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

void QMimeData::setColorData(const QVariant &color)

Устанавливает данные цвета в объекте на заданный цвет color.

Цвета соответствуют MIME-типу application/x-color.

См. также colorData(), hasColor() и setData().

void QMimeData::setData(const QString &mimeType, const QByteArray &data)

Устанавливает данные, связанные с MIME-типом, заданным параметром mimeType, на указанные data.

Для самых распространённых типов данных вы можете вызвать функции более высокого уровня setText(), setHtml(), setUrls(), setImageData() и setColorData() вместо этого.

Обратите внимание, что если вы хотите использовать пользовательский тип данных в операции перетаскивания в представлении элементов, вы должны зарегистрировать его как Qt метатип с помощью макроса Q_DECLARE_METATYPE() и реализовать операторы потоков для него.

См. также data(), hasFormat(), QMetaType и Q_DECLARE_METATYPE().

void QMimeData::setHtml(const QString &html)

Устанавливает html в качестве HTML (MIME-тип text/html) для представления данных.

См. также html(), hasHtml(), setText() и setData().

void QMimeData::setImageData(const QVariant &image)

Устанавливает данные в объекте на заданный image.

Используется QVariant, потому что QMimeData принадлежит модулю Qt Core, а QImage — модулю Qt GUI. Преобразование из QImage в QVariant неявное. Например:

mimeData->setImageData(QImage("beautifulfjord.png"));

См. также imageData(), hasImage() и setData().

void QMimeData::setText(const QString &text)

Устанавливает text в качестве обычного текста (MIME-тип text/plain) для представления данных.

См. также text(), hasText(), setHtml() и setData().

void QMimeData::setUrls(const QList<QUrl> &urls)

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

URL-адреса соответствуют MIME-типу text/uri-list.

Начиная с Qt 5.0, setUrls также экспортирует URL-адреса как обычный текст, если перед этим не был вызван setText, чтобы можно было переместить их в любое поле ввода и редактор текста.

См. также urls(), hasUrls() и setData().

QString QMimeData::text() const

Возвращает представление данных в виде обычного текста (MIME-тип text/plain) .

См. также setText(), hasText(), html() и data().

QList<QUrl> QMimeData::urls() const

Возвращает список URL-адресов, содержащихся в объекте MIME-данных.

URL-адреса соответствуют MIME-типу text/uri-list.

См. также setUrls(), hasUrls() и data().