Data Objects

The wxDataObject class is at the heart of both clipboard and drag and drop. Instances of classes derived from wxDataObject represent the data that is being dragged by the mouse during a drag and drop operation or copied to or pasted from the clipboard. wxDataObject is a "smart" piece of data because it knows which formats it supports (via GetFormatCount and GetAllFormats) and knows how to render itself in any of them (via GetdataHere). It can also receive its value from outside the application in a format it supports if it implements the SetData method. We'll see how to do that later in the chapter.

Standard data formats such as wxDF_TEXT are identified by integers, and custom data formats are identified by a text string. The wxDataFormat class represents both of these kinds of identifiers by virtue of a constructor for each. Table 11-1 lists the standard data formats.

Table 11-1. Standard Data Formats

wxDF_INVALID	An invalid format, used as default argument for functions taking a wxDataFormat argument.
wxDF_TEXT	Text format. Standard data object: wxTexTDataObject.
wxDF_BITMAP	Bitmap format. Standard data object: wxBitmapDataObject.
wxDF_METAFILE	Metafile (Windows only). Standard data object: wxMetafileData Object.
wxDF_FILENAME	A list of file names. Standard data object: wxFileDataObject.

You can also create a custom data format by passing an arbitrary string to the wxDataFormat constructor. The format will be registered the first time it is referenced.

Both clipboard and drag and drop deal with a source (data provider) and a target (data receiver). These may be in the same application and even the same window when, for example, you drag some text from one position to another in a word processor. Let's describe what each should do.

Data Source Duties

The data source is responsible for creating a wxDataObject containing the data to be transferred. Then the data source should either pass the wxDataObject to the clipboard using the SetData function or pass it to a wxDropSource object when dragging starts and call the DoDragDrop function.

The main difference from a clipboard operation is that the object for clipboard transfer must always be created on the heap using new and will be freed by the clipboard when it is no longer needed. Indeed, it is not known in advance when, if ever, the data will be pasted from the clipboard. On the other hand, the object for the drag and drop operation must exist only while DoDragDrop executes and may be safely deleted afterwards, so it can be created either on the heap or on the stack (that is, as a local variable).

Another small difference is that in the case of a clipboard operation, the application usually knows in advance whether it copies or cuts data. In a clipboard cut, the data is copied and then removed from the object being edited. This usually depends on which menu item the user chose. But for drag and drop, the application can only know this information after DoDragDrop returns.

Data Target Duties

To receive data from the clipboard (that is, a paste operation), you should create a wxDataObject derived class that supports the data formats you need and pass it to wxClipboard::GetData. If it returns false, no data in any of the supported formats is available. If it returns true, the data has been successfully transferred to wxDataObject.

For the drag and drop case, the wxDropTarget::OnData virtual function will be called when a data object is dropped, from which the data itself may be requested by calling the wxDropTarget::GetData method.