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