From: Robert Roebling Date: Sat, 30 Jan 1999 00:15:17 +0000 (+0000) Subject: wxDataObject documented X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/f37615d7896e9b976c5c251e567570c394f19cf8 wxDataObject documented git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@1520 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- diff --git a/docs/latex/wx/dataobj.tex b/docs/latex/wx/dataobj.tex index 4efc76278e..556384fc70 100644 --- a/docs/latex/wx/dataobj.tex +++ b/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}. - -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} - -\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 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}. diff --git a/docs/latex/wx/minifram.tex b/docs/latex/wx/minifram.tex index db8cd206b4..afc01f7d0f 100644 --- a/docs/latex/wx/minifram.tex +++ b/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, -it behaves like a normal frame. +This class has miniframe functionality under Windows and GTK, i.e. the presence +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} diff --git a/include/wx/gtk/dataobj.h b/include/wx/gtk/dataobj.h index 13c80135ca..42233e4494 100644 --- a/include/wx/gtk/dataobj.h +++ b/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 diff --git a/include/wx/gtk1/dataobj.h b/include/wx/gtk1/dataobj.h index 13c80135ca..42233e4494 100644 --- a/include/wx/gtk1/dataobj.h +++ b/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