wxDataObject documented

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@1520 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/dataobj.tex

@@ -4,39 +4,51 @@ 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}.
+\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 for user-defined types.
+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.
 
-TODO: how do user-defined types work?
+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}
-
-\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}
-
 \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 +67,18 @@ Constructor.
 
 Destructor.
 
-\membersection{wxDataObject::GetFormat}\label{wxdataobjectgetformat}
+\membersection{wxDataObject::WriteData}\label{wxdataobjectwritedata}
 
-\constfunc{virtual wxDataFormat}{GetFormat}{\void}
+\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}
+
+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}.
 

docs/latex/wx/minifram.tex

@@ -32,12 +32,14 @@ wxCAPTION.}
 for Windows, it is implicit in {\bf wxTHICK\_FRAME}).}
 \end{twocollist}
 
-See also \helpref{window styles overview}{windowstyles}.
+See also \helpref{window styles overview}{windowstyles}. Note that all the window styles
+above are ignored under GTK and the mini frame cannot be resized by the user.
 
 \wxheading{Remarks}
 
-This class has miniframe functionality under Windows and GTK+. On other platforms,
+This class has miniframe functionality under Windows and GTK, i.e. the presence
-it behaves like a normal frame.
+of mini frame will not be noted in the task bar and focus behaviour is different.
+On other platforms, it behaves like a normal frame.
 
 \wxheading{See also}
 

include/wx/gtk/dataobj.h

@@ -32,7 +32,7 @@ class wxPrivateDataObject;
 class wxFileDataObject;
 
 //-------------------------------------------------------------------------
-// wxDataFormat
+// wxDataType (internal)
 //-------------------------------------------------------------------------
 
 enum wxDataType
@@ -57,6 +57,10 @@ enum wxDataType
   wxDF_PRIVATE =          20
 };
 
+//-------------------------------------------------------------------------
+// wxDataFormat (internal)
+//-------------------------------------------------------------------------
+
 class wxDataFormat : public wxObject
 {
   DECLARE_CLASS( wxDataFormat )
@@ -86,7 +90,7 @@ private:
 };
 
 //-------------------------------------------------------------------------
-// wxDataBroker handles data and ormat negotiation for clipboard and DnD
+// wxDataBroker (internal)
 //-------------------------------------------------------------------------
 
 class wxDataBroker : public wxObject

include/wx/gtk1/dataobj.h

@@ -32,7 +32,7 @@ class wxPrivateDataObject;
 class wxFileDataObject;
 
 //-------------------------------------------------------------------------
-// wxDataFormat
+// wxDataType (internal)
 //-------------------------------------------------------------------------
 
 enum wxDataType
@@ -57,6 +57,10 @@ enum wxDataType
   wxDF_PRIVATE =          20
 };
 
+//-------------------------------------------------------------------------
+// wxDataFormat (internal)
+//-------------------------------------------------------------------------
+
 class wxDataFormat : public wxObject
 {
   DECLARE_CLASS( wxDataFormat )
@@ -86,7 +90,7 @@ private:
 };
 
 //-------------------------------------------------------------------------
-// wxDataBroker handles data and ormat negotiation for clipboard and DnD
+// wxDataBroker (internal)
 //-------------------------------------------------------------------------
 
 class wxDataBroker : public wxObject