com.trolltech.qt.core
Class QMimeData

java.lang.Object
  extended by com.trolltech.qt.internal.QSignalEmitterInternal
      extended by com.trolltech.qt.QSignalEmitter
          extended by com.trolltech.qt.QtJambiObject
              extended by com.trolltech.qt.core.QObject
                  extended by com.trolltech.qt.core.QMimeData
All Implemented Interfaces:
QtJambiInterface

public class QMimeData
extends QObject

The QMimeData class provides a container for data that records information about its MIME type. QMimeData is used to describe information that can be stored in the clipboard, and transferred via the drag 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 using new and supplied to QDrag or QClipboard objects. This is to enable Qt to manage the memory that they use.

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

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

Tester
Getter
Setter
MIME Types
hasText() text() setText() text/plain
hasHtml() html() setHtml() text/html
hasUrls() urls() setUrls() text/uri-list
hasImage() imageData() setImageData() image/ *
hasColor() colorData() setColorData() application/x-color
For example, if your write a widget that accepts URL drags, you would end up writing code like this:

The following code example is written in c++.
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 a QMimeData object:
  1. Custom data can be stored directly in a QMimeData object as a QByteArray using setData(). For example:

    The following code example is written in c++.
    QByteArray csvData = ...;
    
    QMimeData *mimeData = new QMimeData;
    mimeData->setData("text/csv", csvData);
    
  2. We can subclass QMimeData and reimplement hasFormat(), formats(), and retrieveData().
  3. If the drag and drop operation occurs withing a single application, we can subclass QMimeData and add extra data in it, and use a qobject_cast() in the receiver's drop event handler. For example:

    The following code example is written in c++.
    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 the x-qt-windows-mime subtype to indicate that they represent data in non-standard formats. The formats will take the following form:

The following code example is written in c++.
application/x-qt-windows-mime;value="<custom type>"
The following are examples of custom MIME types:

The following code example is written in c++.
application/x-qt-windows-mime;value="FileGroupDescriptor"
application/x-qt-windows-mime;value="FileContents"
The value 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 provides QWindowsMime to map clipboard formats to open-standard MIME formats. Similarly, the QMacPasteboardMime maps MIME to Mac flavors.

See also:
QClipboard, QDragEnterEvent, QDragMoveEvent, QDropEvent, QDrag, QWindowsMime, QMacPasteboardMime, and Drag and Drop.


Nested Class Summary
 
Nested classes/interfaces inherited from class com.trolltech.qt.QSignalEmitter
QSignalEmitter.AbstractSignal, QSignalEmitter.PrivateSignal0, QSignalEmitter.PrivateSignal1, QSignalEmitter.PrivateSignal2, QSignalEmitter.PrivateSignal3, QSignalEmitter.PrivateSignal4, QSignalEmitter.PrivateSignal5, QSignalEmitter.PrivateSignal6, QSignalEmitter.PrivateSignal7, QSignalEmitter.PrivateSignal8, QSignalEmitter.PrivateSignal9, QSignalEmitter.Signal0, QSignalEmitter.Signal1, QSignalEmitter.Signal2, QSignalEmitter.Signal3, QSignalEmitter.Signal4, QSignalEmitter.Signal5, QSignalEmitter.Signal6, QSignalEmitter.Signal7, QSignalEmitter.Signal8, QSignalEmitter.Signal9
 
Nested classes/interfaces inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
com.trolltech.qt.internal.QSignalEmitterInternal.AbstractSignalInternal
 
Field Summary
 
Fields inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
currentSender
 
Constructor Summary
QMimeData()
          Constructs a new MIME data object with no data in it.
 
