Contents

• Public Functions
• Protected Functions
• Detailed Description
• Platform-Specific MIME Types

Detailed Description

TheQMimeData class provides a container for data that records information about its MIME type.

QMimeData is used to describe information that can be stored in theclipboard, and transferred via thedrag and drop mechanism.QMimeData objects associate the data that they hold with the corresponding MIME types to ensure that information can be safely transferred between applications, and copied around within the same application.

QMimeData objects are usually created usingnew and supplied toQDrag orQClipboard objects. This is to enable Qt to manage the memory that they use.

A singleQMimeData object can store the same data using several different formats at the same time. Theformats() function returns a list of the available formats in order of preference. Thedata() function returns the raw data associated with a MIME type, andsetData() allows you to set the data for a MIME type.

For the most common MIME types,QMimeData provides convenience functions to access the data:

For example, if your write a widget that accepts URL drags, you would end up writing code like this:

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

There are three approaches for storing custom data in aQMimeData object:

1. Custom data can be stored directly in aQMimeData object as aQByteArray usingsetData(). For example:

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

2. We can subclassQMimeData and reimplementhasFormat(),formats(), andretrieveData().
3. If the drag and drop operation occurs within a single application, we can subclassQMimeData and add extra data in it, and use aqobject_cast() in the receiver's drop event handler. For example:

   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)    }}

Platform-Specific MIME Types

On Windows,formats() will also return custom formats available in the MIME data, using thex-qt-windows-mime subtype to indicate that they represent data in non-standard formats. The formats will take the following form:

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

The following are examples of custom MIME types:

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

Thevalue declaration of each format describes the way in which the data is encoded.

On Windows, the MIME format does not always map directly to the clipboard formats. Qt providesQWindowsMime to map clipboard formats to open-standard MIME formats. Similarly, theQMacPasteboardMime maps MIME to Mac flavors.

Member Function Documentation

QMimeData::QMimeData()

Constructs a new MIME data object with no data in it.

QMimeData::~QMimeData()

Destroys the MIME data object.

void QMimeData::clear()

Removes all the MIME type and data entries in the object.

QVariant QMimeData::colorData() const

Returns a color if the data stored in the object represents a color (MIME typeapplication/x-color); otherwise returns a null variant.

AQVariant is used becauseQMimeData belongs to theQtCore library, whereasQColor belongs toQtGui. To convert theQVariant to aQColor, simply useqvariant_cast(). For example:

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

See alsohasColor(),setColorData(), anddata().

QByteArray QMimeData::data(constQString & mimeType) const

Returns the data stored in the object in the format described by the MIME type specified bymimeType.

See alsosetData().

[virtual]QStringList QMimeData::formats() const

Returns a list of formats supported by the object. This is a list of MIME types for which the object can return suitable data. The formats in the list are in a priority order.

For the most common types of data, you can call the higher-level functionshasText(),hasHtml(),hasUrls(),hasImage(), andhasColor() instead.

See alsohasFormat(),setData(), anddata().

bool QMimeData::hasColor() const

Returns true if the object can return a color (MIME typeapplication/x-color); otherwise returns false.

See alsosetColorData(),colorData(), andhasFormat().

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

Returns true if the object can return data for the MIME type specified bymimeType; otherwise returns false.

For the most common types of data, you can call the higher-level functionshasText(),hasHtml(),hasUrls(),hasImage(), andhasColor() instead.

See alsoformats(),setData(), anddata().

bool QMimeData::hasHtml() const

Returns true if the object can return HTML (MIME typetext/html); otherwise returns false.

See alsosetHtml(),html(), andhasFormat().

bool QMimeData::hasImage() const

Returns true if the object can return an image; otherwise returns false.

See alsosetImageData(),imageData(), andhasFormat().

bool QMimeData::hasText() const

Returns true if the object can return plain text (MIME typetext/plain); otherwise returns false.

See alsosetText(),text(),hasHtml(), andhasFormat().

bool QMimeData::hasUrls() const

Returns true if the object can return a list of urls; otherwise returns false.

URLs correspond to the MIME typetext/uri-list.

See alsosetUrls(),urls(), andhasFormat().

QString QMimeData::html() const

Returns a string if the data stored in the object is HTML (MIME typetext/html); otherwise returns an empty string.

See alsosetHtml(),hasHtml(), andsetData().

QVariant QMimeData::imageData() const

Returns aQVariant storing aQImage if the object can return an image; otherwise returns a null variant.

AQVariant is used becauseQMimeData belongs to theQtCore library, whereasQImage belongs toQtGui. To convert theQVariant to aQImage, simply useqvariant_cast(). For example:

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

See alsosetImageData() andhasImage().

void QMimeData::removeFormat(constQString & mimeType)

Removes the data entry formimeType in the object.

This function was introduced in Qt 4.4.

[virtual protected]QVariant QMimeData::retrieveData(constQString & mimeType,QVariant::Type type) const

Returns a variant with the giventype containing data for the MIME type specified bymimeType. If the object does not support the MIME type or variant type given, a null variant is returned instead.

This function is called by the generaldata() getter and by the convenience getters (text(),html(),urls(),imageData(), andcolorData()). You can reimplement it if you want to store your data using a custom data structure (instead of aQByteArray, which is whatsetData() provides). You would then also need to reimplementhasFormat() andformats().

See alsodata().

void QMimeData::setColorData(constQVariant & color)

Sets the color data in the object to the givencolor.

Colors correspond to the MIME typeapplication/x-color.

See alsocolorData(),hasColor(), andsetData().

void QMimeData::setData(constQString & mimeType, constQByteArray & data)

Sets the data associated with the MIME type given bymimeType to the specifieddata.

For the most common types of data, you can call the higher-level functionssetText(),setHtml(),setUrls(),setImageData(), andsetColorData() instead.

Note that if you want to use a custom data type in an item view drag and drop operation, you must register it as a Qtmeta type, using theQ_DECLARE_METATYPE() macro, and implement stream operators for it. The stream operators must then be registered with theqRegisterMetaTypeStreamOperators() function.

See alsodata(),hasFormat(),QMetaType, andqRegisterMetaTypeStreamOperators().

void QMimeData::setHtml(constQString & html)

Setshtml as the HTML (MIME typetext/html) used to represent the data.

See alsohtml(),hasHtml(),setText(), andsetData().

void QMimeData::setImageData(constQVariant & image)

Sets the data in the object to the givenimage.

AQVariant is used becauseQMimeData belongs to theQtCore library, whereasQImage belongs toQtGui. The conversion fromQImage toQVariant is implicit. For example:

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

See alsoimageData(),hasImage(), andsetData().

void QMimeData::setText(constQString & text)

Setstext as the plain text (MIME typetext/plain) used to represent the data.

See alsotext(),hasText(),setHtml(), andsetData().

void QMimeData::setUrls(constQList<QUrl> & urls)

Sets the URLs stored in the MIME data object to those specified byurls.

URLs correspond to the MIME typetext/uri-list.

See alsourls(),hasUrls(), andsetData().

QString QMimeData::text() const

Returns a plain text (MIME typetext/plain) representation of the data.

See alsosetText(),hasText(),html(), anddata().

QList<QUrl> QMimeData::urls() const

Returns a list of URLs contained within the MIME data object.

URLs correspond to the MIME typetext/uri-list.

See alsosetUrls(),hasUrls(), anddata().