Класс QMimeData

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

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

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

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

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

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

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

• 1 свойство унаследовано от QObject
• 1 открытый слот унаследован от QObject
• 2 сигнала унаследованы от QObject
• 11 статических открытых членов унаследовано от QObject

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

Класс 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, QMacPasteboardMime и Перетаскивание.

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

QMimeData::QMimeData()

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

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 в объекте.

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

[virtual protected] QVariant QMimeData::retrieveData(const QString &mimeType, QVariant::Type 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, и реализовать операторы потокового ввода/вывода для него. Затем операторы потокового ввода/вывода должны быть зарегистрированы с помощью функции qRegisterMetaTypeStreamOperators().

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

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().