| 1 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| 2 | %% Name: dataobj.tex |
| 3 | %% Purpose: wxDataObject documentation |
| 4 | %% Author: Vadim Zeitlin |
| 5 | %% Modified by: |
| 6 | %% Created: 18.10.99 |
| 7 | %% RCS-ID: $Id$ |
| 8 | %% Copyright: (c) wxWidgets team |
| 9 | %% License: wxWindows license |
| 10 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| 11 | |
| 12 | \section{\class{wxDataObject}}\label{wxdataobject} |
| 13 | |
| 14 | A wxDataObject represents data that can be copied to or from the clipboard, or |
| 15 | dragged and dropped. The important thing about wxDataObject is that this is a |
| 16 | 'smart' piece of data unlike 'dumb' data containers such as memory |
| 17 | buffers or files. Being 'smart' here means that the data object itself should |
| 18 | know what data formats it supports and how to render itself in each of |
| 19 | its supported formats. |
| 20 | |
| 21 | A supported format, incidentally, is exactly the format in which the data can |
| 22 | be requested from a data object or from which the data object may be set. In |
| 23 | the general case, an object may support different formats on 'input' and |
| 24 | 'output', i.e. it may be able to render itself in a given format but not be |
| 25 | created from data on this format or vice versa. wxDataObject defines an |
| 26 | enumeration type |
| 27 | |
| 28 | \begin{verbatim} |
| 29 | enum Direction |
| 30 | { |
| 31 | Get = 0x01, // format is supported by GetDataHere() |
| 32 | Set = 0x02 // format is supported by SetData() |
| 33 | }; |
| 34 | \end{verbatim} |
| 35 | |
| 36 | which distinguishes between them. See |
| 37 | \helpref{wxDataFormat}{wxdataformat} documentation for more about formats. |
| 38 | |
| 39 | Not surprisingly, being 'smart' comes at a price of added complexity. This is |
| 40 | reasonable for the situations when you really need to support multiple formats, |
| 41 | but may be annoying if you only want to do something simple like cut and paste |
| 42 | text. |
| 43 | |
| 44 | To provide a solution for both cases, wxWidgets has two predefined classes |
| 45 | which derive from wxDataObject: \helpref{wxDataObjectSimple}{wxdataobjectsimple} and |
| 46 | \helpref{wxDataObjectComposite}{wxdataobjectcomposite}. |
| 47 | \helpref{wxDataObjectSimple}{wxdataobjectsimple} is |
| 48 | the simplest wxDataObject possible and only holds data in a single format (such |
| 49 | as HTML or text) and \helpref{wxDataObjectComposite}{wxdataobjectcomposite} is |
| 50 | the simplest way to implement a wxDataObject that does support multiple formats |
| 51 | because it achieves this by simply holding several wxDataObjectSimple objects. |
| 52 | |
| 53 | So, you have several solutions when you need a wxDataObject class (and you need |
| 54 | one as soon as you want to transfer data via the clipboard or drag and drop): |
| 55 | |
| 56 | \begin{twocollist}\itemsep=1cm |
| 57 | \twocolitem{{\bf 1. Use one of the built-in classes}}{You may use wxTextDataObject, |
| 58 | wxBitmapDataObject or wxFileDataObject in the simplest cases when you only need |
| 59 | to support one format and your data is either text, bitmap or list of files.} |
| 60 | \twocolitem{{\bf 2. Use wxDataObjectSimple}}{Deriving from wxDataObjectSimple is the simplest |
| 61 | solution for custom data - you will only support one format and so probably |
| 62 | won't be able to communicate with other programs, but data transfer will work |
| 63 | in your program (or between different copies of it).} |
| 64 | \twocolitem{{\bf 3. Use wxDataObjectComposite}}{This is a simple but powerful |
| 65 | solution which allows you to support any number of formats (either |
| 66 | standard or custom if you combine it with the previous solution).} |
| 67 | \twocolitem{{\bf 4. Use wxDataObject directly}}{This is the solution for |
| 68 | maximal flexibility and efficiency, but it is also the most difficult to |
| 69 | implement.} |
| 70 | \end{twocollist} |
| 71 | |
| 72 | Please note that the easiest way to use drag and drop and the clipboard with |
| 73 | multiple formats is by using wxDataObjectComposite, but it is not the most |
| 74 | efficient one as each wxDataObjectSimple would contain the whole data in its |
| 75 | respective formats. Now imagine that you want to paste 200 pages of text in |
| 76 | your proprietary format, as well as Word, RTF, HTML, Unicode and plain text to |
| 77 | the clipboard and even today's computers are in trouble. For this case, you |
| 78 | will have to derive from wxDataObject directly and make it enumerate its |
| 79 | formats and provide the data in the requested format on demand. |
| 80 | |
| 81 | Note that neither the GTK+ data transfer mechanisms for clipboard and |
| 82 | drag and drop, nor OLE data transfer, copy any data until another application |
| 83 | actually requests the data. This is in contrast to the 'feel' offered to the |
| 84 | user of a program who would normally think that the data resides in the |
| 85 | clipboard after having pressed 'Copy' - in reality it is only declared to be |
| 86 | available. |
| 87 | |
| 88 | There are several predefined data object classes derived from |
| 89 | wxDataObjectSimple: \helpref{wxFileDataObject}{wxfiledataobject}, |
| 90 | \helpref{wxTextDataObject}{wxtextdataobject} and |
| 91 | \helpref{wxBitmapDataObject}{wxbitmapdataobject} which can be used without |
| 92 | change. |
| 93 | |
| 94 | You may also derive your own data object classes from |
| 95 | \helpref{wxCustomDataObject}{wxcustomdataobject} for user-defined types. The |
| 96 | format of user-defined data is given as a mime-type string literal, such as |
| 97 | "application/word" or "image/png". These strings are used as they are under |
| 98 | Unix (so far only GTK+) to identify a format and are translated into their |
| 99 | Windows equivalent under Win32 (using the OLE IDataObject for data exchange to |
| 100 | and from the clipboard and for drag and drop). Note that the format string |
| 101 | translation under Windows is not yet finished. |
| 102 | |
| 103 | \pythonnote{At this time this class is not directly usable from wxPython. |
| 104 | Derive a class from \helpref{wxPyDataObjectSimple}{wxdataobjectsimple} |
| 105 | instead.} |
| 106 | |
| 107 | \perlnote{This class is not currently usable from wxPerl; you may |
| 108 | use \helpref{Wx::PlDataObjectSimple}{wxdataobjectsimple} instead.} |
| 109 | |
| 110 | \wxheading{Virtual functions to override} |
| 111 | |
| 112 | Each class derived directly from wxDataObject must override and implement all |
| 113 | of its functions which are pure virtual in the base class. |
| 114 | |
| 115 | The data objects which only render their data or only set it (i.e. work in |
| 116 | only one direction), should return 0 from |
| 117 | \helpref{GetFormatCount}{wxdataobjectgetformatcount}. |
| 118 | |
| 119 | \wxheading{Derived from} |
| 120 | |
| 121 | None |
| 122 | |
| 123 | \wxheading{Include files} |
| 124 | |
| 125 | <wx/dataobj.h> |
| 126 | |
| 127 | \wxheading{Library} |
| 128 | |
| 129 | \helpref{wxCore}{librarieslist} |
| 130 | |
| 131 | \wxheading{See also} |
| 132 | |
| 133 | \helpref{Clipboard and drag and drop overview}{wxdndoverview}, |
| 134 | \helpref{DnD sample}{samplednd}, |
| 135 | \helpref{wxFileDataObject}{wxfiledataobject}, |
| 136 | \helpref{wxTextDataObject}{wxtextdataobject}, |
| 137 | \helpref{wxBitmapDataObject}{wxbitmapdataobject}, |
| 138 | \helpref{wxCustomDataObject}{wxcustomdataobject}, |
| 139 | \helpref{wxDropTarget}{wxdroptarget}, |
| 140 | \helpref{wxDropSource}{wxdropsource}, |
| 141 | \helpref{wxTextDropTarget}{wxtextdroptarget}, |
| 142 | \helpref{wxFileDropTarget}{wxfiledroptarget} |
| 143 | |
| 144 | \latexignore{\rtfignore{\wxheading{Members}}} |
| 145 | |
| 146 | \membersection{wxDataObject::wxDataObject}\label{wxdataobjectwxdataobject} |
| 147 | |
| 148 | \func{}{wxDataObject}{\void} |
| 149 | |
| 150 | Constructor. |
| 151 | |
| 152 | \membersection{wxDataObject::\destruct{wxDataObject}}\label{wxdataobjectdtor} |
| 153 | |
| 154 | \func{}{\destruct{wxDataObject}}{\void} |
| 155 | |
| 156 | Destructor. |
| 157 | |
| 158 | \membersection{wxDataObject::GetAllFormats}\label{wxdataobjectgetallformats} |
| 159 | |
| 160 | \constfunc{virtual void}{GetAllFormats}{ \param{wxDataFormat *}{formats}, \param{Direction}{ dir = Get}} |
| 161 | |
| 162 | Copy all supported formats in the given direction to the array pointed to by |
| 163 | {\it formats}. There is enough space for GetFormatCount(dir) formats in it. |
| 164 | |
| 165 | \perlnote{In wxPerl this method only takes the {\tt dir} parameter. |
| 166 | In scalar context it returns the first format, |
| 167 | in list context it returns a list containing all the supported formats.} |
| 168 | |
| 169 | \membersection{wxDataObject::GetDataHere}\label{wxdataobjectgetdatahere} |
| 170 | |
| 171 | \constfunc{virtual bool}{GetDataHere}{\param{const wxDataFormat\&}{ format}, \param{void }{*buf} } |
| 172 | |
| 173 | The method will write the data of the format {\it format} in the buffer {\it |
| 174 | buf} and return true on success, false on failure. |
| 175 | |
| 176 | \membersection{wxDataObject::GetDataSize}\label{wxdataobjectgetdatasize} |
| 177 | |
| 178 | \constfunc{virtual size\_t}{GetDataSize}{\param{const wxDataFormat\&}{ format} } |
| 179 | |
| 180 | Returns the data size of the given format {\it format}. |
| 181 | |
| 182 | \membersection{wxDataObject::GetFormatCount}\label{wxdataobjectgetformatcount} |
| 183 | |
| 184 | \constfunc{virtual size\_t}{GetFormatCount}{\param{Direction}{ dir = Get}} |
| 185 | |
| 186 | Returns the number of available formats for rendering or setting the data. |
| 187 | |
| 188 | \membersection{wxDataObject::GetPreferredFormat}\label{wxdataobjectgetpreferredformat} |
| 189 | |
| 190 | \constfunc{virtual wxDataFormat}{GetPreferredFormat}{\param{Direction}{ dir = Get}} |
| 191 | |
| 192 | Returns the preferred format for either rendering the data (if {\it dir} is {\tt Get}, |
| 193 | its default value) or for setting it. Usually this will be the |
| 194 | native format of the wxDataObject. |
| 195 | |
| 196 | \membersection{wxDataObject::SetData}\label{wxdataobjectsetdata} |
| 197 | |
| 198 | \func{virtual bool}{SetData}{ \param{const wxDataFormat\&}{ format}, \param{size\_t}{ len}, \param{const void }{*buf} } |
| 199 | |
| 200 | Set the data in the format {\it format} of the length {\it len} provided in the |
| 201 | buffer {\it buf}. |
| 202 | |
| 203 | Returns true on success, false on failure. |
| 204 | |