X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/60a67569bf1bbcbc4d38c86ec30bb69613ecee92..d65c269b3f665e15a8ae1b8fff063b2ec0ef19a7:/docs/latex/wx/dataobj.tex?ds=sidebyside

diff --git a/docs/latex/wx/dataobj.tex b/docs/latex/wx/dataobj.tex
index b691ce1c0d..8292bb58ba 100644
--- a/docs/latex/wx/dataobj.tex
+++ b/docs/latex/wx/dataobj.tex
@@ -1,47 +1,121 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        dataobj.tex
+%% Purpose:     wxDataObject documentation
+%% Author:      Vadim Zeitlin
+%% Modified by:
+%% Created:     18.10.99
+%% RCS-ID:      $Id$
+%% Copyright:   (c) wxWindows team
+%% License:     wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
 \section{\class{wxDataObject}}\label{wxdataobject}
 
 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} 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.
+dragged and dropped. The important thing about wxDataObject is that this is a
+'smart' piece of data unlike usual 'dumb' data containers such as memory
+buffers or files. Being 'smart' here means that the data object itself should
+know what data formats it supports and how to render itself in each of
+supported formats.
+
+A supported format, incidentally, is exactly the format in which the data can
+be requested from a data object or from which the data object may be set. In
+the general case, an object may support different formats on 'input' and
+'output', i.e. it may be able to render itself in a given format but not be
+created from data on this format or vice versa. wxDataObject defines an
+enumeration type
+
+\begin{verbatim}
+enum Direction
+{
+    Get  = 0x01,    // format is supported by GetDataHere()
+    Set  = 0x02     // format is supported by SetData()
+};
+\end{verbatim}
+
+which allows to distinguish between them. See 
+\helpref{wxDataFormat}{wxdataformat} documentation for more about formats.
+
+Not surprizingly, being 'smart' comes at a price of added complexity. This is
+reasonable for the situations when you really need to support multiple formats,
+but may be annoying if you only want to do something simple like cut and paste
+text.
+
+To provide a solution for both cases, wxWindows has two predefined classes
+which derive from wxDataObject: \helpref{wxDataObjectSimple}{wxdataobjectsimple} and 
+\helpref{wxDataObjectComposite}{wxdataobjectcomposite}. 
+\helpref{wxDataObjectSimple}{wxdataobjectsimple} is
+the simplest wxDataObject possible and only holds data in a single format (such
+as HTML or text) and \helpref{wxDataObjectComposite}{wxdataobjectcomposite} is
+the simplest way to implement wxDataObject which does support multiple formats
+because it achievs this by simply holding several wxDataObjectSimple objects.
+
+So, you have several solutions when you need a wxDataObject class (and you need
+one as soon as you want to transfer data via the clipboard or drag and drop):
+
+\begin{twocollist}\itemsep=1cm
+\twocolitem{{\bf 1. Use one of the built-in classes}}{You may use wxTextDataObject,
+wxBitmapDataObject or wxFileDataObject in the simplest cases when you only need
+to support one format and your data is either text, bitmap or list of files.}
+\twocolitem{{\bf 2. Use wxDataObjectSimple}}{Deriving from wxDataObjectSimple is the simplest
+solution for custom data - you will only support one format and so probably
+won't be able to communicate with other programs, but data transfer will work
+in your program (or between different copies of it).}
+\twocolitem{{\bf 3. Use wxDataObjectComposite}}{This is a simple but powerful
+solution which allows you to support any number of formats (either
+standard or custom if you combine it with the previous solution).}
+\twocolitem{{\bf 4. Use wxDataObject directly}}{This is the solution for
+maximal flexibility and efficiency, but it is also is the most difficult to
+implement.}
+\end{twocollist}
+
+Please note that the easiest way to use drag and drop and the clipboard with
+multiple formats is by using wxDataObjectComposite, but it is not the most
+efficient one as each wxDataObjectSimple would contain the whole data in its
+respective formats. Now imagine that you want to paste 200 pages of text in
+your proprietary format, as well as Word, RTF, HTML, Unicode and plain text to
+the clipboard and even today's computers are in trouble. For this case, you
+will have to derive from wxDataObject directly and make it enumerate its
+formats and provide the data in the requested format on demand.
+
+Note that neither the GTK data transfer mechanisms for the clipboard and
+drag and drop, nor the OLE data transfer copy 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.
+
+There are several predefined data object classes derived from
+wxDataObjectSimple: \helpref{wxFileDataObject}{wxfiledataobject}, 
+\helpref{wxTextDataObject}{wxtextdataobject} and 
+\helpref{wxBitmapDataObject}{wxbitmapdataobject} which can be used without
+change.
+
+You may also derive your own data object classes from 
+\helpref{wxCustomDataObject}{wxcustomdataobject} 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 and drop). Note that the format string
+translation under Windows is not yet finished.
+
+\pythonnote{At this time this class is not directly usable from wxPython.
+Derive a class from \helpref{wxPyDataObjectSimple}{wxdataobjectsimple} 
+instead.}
+
+\wxheading{Virtual functions to override}
+
+Each class derived directly from wxDataObject must override and implement all
+of its functions which are pure virtual in the base class.
+
+The data objects which only render their data or only set it (i.e. work in
+only one direction), should return 0 from 
+\helpref{GetFormatCount}{wxdataobjectgetformatcount}.
 
 \wxheading{Derived from}
 
