1\section{wxDataObject overview}\label{wxdataobjectoverview} 2 3Classes: \helpref{wxDataObject}{wxdataobject}, 4 \helpref{wxClipboard}{wxclipboard}, 5 \helpref{wxDataFormat}{wxdataformat}, 6 \helpref{wxDropSource}{wxdropsource}, 7 \helpref{wxDropTarget}{wxdroptarget} 8 9See also: \helpref{Drag and drop overview}{wxdndoverview} and \helpref{DnD sample}{samplednd} 10 11This overview discusses data transfer through clipboard or drag and drop. In 12wxWidgets, these two ways to transfer data (either between different 13applications or inside one and the same) are very similar which allows to 14implement both of them using almost the same code - or, in other 15words, if you implement drag and drop support for your application, you get 16clipboard support for free and vice versa. 17 18At the heart of both clipboard and drag and drop operations lies the 19\helpref{wxDataObject}{wxdataobject} class. The objects of this class (or, to 20be precise, classes derived from it) represent the data which is being carried 21by the mouse during drag and drop operation or copied to or pasted from the 22clipboard. wxDataObject is a "smart" piece of data because it knows which 23formats it supports (see GetFormatCount and GetAllFormats) and knows how to 24render itself in any of them (see GetDataHere). It can also receive its value 25from the outside in a format it supports if it implements the SetData method. 26Please see the documentation of this class for more details. 27 28Both clipboard and drag and drop operations have two sides: the source and 29target, the data provider and the data receiver. These which may be in the same 30application and even the same window when, for example, you drag some text from 31one position to another in a word processor. Let us describe what each of them 32should do. 33 34\subsection{The data provider (source) duties}\label{wxdataobjectsource} 35 36The data provider is responsible for creating a 37\helpref{wxDataObject}{wxdataobject} containing the data to be 38transferred. Then it should either pass it to the clipboard using 39\helpref{SetData}{wxclipboardsetdata} function or to 40\helpref{wxDropSource}{wxdropsource} and call 41\helpref{DoDragDrop}{wxdropsourcedodragdrop} function. 42 43The only (but important) difference is that the object for the clipboard 44transfer must always be created on the heap (i.e. using {\tt new}) and it will 45be freed by the clipboard when it is no longer needed (indeed, it is not known 46in advance when, if ever, the data will be pasted from the clipboard). On the 47other hand, the object for drag and drop operation must only exist while 48\helpref{DoDragDrop}{wxdropsourcedodragdrop} executes and may be safely deleted 49afterwards and so can be created either on heap or on stack (i.e. as a local 50variable). 51 52Another small difference is that in the case of clipboard operation, the 53application usually knows in advance whether it copies or cuts (i.e. copies and 54deletes) data - in fact, this usually depends on which menu item the user 55chose. But for drag and drop it can only know it after 56\helpref{DoDragDrop}{wxdropsourcedodragdrop} returns (from its return value). 57 58\subsection{The data receiver (target) duties}\label{wxdataobjecttarget} 59 60To receive (paste in usual terminology) data from the clipboard, you should 61create a \helpref{wxDataObject}{wxdataobject} derived class which supports the 62data formats you need and pass it as argument to 63\helpref{wxClipboard::GetData}{wxclipboardgetdata}. If it returns {\tt false}, 64no data in (any of) the supported format(s) is available. If it returns {\tt 65true}, the data has been successfully transferred to wxDataObject. 66 67For drag and drop case, the \helpref{wxDropTarget::OnData}{wxdroptargetondata} 68virtual function will be called when a data object is dropped, from which the 69data itself may be requested by calling 70\helpref{wxDropTarget::GetData}{wxdroptargetwxdroptarget} method which fills 71the data object. 72 73