Method Summary
 void clear()
          Removes all the MIME type and data entries in the object.
 java.lang.Object colorData()
          Returns a color if the data stored in the object represents a color (MIME type application/x-color); otherwise returns a null variant.
 QByteArray data(java.lang.String mimetype)
          Returns the data stored in the object in the format described by the MIME type specified by mimeType.
 java.util.List formats()
          Returns a list of formats supported by the object.
 boolean hasColor()
          Returns true if the object can return a color (MIME type application/x-color); otherwise returns false.
 boolean hasFormat(java.lang.String mimetype)
          Returns true if the object can return data for the MIME type specified by mimeType; otherwise returns false.
 boolean hasHtml()
          Returns true if the object can return HTML (MIME type text/html); otherwise returns false.
 boolean hasImage()
          Returns true if the object can return an image; otherwise returns false.
 boolean hasText()
          Returns true if the object can return plain text (MIME type text/plain); otherwise returns false.
 boolean hasUrls()
          Returns true if the object can return a list of urls; otherwise returns false.
 java.lang.String html()
          Returns a string if the data stored in the object is HTML (MIME type text/html); otherwise returns an empty string.
 java.lang.Object imageData()
          Returns a QVariant storing a QImage if the object can return an image; otherwise returns a null variant.
 void removeFormat(java.lang.String mimetype)
          Removes the data entry for mimeType in the object.
protected  java.lang.Object retrieveData(java.lang.String mimetype, int preferredType)
          Returns a variant with the given type containing data for the MIME type specified by mimeType.
 void setColorData(java.lang.Object color)
          Sets the color data in the object to the given color.
 void setData(java.lang.String mimetype, QByteArray data)
          Sets the data associated with the MIME type given by mimeType to the specified data.
 void setHtml(java.lang.String html)
          Sets html as the HTML (MIME type text/html) used to represent the data.
 void setImageData(java.lang.Object image)
          Sets the data in the object to the given image.
 void setText(java.lang.String text)
          Sets text as the plain text (MIME type text/plain) used to represent the data.
 void setUrls(java.util.List urls)
          Sets the URLs stored in the MIME data object to those specified by urls.
 java.lang.String text()
          Returns a plain text (MIME type text/plain) representation of the data.
 java.util.List urls()
          Returns a list of URLs contained within the MIME data object.
 
Methods inherited from class com.trolltech.qt.core.QObject
childEvent, children, connectSlotsByName, customEvent, disposeLater, dumpObjectInfo, dumpObjectTree, dynamicPropertyNames, event, eventFilter, findChild, findChild, findChild, findChildren, findChildren, findChildren, findChildren, indexOfProperty, installEventFilter, isWidgetType, killTimer, moveToThread, objectName, parent, properties, property, removeEventFilter, setObjectName, setParent, setProperty, startTimer, timerEvent, toString, userProperty
 
Methods inherited from class com.trolltech.qt.QtJambiObject
dispose, disposed, equals, finalize, reassignNativeResources, tr, tr, tr
 
Methods inherited from class com.trolltech.qt.QSignalEmitter
blockSignals, disconnect, disconnect, signalsBlocked, signalSender, thread
 
Methods inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
__qt_signalInitialization
 
Methods inherited from class java.lang.Object
clone, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface com.trolltech.qt.QtJambiInterface
disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership
 

Constructor Detail

QMimeData

public QMimeData()
Constructs a new MIME data object with no data in it.

Method Detail

clear

public final void clear()
Removes all the MIME type and data entries in the object.


colorData

public final java.lang.Object colorData()
Returns a color if the data stored in the object represents a color (MIME type application/x-color); otherwise returns a null variant.

A QVariant is used because QMimeData belongs to the QtCore library, whereas QColor belongs to QtGui. To convert the QVariant to a QColor, simply use qvariant_cast(). For example:

The following code example is written in c++.

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

See also:
hasColor(), setColorData(), and data().


data

public final QByteArray data(java.lang.String mimetype)
Returns the data stored in the object in the format described by the MIME type specified by mimeType.

See also:
setData().


hasColor

public final boolean hasColor()
Returns true if the object can return a color (MIME type application/x-color); otherwise returns false.

See also:
setColorData(), colorData(), and hasFormat().


hasHtml

public final boolean hasHtml()
Returns true if the object can return HTML (MIME type text/html); otherwise returns false.

See also:
setHtml(), html(), and hasFormat().


hasImage

public final boolean hasImage()
Returns true if the object can return an image; otherwise returns false.