-\helpref{wxObject}{wxobject}
+None
 
 \wxheading{Include files}
 
@@ -49,13 +123,16 @@ available data and the WriteData() methods in both classes.
 
 \wxheading{See also}
 
+\helpref{Clipboard and drag and drop overview}{wxdndoverview}, 
+\helpref{DnD sample}{samplednd}, 
 \helpref{wxFileDataObject}{wxfiledataobject}, 
 \helpref{wxTextDataObject}{wxtextdataobject}, 
 \helpref{wxBitmapDataObject}{wxbitmapdataobject}, 
-\helpref{wxPrivateDataObject}{wxprivatedataobject}, 
-\helpref{Drag and drop overview}{wxdndoverview}, \helpref{wxDropTarget}{wxdroptarget}, 
+\helpref{wxCustomDataObject}{wxcustomdataobject}, 
+\helpref{wxDropTarget}{wxdroptarget}, 
 \helpref{wxDropSource}{wxdropsource}, 
-\helpref{wxTextDropTarget}{wxtextdroptarget}, \helpref{wxFileDropTarget}{wxfiledroptarget}
+\helpref{wxTextDropTarget}{wxtextdroptarget}, 
+\helpref{wxFileDropTarget}{wxfiledroptarget}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
@@ -71,18 +148,50 @@ Constructor.
 
 Destructor.
 
-\membersection{wxDataObject::WriteData}\label{wxdataobjectwritedata}
+\membersection{wxDataObject::GetAllFormats}\label{wxdataobjectgetallformats}
+
+\constfunc{virtual void}{GetAllFormats}{ \param{wxDataFormat *}{formats}, \param{Direction}{ dir = Get}}
+
+Copy all supported formats in the given direction to the array pointed to by 
+{\it formats}. There is enough space for GetFormatCount(dir) formats in it.
+
+\perlnote{In wxPerl this method only takes the {\tt dir} parameter. 
+In scalar context it returns the first format,
+in list context it returns a list containing all the supported formats.}
+
+\membersection{wxDataObject::GetDataHere}\label{wxdataobjectgetdatahere}
+
+\constfunc{virtual bool}{GetDataHere}{\param{const wxDataFormat\&}{ format}, \param{void }{*buf} }
+
+The method will write the data of the format {\it format} in the buffer {\it
+buf} and return TRUE on success, FALSE on failure.
+
+\membersection{wxDataObject::GetDataSize}\label{wxdataobjectgetdatasize}
+
+\constfunc{virtual size\_t}{GetDataSize}{\param{const wxDataFormat\&}{ format} }
+
+Returns the data size of the given format {\it format}.
+
+\membersection{wxDataObject::GetFormatCount}\label{wxdataobjectgetformatcount}
+
+\constfunc{virtual size\_t}{GetFormatCount}{\param{Direction}{ dir = Get}}
+
+Returns the number of available formats for rendering or setting the data.
+
+\membersection{wxDataObject::GetPreferredFormat}\label{wxdataobjectgetpreferredformat}
 
-\constfunc{virtual void}{WriteData}{\param{void}{*dest} }
+\constfunc{virtual wxDataFormat}{GetPreferredFormat}{\param{Direction}{ dir = Get}}
 
-Write the data owned by this class to {\it dest}. This method is a pure
-virtual function and must be overridden.
+Returns the preferred format for either rendering the data (if {\it dir} is {\tt Get},
+its default value) or for setting it. Usually this will be the
+native format of the wxDataObject.
 
-\membersection{wxDataObject::GetSize}\label{wxdataobjectgetdatasize}
+\membersection{wxDataObject::SetData}\label{wxdataobjectsetdata}
 
-\constfunc{virtual size\_t}{GetSize}{\void}
+\func{virtual bool}{SetData}{ \param{const wxDataFormat\&}{ format}, \param{size\_t}{ len}, \param{const void }{*buf} }
 
-Returns the data size. This method is a pure
-virtual function and must be overridden.
+Set the data in the format {\it format} of the length {\it len} provided in the
+buffer {\it buf}.
 
+Returns TRUE on success, FALSE on failure.
 
