]> git.saurik.com Git - wxWidgets.git/blame_incremental - include/wx/dataobj.h
#ifdefed out the joystick code, and removed the wxBitmapList addition
[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) 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
53class wxDataFormat
54{
55public:
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)
90extern 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
112class WXDLLEXPORT wxDataObjectBase
113{
114public:
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
188class WXDLLEXPORT wxDataObjectSimple : public wxDataObject
189{
190public:
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
236private:
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
251WX_DECLARE_EXPORTED_LIST(wxDataObjectSimple, wxSimpleDataObjectList);
252
253class WXDLLEXPORT wxDataObjectComposite : public wxDataObject
254{
255public:
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
273protected:
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
284private:
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
305class WXDLLEXPORT wxTextDataObject : public wxDataObjectSimple
306{
307public:
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
328private:
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
344class WXDLLEXPORT wxBitmapDataObjectBase : public wxDataObjectSimple
345{
346public:
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
359protected:
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
370class WXDLLEXPORT wxFileDataObjectBase : public wxDataObjectSimple
371{
372public:
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
383protected:
384 wxArrayString m_filenames;
385
386private:
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
400class WXDLLEXPORT wxCustomDataObject : public wxDataObjectSimple
401{
402public:
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
435private:
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_