See also:
setImageData(), imageData(), and hasFormat().


hasText

public final boolean hasText()
Returns true if the object can return plain text (MIME type text/plain); otherwise returns false.

See also:
setText(), text(), hasHtml(), and hasFormat().


hasUrls

public final boolean hasUrls()
Returns true if the object can return a list of urls; otherwise returns false.

URLs correspond to the MIME type text/uri-list.

See also:
setUrls(), urls(), and hasFormat().


html

public final java.lang.String html()
Returns a string if the data stored in the object is HTML (MIME type text/html); otherwise returns an empty string.

See also:
setHtml(), hasHtml(), and setData().


imageData

public final java.lang.Object imageData()
Returns a QVariant storing a QImage if the object can return an image; otherwise returns a null variant.

A QVariant is used because QMimeData belongs to the QtCore library, whereas QImage belongs to QtGui. To convert the QVariant to a QImage, simply use qvariant_cast(). For example:

The following code example is written in c++.

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

See also:
setImageData(), and hasImage().


removeFormat

public final void removeFormat(java.lang.String mimetype)
Removes the data entry for mimeType in the object.


setColorData

public final void setColorData(java.lang.Object color)
Sets the color data in the object to the given color.

Colors correspond to the MIME type application/x-color.

See also:
colorData(), hasColor(), and setData().


setData

public final void setData(java.lang.String mimetype,
                          QByteArray data)
Sets the data associated with the MIME type given by mimeType to the specified data.

For the most common types of data, you can call the higher-level functions setText(), setHtml(), setUrls(), setImageData(), and setColorData() 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 Qt meta type, using the Q_DECLARE_METATYPE() macro, and implement stream operators for it. The stream operators must then be registered with the qRegisterMetaTypeStreamOperators() function.

See also:
data(), hasFormat(), QMetaType, and qRegisterMetaTypeStreamOperators().


setHtml

public final void setHtml(java.lang.String html)
Sets html as the HTML (MIME type text/html) used to represent the data.

See also:
html(), hasHtml(), setText(), and setData().


setImageData

public final void setImageData(java.lang.Object image)
Sets the data in the object to the given image.

A QVariant is used because QMimeData belongs to the QtCore library, whereas QImage belongs to QtGui. The conversion from QImage to QVariant is implicit. For example:

The following code example is written in c++.

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

See also:
imageData(), hasImage(), and setData().


setText

public final void setText(java.lang.String text)
Sets text as the plain text (MIME type text/plain) used to represent the data.

See also:
text(), hasText(), setHtml(), and setData().


setUrls

public final void setUrls(java.util.List urls)
Sets the URLs stored in the MIME data object to those specified by urls.

URLs correspond to the MIME type text/uri-list.

See also:
urls(), hasUrls(), and setData().


text

public final java.lang.String text()
Returns a plain text (MIME type text/plain) representation of the data.

See also:
setText(), hasText(), html(), and data().


urls

public final java.util.List urls()
Returns a list of URLs contained within the MIME data object.

URLs correspond to the MIME type text/uri-list.

See also:
setUrls(), hasUrls(), and data().


formats

public java.util.List formats()
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 functions hasText(), hasHtml(), hasUrls(), hasImage(), and hasColor() instead.

See also:
hasFormat(), setData(), and data().


hasFormat

public boolean hasFormat(java.lang.String mimetype)
Returns true if the object can return data for the MIME type specified by mimeType; otherwise returns false.

For the most common types of data, you can call the higher-level functions hasText(), hasHtml(), hasUrls(), hasImage(), and hasColor() instead.

See also:
formats(), setData(), and data().


retrieveData

protected java.lang.Object retrieveData(java.lang.String mimetype,
                                        int preferredType)
Returns a variant with the given type containing data for the MIME type specified by mimeType. 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 general data() getter and by the convenience getters (text(), html(), urls(), imageData(), and colorData()). You can reimplement it if you want to store your data using a custom data structure (instead of a QByteArray, which is what setData() provides). You would then also need to reimplement hasFormat() and formats().

See also:
data().