Класс QMimeData

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

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

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

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

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

QMimeData используется для описания информации, которая может храниться в буфере обмена (clipboard), и передаваться с помощью механизма перетаскивания (drag and drop). Объекты 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() в обработчике события отпускания. Например:

   void MyWidget::dropEvent(QDropEvent *event)
   {
       const MyMimeData *myData =
               qobject_cast<const MyMimeData *>(event->mimeData());
       if (myData) {
           // access myData's data directly (not through QMimeData's API)
       }
   }

Платформенно-зависимые типы 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 не был вызван ранее, чтобы сделать возможным их выброс в любой lineedit и текстовый редактор.

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