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