Класс QMimeData

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

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

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

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

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

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

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

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

   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, форматы() также вернут пользовательские форматы, доступные в данных 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 без данных.

[virtual] QMimeData::~QMimeData()

Уничтожает объект данных MIME.

void QMimeData::очистить()

Удаляет все записи типов и данных 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());
    ...
}

См. также имеетЦвет(), установитьЦветДанные() и data().

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

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

См. также установитьДанные().

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

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