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