dragged and dropped.
There are several predefined data object classes, such as \helpref{wxFileDataObject}{wxfiledataobject},
-\helpref{wxTextDataObject}{wxtextdataobject}, and \helpref{wxBitmapDataObject}{wxbitmapdataobject}.
-
-You may also derive your own data object classes for user-defined types.
-
-TODO: how do user-defined types work?
+\helpref{wxTextDataObject}{wxtextdataobject}, and \helpref{wxBitmapDataObject}{wxbitmapdataobject} which
+can be used without change or can be altered (by deriving a new class from them) in order to deliver
+data and data size on-demand. There is no need to ever use wxDataObject itself or derive directly from it.
+
+You may also derive your own data object classes from \helpref{wxPrivateDataObject}{wxprivatedataobject}
+for user-defined types. The format of user-defined data is given as mime-type string literal,
+such as "application/word" or "image/png". These strings are used as they are under Unix (so
+far only GTK) to identify a format and are translated into their Windows equivalent under
+Win32 (using the OLE IDataObject for data exchange to and from the clipboard and for Drag'n'Drop).
+Note that the format string translation under Windows is not yet finnished.
+
+As mentioned above, data may be placed into the \helpref{wxClipboard}{wxclipboard}
+or a \helpref{wxDropSource}{wxdropsource} instance either directly or on-demand.
+As long as only one format is offerred, putting data directly into the clipboard may
+be sufficient. But imagine that you paste a large piece of text to the clipboard and
+offer it in "text/plain", "text/rtf", "text/html", "application/word" and your own
+format for internal use - here offering data on-demand is required to minimize memory
+consumption. This would generally get implemented using a central object that
+contains clipboard information in the format with the maximum of information. Note
+that neither the GTK data transfer mechanisms for the clipboard and Drag'n'Drop
+nor the OLE data transfer copies any data until another application actually
+requests the data. This is in contrast to the "feel" offered to the user of a
+program who would normally think that the data resides in the clipboard after
+having pressed "Copy" - in reality it is only declared to be available.
+
+Let's assume that you have written an HTML editor and want it to paste contents
+in the formats "text/plain" and "text/html" to the clipboard. For offering
+data on-demand in "text/plain" you would derive your class from \helpref{wxTextDataObject}{wxtextdataobject}
+and for offering data on-demand in "text/html" you would derive your own class from
+\helpref{wxPrivateDataObject}{wxprivatedataobject} and set its ID string
+identifying the format to "text/html" using \helpref{wxPrivateDataObject::SetId}{wxprivatedataobjectsetid}.
+In your two derived classed you'd then have a pointer or reference to the central
+data container and you'd override the methods returning the size of the
+available data and the WriteData() methods in both classes.
\wxheading{Derived from}
\helpref{wxObject}{wxobject}
-\wxheading{Types}
+\wxheading{Include files}
-\index{wxDataFormat}The following symbols are interchangable with the
-Windows equivalents.
-
-\begin{verbatim}
-enum wxDataFormat
-{
- wxDF_TEXT = 1, /* CF_TEXT */
- wxDF_BITMAP = 2, /* CF_BITMAP */
- wxDF_METAFILE = 3, /* CF_METAFILEPICT */
- wxDF_DIB = 8, /* CF_DIB */
- wxDF_OEMTEXT = 7, /* CF_OEMTEXT */
- wxDF_FILENAME = 15, /* CF_HDROP */
- wxDF_PRIVATE = 20
-};
-\end{verbatim}
+<wx/dataobj.h>
\wxheading{See also}
\helpref{wxFileDataObject}{wxfiledataobject},
\helpref{wxTextDataObject}{wxtextdataobject},
\helpref{wxBitmapDataObject}{wxbitmapdataobject},
+\helpref{wxPrivateDataObject}{wxprivatedataobject},
\helpref{Drag and drop overview}{wxdndoverview}, \helpref{wxDropTarget}{wxdroptarget},
\helpref{wxDropSource}{wxdropsource},
\helpref{wxTextDropTarget}{wxtextdroptarget}, \helpref{wxFileDropTarget}{wxfiledroptarget}
Destructor.
-\membersection{wxDataObject::GetFormat}\label{wxdataobjectgetformat}
+\membersection{wxDataObject::WriteData}\label{wxdataobjectwritedata}
+
+\constfunc{virtual void}{WriteData}{\param{void}{*dest} }
+
+Write the data owned by this class to {\it dest}. This method is a pure
+virtual function and must be overridden.
+
+\membersection{wxDataObject::GetSize}\label{wxdataobjectgetdatasize}
+
+\constfunc{virtual size\_t}{GetSize}{\void}
-\constfunc{virtual wxDataFormat}{GetFormat}{\void}
+Returns the data size. This method is a pure
+virtual function and must be overridden.
-Returns the format of the object. See \helpref{Types}{wxdataobject}.
projects / wxWidgets.git / blobdiff