+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 0. Use one of 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 1. 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 2. 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 3. Use wxDataObject directly}}{This is the solution for
+maximal flexibility and efficiency, but it 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}.
projects / wxWidgets.git / blobdiff