]>
Commit | Line | Data |
---|---|---|
717a57c2 VZ |
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) wxWindows team | |
f6bcfd97 | 9 | %% License: wxWindows license |
717a57c2 VZ |
10 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
11 | ||
dface61c JS |
12 | \section{\class{wxDataObject}}\label{wxdataobject} |
13 | ||
14 | A wxDataObject represents data that can be copied to or from the clipboard, or | |
717a57c2 | 15 | dragged and dropped. The important thing about wxDataObject is that this is a |
407f3681 JS |
16 | 'smart' piece of data unlike usual 'dumb' data containers such as memory |
17 | buffers or files. Being 'smart' here means that the data object itself should | |
717a57c2 VZ |
18 | know what data formats it supports and how to render itself in each of |
19 | 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 | |
407f3681 JS |
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 | |
717a57c2 VZ |
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 | ||
fa482912 | 36 | which allows to distinguish between them. See |
717a57c2 VZ |
37 | \helpref{wxDataFormat}{wxdataformat} documentation for more about formats. |
38 | ||
407f3681 | 39 | Not surprizingly, being 'smart' comes at a price of added complexity. This is |
717a57c2 VZ |
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, wxWindows has two predefined classes | |
fa482912 JS |
45 | which derive from wxDataObject: \helpref{wxDataObjectSimple}{wxdataobjectsimple} and |
46 | \helpref{wxDataObjectComposite}{wxdataobjectcomposite}. | |
717a57c2 VZ |
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 wxDataObject which does support multiple formats | |
51 | because it achievs 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 | ||
c03648c2 | 56 | \begin{twocollist}\itemsep=1cm |
fa482912 | 57 | \twocolitem{{\bf 1. Use one of the built-in classes}}{You may use wxTextDataObject, |
717a57c2 | 58 | wxBitmapDataObject or wxFileDataObject in the simplest cases when you only need |
407f3681 | 59 | to support one format and your data is either text, bitmap or list of files.} |
fa482912 | 60 | \twocolitem{{\bf 2. Use wxDataObjectSimple}}{Deriving from wxDataObjectSimple is the simplest |
717a57c2 VZ |
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).} | |
fa482912 | 64 | \twocolitem{{\bf 3. Use wxDataObjectComposite}}{This is a simple but powerful |
407f3681 | 65 | solution which allows you to support any number of formats (either |
717a57c2 | 66 | standard or custom if you combine it with the previous solution).} |
fa482912 JS |
67 | \twocolitem{{\bf 4. Use wxDataObject directly}}{This is the solution for |
68 | maximal flexibility and efficiency, but it is also is the most difficult to | |
717a57c2 VZ |
69 | implement.} |
70 | \end{twocollist} | |
71 | ||
407f3681 | 72 | Please note that the easiest way to use drag and drop and the clipboard with |
717a57c2 VZ |
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 | |
f59d80ca | 75 | respective formats. Now imagine that you want to paste 200 pages of text in |
717a57c2 VZ |
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 the clipboard and | |
f59d80ca | 82 | drag and drop, nor the OLE data transfer copy any data until another application |
407f3681 | 83 | actually requests the data. This is in contrast to the 'feel' offered to the |
717a57c2 | 84 | user of a program who would normally think that the data resides in the |
407f3681 | 85 | clipboard after having pressed 'Copy' - in reality it is only declared to be |
717a57c2 VZ |
86 | available. |
87 | ||
88 | There are several predefined data object classes derived from | |
fa482912 JS |
89 | wxDataObjectSimple: \helpref{wxFileDataObject}{wxfiledataobject}, |
90 | \helpref{wxTextDataObject}{wxtextdataobject} and | |
717a57c2 VZ |
91 | \helpref{wxBitmapDataObject}{wxbitmapdataobject} which can be used without |
92 | change. | |
93 | ||
fa482912 | 94 | You may also derive your own data object classes from |
0a2017e0 | 95 | \helpref{wxCustomDataObject}{wxcustomdataobject} for user-defined types. The |
717a57c2 VZ |
96 | format of user-defined data is given as 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 | |
407f3681 JS |
100 | and from the clipboard and for drag and drop). Note that the format string |
101 | translation under Windows is not yet finished. | |
717a57c2 | 102 | |
874a1686 | 103 | \pythonnote{At this time this class is not directly usable from wxPython. |
fa482912 | 104 | Derive a class from \helpref{wxPyDataObjectSimple}{wxdataobjectsimple} |
b1462dfa RD |
105 | instead.} |
106 | ||
717a57c2 VZ |
107 | \wxheading{Virtual functions to override} |
108 | ||
109 | Each class derived directly from wxDataObject must override and implement all | |
110 | of its functions which are pure virtual in the base class. | |
111 | ||
112 | The data objects which only render their data or only set it (i.e. work in | |
fa482912 | 113 | only one direction), should return 0 from |
717a57c2 | 114 | \helpref{GetFormatCount}{wxdataobjectgetformatcount}. |
f37615d7 | 115 | |
dface61c JS |
116 | \wxheading{Derived from} |
117 | ||
717a57c2 | 118 | None |
dface61c | 119 | |
954b8ae6 JS |
120 | \wxheading{Include files} |
121 | ||
122 | <wx/dataobj.h> | |
123 | ||
dface61c JS |
124 | \wxheading{See also} |
125 | ||
fa482912 JS |
126 | \helpref{Clipboard and drag and drop overview}{wxdndoverview}, |
127 | \helpref{DnD sample}{samplednd}, | |
128 | \helpref{wxFileDataObject}{wxfiledataobject}, | |
129 | \helpref{wxTextDataObject}{wxtextdataobject}, | |
130 | \helpref{wxBitmapDataObject}{wxbitmapdataobject}, | |
131 | \helpref{wxCustomDataObject}{wxcustomdataobject}, | |
132 | \helpref{wxDropTarget}{wxdroptarget}, | |
133 | \helpref{wxDropSource}{wxdropsource}, | |
134 | \helpref{wxTextDropTarget}{wxtextdroptarget}, | |
717a57c2 | 135 | \helpref{wxFileDropTarget}{wxfiledroptarget} |
dface61c JS |
136 | |
137 | \latexignore{\rtfignore{\wxheading{Members}}} | |
138 | ||
139 | \membersection{wxDataObject::wxDataObject}\label{wxdataobjectwxdataobject} | |
140 | ||
141 | \func{}{wxDataObject}{\void} | |
142 | ||
143 | Constructor. | |
144 | ||
145 | \membersection{wxDataObject::\destruct{wxDataObject}}\label{wxdataobjectdtor} | |
146 | ||
147 | \func{}{\destruct{wxDataObject}}{\void} | |
148 | ||
149 | Destructor. | |
150 | ||
717a57c2 | 151 | \membersection{wxDataObject::GetAllFormats}\label{wxdataobjectgetallformats} |
fc9c7c09 | 152 | |
407f3681 | 153 | \constfunc{virtual void}{GetAllFormats}{ \param{wxDataFormat *}{formats}, \param{Direction}{ dir = Get}} |
fc9c7c09 | 154 | |
fa482912 | 155 | Copy all supported formats in the given direction to the array pointed to by |
407f3681 | 156 | {\it formats}. There is enough space for GetFormatCount(dir) formats in it. |
fc9c7c09 | 157 | |
0a67eeac MB |
158 | \perlnote{In wxPerl this method only takes the {\tt dir} parameter. |
159 | In scalar context it returns the first format, | |
160 | in list context it returns a list containing all the supported formats.} | |
161 | ||
fc9c7c09 RR |
162 | \membersection{wxDataObject::GetDataHere}\label{wxdataobjectgetdatahere} |
163 | ||
717a57c2 | 164 | \constfunc{virtual bool}{GetDataHere}{\param{const wxDataFormat\&}{ format}, \param{void }{*buf} } |
fc9c7c09 | 165 | |
717a57c2 VZ |
166 | The method will write the data of the format {\it format} in the buffer {\it |
167 | buf} and return TRUE on success, FALSE on failure. | |
fc9c7c09 RR |
168 | |
169 | \membersection{wxDataObject::GetDataSize}\label{wxdataobjectgetdatasize} | |
170 | ||
171 | \constfunc{virtual size\_t}{GetDataSize}{\param{const wxDataFormat\&}{ format} } | |
172 | ||
173 | Returns the data size of the given format {\it format}. | |
174 | ||
717a57c2 VZ |
175 | \membersection{wxDataObject::GetFormatCount}\label{wxdataobjectgetformatcount} |
176 | ||
177 | \constfunc{virtual size\_t}{GetFormatCount}{\param{Direction}{ dir = Get}} | |
178 | ||
407f3681 | 179 | Returns the number of available formats for rendering or setting the data. |
717a57c2 | 180 | |
fc9c7c09 | 181 | \membersection{wxDataObject::GetPreferredFormat}\label{wxdataobjectgetpreferredformat} |
f37615d7 | 182 | |
717a57c2 | 183 | \constfunc{virtual wxDataFormat}{GetPreferredFormat}{\param{Direction}{ dir = Get}} |
f37615d7 | 184 | |
407f3681 JS |
185 | Returns the preferred format for either rendering the data (if {\it dir} is {\tt Get}, |
186 | its default value) or for setting it. Usually this will be the | |
717a57c2 | 187 | native format of the wxDataObject. |
f37615d7 | 188 | |
fc9c7c09 | 189 | \membersection{wxDataObject::SetData}\label{wxdataobjectsetdata} |
f37615d7 | 190 | |
407f3681 | 191 | \func{virtual bool}{SetData}{ \param{const wxDataFormat\&}{ format}, \param{size\_t}{ len}, \param{const void }{*buf} } |
717a57c2 VZ |
192 | |
193 | Set the data in the format {\it format} of the length {\it len} provided in the | |
194 | buffer {\it buf}. | |
dface61c | 195 | |
407f3681 | 196 | Returns TRUE on success, FALSE on failure. |
dface61c | 197 |