X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/dface61ccba162c922b25d18aca2ebc4e6f03312..96db102a93ed103a1c757c4445dd71789c2d0054:/docs/latex/wx/dataobj.tex

diff --git a/docs/latex/wx/dataobj.tex b/docs/latex/wx/dataobj.tex
index 4efc76278e..bec42f8c47 100644
--- a/docs/latex/wx/dataobj.tex
+++ b/docs/latex/wx/dataobj.tex
@@ -4,39 +4,55 @@ A wxDataObject represents data that can be copied to or from the clipboard, or
 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}
@@ -55,9 +71,18 @@ Constructor.
 
 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}.