include/wx/dataobj.h

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