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) 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
  52 class wxDataFormat
  53 {
  54 public:
  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)
  95 extern 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
 117 class WXDLLIMPEXP_CORE wxDataObjectBase
 118 {
 119 public:
 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
 197 class WXDLLIMPEXP_CORE wxDataObjectSimple : public wxDataObject
 198 {
 199 public:
 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
 245 private:
 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
 262 WX_DECLARE_EXPORTED_LIST(wxDataObjectSimple, wxSimpleDataObjectList);
 263
 264 class WXDLLIMPEXP_CORE wxDataObjectComposite : public wxDataObject
 265 {
 266 public:
 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
 304 private:
 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
 337 class WXDLLIMPEXP_CORE wxHTMLDataObject : public wxDataObjectSimple
 338 {
 339 public:
 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
 372 private:
 373     wxString m_html;
 374 };
 375
 376 class WXDLLIMPEXP_CORE wxTextDataObject : public wxDataObjectSimple
 377 {
 378 public:
 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
 434 private:
 435     wxString m_text;
 436
 437     wxDECLARE_NO_COPY_CLASS(wxTextDataObject);
 438 };
 439
 440 // ----------------------------------------------------------------------------
 441 // wxBitmapDataObject contains a bitmap
 442 // ----------------------------------------------------------------------------
 443
 444 class WXDLLIMPEXP_CORE wxBitmapDataObjectBase : public wxDataObjectSimple
 445 {
 446 public:
 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
 459 protected:
 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
 472 class WXDLLIMPEXP_CORE wxFileDataObjectBase : public wxDataObjectSimple
 473 {
 474 public:
 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
 481 protected:
 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
 493 class WXDLLIMPEXP_CORE wxCustomDataObject : public wxDataObjectSimple
 494 {
 495 public:
 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
 541 private:
 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_