]>
Commit | Line | Data |
---|---|---|
1 | /////////////////////////////////////////////////////////////////////////////// | |
2 | // Name: wx/dataobj.h | |
3 | // Purpose: common data object classes | |
4 | // Author: Vadim Zeitlin, Robert Roebling | |
5 | // Modified by: | |
6 | // Created: 26.05.99 | |
7 | // RCS-ID: $Id$ | |
8 | // Copyright: (c) wxWindows Team | |
9 | // Licence: wxWindows license | |
10 | /////////////////////////////////////////////////////////////////////////////// | |
11 | ||
12 | #ifndef _WX_DATAOBJ_H_BASE_ | |
13 | #define _WX_DATAOBJ_H_BASE_ | |
14 | ||
15 | #ifdef __GNUG__ | |
16 | #pragma interface "dataobjbase.h" | |
17 | #endif | |
18 | ||
19 | // ---------------------------------------------------------------------------- | |
20 | // headers | |
21 | // ---------------------------------------------------------------------------- | |
22 | ||
23 | #include "wx/defs.h" | |
24 | #include "wx/string.h" | |
25 | #include "wx/bitmap.h" | |
26 | #include "wx/list.h" | |
27 | ||
28 | // ============================================================================ | |
29 | /* | |
30 | Generic data transfer related classes. The class hierarchy is as follows: | |
31 | ||
32 | - wxDataObject- | |
33 | / \ | |
34 | / \ | |
35 | wxDataObjectSimple wxDataObjectComposite | |
36 | / | \ | |
37 | / | \ | |
38 | wxTextDataObject | wxBitmapDataObject | |
39 | | | |
40 | wxCustomDataObject | |
41 | ||
42 | */ | |
43 | // ============================================================================ | |
44 | ||
45 | // ---------------------------------------------------------------------------- | |
46 | // wxDataFormat class is declared in platform-specific headers: it represents | |
47 | // a format for data which may be either one of the standard ones (text, | |
48 | // bitmap, ...) or a custom one which is then identified by a unique string. | |
49 | // ---------------------------------------------------------------------------- | |
50 | ||
51 | /* the class interface looks like this (pseudo code): | |
52 | ||
53 | class wxDataFormat | |
54 | { | |
55 | public: | |
56 | typedef <integral type> NativeFormat; | |
57 | ||
58 | wxDataFormat(NativeFormat format = wxDF_INVALID); | |
59 | wxDataFormat(const wxChar *format); | |
60 | ||
61 | wxDataFormat& operator=(NativeFormat format); | |
62 | wxDataFormat& operator=(const wxDataFormat& format); | |
63 | ||
64 | bool operator==(NativeFormat format) const; | |
65 | bool operator!=(NativeFormat format) const; | |
66 | ||
67 | void SetType(NativeFormat format); | |
68 | NativeFormat GetType() const; | |
69 | ||
70 | wxString GetId() const; | |
71 | void SetId(const wxChar *format); | |
72 | }; | |
73 | ||
74 | */ | |
75 | ||
76 | #if defined(__WXMSW__) | |
77 | #include "wx/msw/ole/dataform.h" | |
78 | #elif defined(__WXMOTIF__) | |
79 | #include "wx/motif/dataform.h" | |
80 | #elif defined(__WXGTK__) | |
81 | #include "wx/gtk/dataform.h" | |
82 | #elif defined(__WXMAC__) | |
83 | #include "wx/mac/dataform.h" | |
84 | #elif defined(__WXPM__) | |
85 | #include "wx/os2/dataform.h" | |
86 | #endif | |
87 | ||
88 | // the value for default argument to some functions (corresponds to | |
89 | // wxDF_INVALID) | |
90 | extern WXDLLEXPORT const wxDataFormat& wxFormatInvalid; | |
91 | ||
92 | // ---------------------------------------------------------------------------- | |
93 | // wxDataObject represents a piece of data which knows which formats it | |
94 | // supports and knows how to render itself in each of them - GetDataHere(), | |
95 | // and how to restore data from the buffer (SetData()). | |
96 | // | |
97 | // Although this class may be used directly (i.e. custom classes may be | |
98 | // derived from it), in many cases it might be simpler to use either | |
99 | // wxDataObjectSimple or wxDataObjectComposite classes. | |
100 | // | |
101 | // A data object may be "read only", i.e. support only GetData() functions or | |
102 | // "read-write", i.e. support both GetData() and SetData() (in principle, it | |
103 | // might be "write only" too, but this is rare). Moreover, it doesn't have to | |
104 | // support the same formats in Get() and Set() directions: for example, a data | |
105 | // object containing JPEG image might accept BMPs in GetData() because JPEG | |
106 | // image may be easily transformed into BMP but not in SetData(). Accordingly, | |
107 | // all methods dealing with formats take an additional "direction" argument | |
108 | // which is either SET or GET and which tells the function if the format needs | |
109 | // to be supported by SetData() or GetDataHere(). | |
110 | // ---------------------------------------------------------------------------- | |
111 | ||
112 | class WXDLLEXPORT wxDataObjectBase | |
113 | { | |
114 | public: | |
115 | enum Direction | |
116 | { | |
117 | Get = 0x01, // format is supported by GetDataHere() | |
118 | Set = 0x02, // format is supported by SetData() | |
119 | Both = 0x03 // format is supported by both (unused currently) | |
120 | }; | |
121 | ||
122 | // this class is polymorphic, hence it needs a virtual dtor | |
123 | virtual ~wxDataObjectBase(); | |
124 | ||
125 | // get the best suited format for rendering our data | |
126 | virtual wxDataFormat GetPreferredFormat(Direction dir = Get) const = 0; | |
127 | ||
128 | // get the number of formats we support | |
129 | virtual size_t GetFormatCount(Direction dir = Get) const = 0; | |
130 | ||
131 | // return all formats in the provided array (of size GetFormatCount()) | |
132 | virtual void GetAllFormats(wxDataFormat *formats, | |
133 | Direction dir = Get) const = 0; | |
134 | ||
135 | // get the (total) size of data for the given format | |
136 | virtual size_t GetDataSize(const wxDataFormat& format) const = 0; | |
137 | ||
138 | // copy raw data (in the specified format) to the provided buffer, return | |
139 | // TRUE if data copied successfully, FALSE otherwise | |
140 | virtual bool GetDataHere(const wxDataFormat& format, void *buf) const = 0; | |
141 | ||
142 | // get data from the buffer of specified length (in the given format), | |
143 | // return TRUE if the data was read successfully, FALSE otherwise | |
144 | virtual bool SetData(const wxDataFormat& WXUNUSED(format), | |
145 | size_t WXUNUSED(len), const void * WXUNUSED(buf)) | |
146 | { | |
147 | return FALSE; | |
148 | } | |
149 | ||
150 | // returns TRUE if this format is supported | |
151 | bool IsSupported(const wxDataFormat& format, Direction dir = Get) const; | |
152 | }; | |
153 | ||
154 | // ---------------------------------------------------------------------------- | |
155 | // include the platform-specific declarations of wxDataObject | |
156 | // ---------------------------------------------------------------------------- | |
157 | ||
158 | #if defined(__WXMSW__) | |
159 | #include "wx/msw/ole/dataobj.h" | |
160 | #elif defined(__WXMOTIF__) | |
161 | #include "wx/motif/dataobj.h" | |
162 | #elif defined(__WXGTK__) | |
163 | #include "wx/gtk/dataobj.h" | |
164 | #elif defined(__WXMAC__) | |
165 | #include "wx/mac/dataobj.h" | |
166 | #elif defined(__WXPM__) | |
167 | #include "wx/os2/dataobj.h" | |
168 | #elif defined(__WXSTUBS__) | |
169 | #include "wx/stubs/dnd.h" | |
170 | #endif | |
171 | ||
172 | // ---------------------------------------------------------------------------- | |
173 | // wxDataObjectSimple is a wxDataObject which only supports one format (in | |
174 | // both Get and Set directions, but you may return FALSE from GetDataHere() or | |
175 | // SetData() if one of them is not supported). This is the simplest possible | |
176 | // wxDataObject implementation. | |
177 | // | |
178 | // This is still an "abstract base class" (although it doesn't have any pure | |
179 | // virtual functions), to use it you should derive from it and implement | |
180 | // GetDataSize(), GetDataHere() and SetData() functions because the base class | |
181 | // versions don't do anything - they just return "not implemented". | |
182 | // | |
183 | // This class should be used when you provide data in only one format (no | |
184 | // conversion to/from other formats), either a standard or a custom one. | |
185 | // Otherwise, you should use wxDataObjectComposite or wxDataObject directly. | |
186 | // ---------------------------------------------------------------------------- | |
187 | ||
188 | class WXDLLEXPORT wxDataObjectSimple : public wxDataObject | |
189 | { | |
190 | public: | |
191 | // ctor takes the format we support, but it can also be set later with | |
192 | // SetFormat() | |
193 | wxDataObjectSimple(const wxDataFormat& format = wxFormatInvalid) | |
194 | : m_format(format) | |
195 | { | |
196 | } | |
197 | ||
198 | // get/set the format we support | |
199 | const wxDataFormat& GetFormat() const { return m_format; } | |
200 | void SetFormat(const wxDataFormat& format) { m_format = format; } | |
201 | ||
202 | // virtual functions to override in derived class (the base class versions | |
203 | // just return "not implemented") | |
204 | // ----------------------------------------------------------------------- | |
205 | ||
206 | // get the size of our data | |
207 | virtual size_t GetDataSize() const | |
208 | { return 0; } | |
209 | ||
210 | // copy our data to the buffer | |
211 | virtual bool GetDataHere(void *WXUNUSED(buf)) const | |
212 | { return FALSE; } | |
213 | ||
214 | // copy data from buffer to our data | |
215 | virtual bool SetData(size_t WXUNUSED(len), const void *WXUNUSED(buf)) | |
216 | { return FALSE; } | |
217 | ||
218 | // implement base class pure virtuals | |
219 | // ---------------------------------- | |
220 | virtual wxDataFormat GetPreferredFormat(wxDataObjectBase::Direction WXUNUSED(dir) = Get) const | |
221 | { return m_format; } | |
222 | virtual size_t GetFormatCount(wxDataObjectBase::Direction WXUNUSED(dir) = Get) const | |
223 | { return 1; } | |
224 | virtual void GetAllFormats(wxDataFormat *formats, | |
225 | wxDataObjectBase::Direction WXUNUSED(dir) = Get) const | |
226 | { *formats = m_format; } | |
227 | virtual size_t GetDataSize(const wxDataFormat& WXUNUSED(format)) const | |
228 | { return GetDataSize(); } | |
229 | virtual bool GetDataHere(const wxDataFormat& WXUNUSED(format), | |
230 | void *buf) const | |
231 | { return GetDataHere(buf); } | |
232 | virtual bool SetData(const wxDataFormat& WXUNUSED(format), | |
233 | size_t len, const void *buf) | |
234 | { return SetData(len, buf); } | |
235 | ||
236 | private: | |
237 | // the one and only format we support | |
238 | wxDataFormat m_format; | |
239 | }; | |
240 | ||
241 | // ---------------------------------------------------------------------------- | |
242 | // wxDataObjectComposite is the simplest way to implement wxDataObject | |
243 | // supporting multiple formats. It contains several wxDataObjectSimple and | |
244 | // supports all formats supported by any of them. | |
245 | // | |
246 | // This class shouldn't be (normally) derived from, but may be used directly. | |
247 | // If you need more flexibility than what it provides, you should probably use | |
248 | // wxDataObject directly. | |
249 | // ---------------------------------------------------------------------------- | |
250 | ||
251 | WX_DECLARE_EXPORTED_LIST(wxDataObjectSimple, wxSimpleDataObjectList); | |
252 | ||
253 | class WXDLLEXPORT wxDataObjectComposite : public wxDataObject | |
254 | { | |
255 | public: | |
256 | // ctor | |
257 | wxDataObjectComposite() { m_preferred = 0; } | |
258 | ||
259 | // add data object (it will be deleted by wxDataObjectComposite, hence it | |
260 | // must be allocated on the heap) whose format will become the preferred | |
261 | // one if preferred == TRUE | |
262 | void Add(wxDataObjectSimple *dataObject, bool preferred = FALSE); | |
263 | ||
264 | // implement base class pure virtuals | |
265 | // ---------------------------------- | |
266 | virtual wxDataFormat GetPreferredFormat(wxDataObjectBase::Direction dir = Get) const; | |
267 | virtual size_t GetFormatCount(wxDataObjectBase::Direction dir = Get) const; | |
268 | virtual void GetAllFormats(wxDataFormat *formats, wxDataObjectBase::Direction dir = Get) const; | |
269 | virtual size_t GetDataSize(const wxDataFormat& format) const; | |
270 | virtual bool GetDataHere(const wxDataFormat& format, void *buf) const; | |
271 | virtual bool SetData(const wxDataFormat& format, size_t len, const void *buf); | |
272 | ||
273 | protected: | |
274 | // returns the pointer to the object which supports this format or NULL | |
275 | wxDataObjectSimple *GetObject(const wxDataFormat& format) const; | |
276 | #if defined(__WXMSW__) | |
277 | virtual const void* GetSizeFromBuffer( const void* buffer, size_t* size, | |
278 | const wxDataFormat& format ); | |
279 | virtual void* SetSizeInBuffer( void* buffer, size_t size, | |
280 | const wxDataFormat& format ); | |
281 | virtual size_t GetBufferOffset( const wxDataFormat& format ); | |
282 | #endif | |
283 | ||
284 | private: | |
285 | // the list of all (simple) data objects whose formats we support | |
286 | wxSimpleDataObjectList m_dataObjects; | |
287 | ||
288 | // the index of the preferred one (0 initially, so by default the first | |
289 | // one is the preferred) | |
290 | size_t m_preferred; | |
291 | }; | |
292 | ||
293 | // ============================================================================ | |
294 | // Standard implementations of wxDataObjectSimple which can be used directly | |
295 | // (i.e. without having to derive from them) for standard data type transfers. | |
296 | // | |
297 | // Note that although all of them can work with provided data, you can also | |
298 | // override their virtual GetXXX() functions to only provide data on demand. | |
299 | // ============================================================================ | |
300 | ||
301 | // ---------------------------------------------------------------------------- | |
302 | // wxTextDataObject contains text data | |
303 | // ---------------------------------------------------------------------------- | |
304 | ||
305 | class WXDLLEXPORT wxTextDataObject : public wxDataObjectSimple | |
306 | { | |
307 | public: | |
308 | // ctor: you can specify the text here or in SetText(), or override | |
309 | // GetText() | |
310 | wxTextDataObject(const wxString& text = wxEmptyString) | |
311 | : wxDataObjectSimple(wxUSE_UNICODE?wxDF_UNICODETEXT:wxDF_TEXT), | |
312 | m_text(text) | |
313 | { | |
314 | } | |
315 | ||
316 | // virtual functions which you may override if you want to provide text on | |
317 | // demand only - otherwise, the trivial default versions will be used | |
318 | virtual size_t GetTextLength() const { return m_text.Len() + 1; } | |
319 | virtual wxString GetText() const { return m_text; } | |
320 | virtual void SetText(const wxString& text) { m_text = text; } | |
321 | ||
322 | // implement base class pure virtuals | |
323 | // ---------------------------------- | |
324 | virtual size_t GetDataSize() const; | |
325 | virtual bool GetDataHere(void *buf) const; | |
326 | virtual bool SetData(size_t len, const void *buf); | |
327 | ||
328 | private: | |
329 | wxString m_text; | |
330 | ||
331 | // virtual function hiding supression | |
332 | size_t GetDataSize(const wxDataFormat& format) const | |
333 | { return(wxDataObjectSimple::GetDataSize(format)); } | |
334 | bool GetDataHere(const wxDataFormat& format, void *pBuf) const | |
335 | { return(wxDataObjectSimple::GetDataHere(format, pBuf)); } | |
336 | bool SetData(const wxDataFormat& format, size_t nLen, const void* pBuf) | |
337 | { return(wxDataObjectSimple::SetData(format, nLen, pBuf)); } | |
338 | }; | |
339 | ||
340 | // ---------------------------------------------------------------------------- | |
341 | // wxBitmapDataObject contains a bitmap | |
342 | // ---------------------------------------------------------------------------- | |
343 | ||
344 | class WXDLLEXPORT wxBitmapDataObjectBase : public wxDataObjectSimple | |
345 | { | |
346 | public: | |
347 | // ctor: you can specify the bitmap here or in SetBitmap(), or override | |
348 | // GetBitmap() | |
349 | wxBitmapDataObjectBase(const wxBitmap& bitmap = wxNullBitmap) | |
350 | : wxDataObjectSimple(wxDF_BITMAP), m_bitmap(bitmap) | |
351 | { | |
352 | } | |
353 | ||
354 | // virtual functions which you may override if you want to provide data on | |
355 | // demand only - otherwise, the trivial default versions will be used | |
356 | virtual wxBitmap GetBitmap() const { return m_bitmap; } | |
357 | virtual void SetBitmap(const wxBitmap& bitmap) { m_bitmap = bitmap; } | |
358 | ||
359 | protected: | |
360 | wxBitmap m_bitmap; | |
361 | }; | |
362 | ||
363 | // ---------------------------------------------------------------------------- | |
364 | // wxFileDataObject contains a list of filenames | |
365 | // | |
366 | // NB: notice that this is a "write only" object, it can only be filled with | |
367 | // data from drag and drop operation. | |
368 | // ---------------------------------------------------------------------------- | |
369 | ||
370 | class WXDLLEXPORT wxFileDataObjectBase : public wxDataObjectSimple | |
371 | { | |
372 | public: | |
373 | // ctor: use AddFile() later to fill the array | |
374 | wxFileDataObjectBase() : wxDataObjectSimple(wxDF_FILENAME) { } | |
375 | ||
376 | // get a reference to our array | |
377 | const wxArrayString& GetFilenames() const { return m_filenames; } | |
378 | ||
379 | // the Get() functions do nothing for us | |
380 | virtual size_t GetDataSize() const { return 0; } | |
381 | virtual bool GetDataHere(void *WXUNUSED(buf)) const { return FALSE; } | |
382 | ||
383 | protected: | |
384 | wxArrayString m_filenames; | |
385 | ||
386 | private: | |
387 | // Virtual function hiding supression | |
388 | size_t GetDataSize(const wxDataFormat& format) const | |
389 | { return(wxDataObjectSimple::GetDataSize(format)); } | |
390 | bool GetDataHere(const wxDataFormat& format, void* pBuf) const | |
391 | { return(wxDataObjectSimple::GetDataHere(format, pBuf)); } | |
392 | }; | |
393 | ||
394 | // ---------------------------------------------------------------------------- | |
395 | // wxCustomDataObject contains arbitrary untyped user data. | |
396 | // | |
397 | // It is understood that this data can be copied bitwise. | |
398 | // ---------------------------------------------------------------------------- | |
399 | ||
400 | class WXDLLEXPORT wxCustomDataObject : public wxDataObjectSimple | |
401 | { | |
402 | public: | |
403 | // if you don't specify the format in the ctor, you can still use | |
404 | // SetFormat() later | |
405 | wxCustomDataObject(const wxDataFormat& format = wxFormatInvalid); | |
406 | ||
407 | // the dtor calls Free() | |
408 | virtual ~wxCustomDataObject(); | |
409 | ||
410 | // you can call SetData() to set m_data: it will make a copy of the data | |
411 | // you pass - or you can use TakeData() which won't copy anything, but | |
412 | // will take ownership of data (i.e. will call Free() on it later) | |
413 | void TakeData(size_t size, void *data); | |
414 | ||
415 | // this function is called to allocate "size" bytes of memory from | |
416 | // SetData(). The default version uses operator new[]. | |
417 | virtual void *Alloc(size_t size); | |
418 | ||
419 | // this function is called when the data is freed, you may override it to | |
420 | // anything you want (or may be nothing at all). The default version calls | |
421 | // operator delete[] on m_data | |
422 | virtual void Free(); | |
423 | ||
424 | // get data: you may override these functions if you wish to provide data | |
425 | // only when it's requested | |
426 | virtual size_t GetSize() const { return m_size; } | |
427 | virtual void *GetData() const { return m_data; } | |
428 | ||
429 | // implement base class pure virtuals | |
430 | // ---------------------------------- | |
431 | virtual size_t GetDataSize() const; | |
432 | virtual bool GetDataHere(void *buf) const; | |
433 | virtual bool SetData(size_t size, const void *buf); | |
434 | ||
435 | private: | |
436 | size_t m_size; | |
437 | void *m_data; | |
438 | ||
439 | // virtual function hiding supression | |
440 | size_t GetDataSize(const wxDataFormat& format) const | |
441 | { return(wxDataObjectSimple::GetDataSize(format)); } | |
442 | bool GetDataHere(const wxDataFormat& format, void* pBuf) const | |
443 | { return(wxDataObjectSimple::GetDataHere(format, pBuf)); } | |
444 | bool SetData(const wxDataFormat& format, size_t nLen, const void* pBuf) | |
445 | { return(wxDataObjectSimple::SetData(format, nLen, pBuf)); } | |
446 | }; | |
447 | ||
448 | // ---------------------------------------------------------------------------- | |
449 | // include platform-specific declarations of wxXXXBase classes | |
450 | // ---------------------------------------------------------------------------- | |
451 | ||
452 | #if defined(__WXMSW__) | |
453 | #include "wx/msw/ole/dataobj2.h" | |
454 | ||
455 | // wxURLDataObject defined in msw/ole/dataobj2.h | |
456 | #else // !__WXMSW__ | |
457 | #if defined(__WXGTK__) | |
458 | #include "wx/gtk/dataobj2.h" | |
459 | #elif defined(__WXMAC__) | |
460 | #include "wx/mac/dataobj2.h" | |
461 | #elif defined(__WXPM__) | |
462 | #include "wx/os2/dataobj2.h" | |
463 | #endif | |
464 | ||
465 | // wxURLDataObject is simply wxTextDataObject with a different name | |
466 | class WXDLLEXPORT wxURLDataObject : public wxTextDataObject | |
467 | { | |
468 | public: | |
469 | wxString GetURL() const { return GetText(); } | |
470 | void SetURL(const wxString& url) { SetText(url); } | |
471 | }; | |
472 | #endif // __WXMSW__/!__WXMSW__ | |
473 | ||
474 | #endif // _WX_DATAOBJ_H_BASE_ |