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 licence
  10 ///////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_DATAOBJ_H_BASE_
  13 #define _WX_DATAOBJ_H_BASE_
  14
  15 #if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)
  16     #pragma interface "dataobjbase.h"
  17 #endif
  18
  19 // ----------------------------------------------------------------------------
  20 // headers
  21 // ----------------------------------------------------------------------------
  22 #include "wx/defs.h"
  23
  24 #if wxUSE_DATAOBJ
  25
  26 #include "wx/string.h"
  27 #include "wx/bitmap.h"
  28 #include "wx/list.h"
  29 #include "wx/arrstr.h"
  30
  31 // ============================================================================
  32 /*
  33    Generic data transfer related classes. The class hierarchy is as follows:
  34
  35                                 - wxDataObject-
  36                                /               \
  37                               /                 \
  38             wxDataObjectSimple                  wxDataObjectComposite
  39            /           |      \
  40           /            |       \
  41    wxTextDataObject    |     wxBitmapDataObject
  42                        |
  43                wxCustomDataObject
  44
  45 */
  46 // ============================================================================
  47
  48 // ----------------------------------------------------------------------------
  49 // wxDataFormat class is declared in platform-specific headers: it represents
  50 // a format for data which may be either one of the standard ones (text,
  51 // bitmap, ...) or a custom one which is then identified by a unique string.
  52 // ----------------------------------------------------------------------------
  53
  54 /* the class interface looks like this (pseudo code):
  55
  56 class wxDataFormat
  57 {
  58 public:
  59     typedef <integral type> NativeFormat;
  60
  61     wxDataFormat(NativeFormat format = wxDF_INVALID);
  62     wxDataFormat(const wxChar *format);
  63
  64     wxDataFormat& operator=(NativeFormat format);
  65     wxDataFormat& operator=(const wxDataFormat& format);
  66
  67     bool operator==(NativeFormat format) const;
  68     bool operator!=(NativeFormat format) const;
  69
  70     void SetType(NativeFormat format);
  71     NativeFormat GetType() const;
  72
  73     wxString GetId() const;
  74     void SetId(const wxChar *format);
  75 };
  76
  77 */
  78
  79 #if defined(__WXMSW__)
  80     #include "wx/msw/ole/dataform.h"
  81 #elif defined(__WXMOTIF__)
  82     #include "wx/motif/dataform.h"
  83 #elif defined(__WXGTK__)
  84     #include "wx/gtk/dataform.h"
  85 #elif defined(__WXX11__)
  86     #include "wx/x11/dataform.h"
  87 #elif defined(__WXMAC__)
  88     #include "wx/mac/dataform.h"
  89 #elif defined(__WXCOCOA__)
  90     #include "wx/cocoa/dataform.h"
  91 #elif defined(__WXPM__)
  92     #include "wx/os2/dataform.h"
  93 #endif
  94
  95 // the value for default argument to some functions (corresponds to
  96 // wxDF_INVALID)
  97 extern WXDLLEXPORT const wxDataFormat& wxFormatInvalid;
  98
  99 // ----------------------------------------------------------------------------
 100 // wxDataObject represents a piece of data which knows which formats it
 101 // supports and knows how to render itself in each of them - GetDataHere(),
 102 // and how to restore data from the buffer (SetData()).
 103 //
 104 // Although this class may be used directly (i.e. custom classes may be
 105 // derived from it), in many cases it might be simpler to use either
 106 // wxDataObjectSimple or wxDataObjectComposite classes.
 107 //
 108 // A data object may be "read only", i.e. support only GetData() functions or
 109 // "read-write", i.e. support both GetData() and SetData() (in principle, it
 110 // might be "write only" too, but this is rare). Moreover, it doesn't have to
 111 // support the same formats in Get() and Set() directions: for example, a data
 112 // object containing JPEG image might accept BMPs in GetData() because JPEG
 113 // image may be easily transformed into BMP but not in SetData(). Accordingly,
 114 // all methods dealing with formats take an additional "direction" argument
 115 // which is either SET or GET and which tells the function if the format needs
 116 // to be supported by SetData() or GetDataHere().
 117 // ----------------------------------------------------------------------------
 118
 119 class WXDLLEXPORT wxDataObjectBase
 120 {
 121 public:
 122     enum Direction
 123     {
 124         Get  = 0x01,    // format is supported by GetDataHere()
 125         Set  = 0x02,    // format is supported by SetData()
 126         Both = 0x03     // format is supported by both (unused currently)
 127     };
 128
 129     // this class is polymorphic, hence it needs a virtual dtor
 130     virtual ~wxDataObjectBase();
 131
 132     // get the best suited format for rendering our data
 133     virtual wxDataFormat GetPreferredFormat(Direction dir = Get) const = 0;
 134
 135     // get the number of formats we support
 136     virtual size_t GetFormatCount(Direction dir = Get) const = 0;
 137
 138     // return all formats in the provided array (of size GetFormatCount())
 139     virtual void GetAllFormats(wxDataFormat *formats,
 140                                Direction dir = Get) const = 0;
 141
 142     // get the (total) size of data for the given format
 143     virtual size_t GetDataSize(const wxDataFormat& format) const = 0;
 144
 145     // copy raw data (in the specified format) to the provided buffer, return
 146     // TRUE if data copied successfully, FALSE otherwise
 147     virtual bool GetDataHere(const wxDataFormat& format, void *buf) const = 0;
 148
 149     // get data from the buffer of specified length (in the given format),
 150     // return TRUE if the data was read successfully, FALSE otherwise
 151     virtual bool SetData(const wxDataFormat& WXUNUSED(format),
 152                          size_t WXUNUSED(len), const void * WXUNUSED(buf))
 153     {
 154         return FALSE;
 155     }
 156
 157     // returns TRUE if this format is supported
 158     bool IsSupported(const wxDataFormat& format, Direction dir = Get) const;
 159 };
 160
 161 // ----------------------------------------------------------------------------
 162 // include the platform-specific declarations of wxDataObject
 163 // ----------------------------------------------------------------------------
 164
 165 #if defined(__WXMSW__)
 166     #include "wx/msw/ole/dataobj.h"
 167 #elif defined(__WXMOTIF__)
 168     #include "wx/motif/dataobj.h"
 169 #elif defined(__WXX11__)
 170     #include "wx/x11/dataobj.h"
 171 #elif defined(__WXGTK__)
 172     #include "wx/gtk/dataobj.h"
 173 #elif defined(__WXMAC__)
 174     #include "wx/mac/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 WXDLLEXPORT 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     DECLARE_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 WXDLLEXPORT 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     // implement base class pure virtuals
 277     // ----------------------------------
 278     virtual wxDataFormat GetPreferredFormat(wxDataObjectBase::Direction dir = Get) const;
 279     virtual size_t GetFormatCount(wxDataObjectBase::Direction dir = Get) const;
 280     virtual void GetAllFormats(wxDataFormat *formats, wxDataObjectBase::Direction dir = Get) const;
 281     virtual size_t GetDataSize(const wxDataFormat& format) const;
 282     virtual bool GetDataHere(const wxDataFormat& format, void *buf) const;
 283     virtual bool SetData(const wxDataFormat& format, size_t len, const void *buf);
 284
 285 protected:
 286     // returns the pointer to the object which supports this format or NULL
 287     wxDataObjectSimple *GetObject(const wxDataFormat& format) const;
 288 #if defined(__WXMSW__)
 289     virtual const void* GetSizeFromBuffer( const void* buffer, size_t* size,
 290                                            const wxDataFormat& format );
 291     virtual void* SetSizeInBuffer( void* buffer, size_t size,
 292                                    const wxDataFormat& format );
 293     virtual size_t GetBufferOffset( const wxDataFormat& format );
 294 #endif
 295
 296 private:
 297     // the list of all (simple) data objects whose formats we support
 298     wxSimpleDataObjectList m_dataObjects;
 299
 300     // the index of the preferred one (0 initially, so by default the first
 301     // one is the preferred)
 302     size_t m_preferred;
 303
 304     DECLARE_NO_COPY_CLASS(wxDataObjectComposite)
 305 };
 306
 307 // ============================================================================
 308 // Standard implementations of wxDataObjectSimple which can be used directly
 309 // (i.e. without having to derive from them) for standard data type transfers.
 310 //
 311 // Note that although all of them can work with provided data, you can also
 312 // override their virtual GetXXX() functions to only provide data on demand.
 313 // ============================================================================
 314
 315 // ----------------------------------------------------------------------------
 316 // wxTextDataObject contains text data
 317 // ----------------------------------------------------------------------------
 318
 319 class WXDLLEXPORT wxTextDataObject : public wxDataObjectSimple
 320 {
 321 public:
 322     // ctor: you can specify the text here or in SetText(), or override
 323     // GetText()
 324     wxTextDataObject(const wxString& text = wxEmptyString)
 325         : wxDataObjectSimple(wxUSE_UNICODE?wxDF_UNICODETEXT:wxDF_TEXT),
 326           m_text(text)
 327         {
 328         }
 329
 330     // virtual functions which you may override if you want to provide text on
 331     // demand only - otherwise, the trivial default versions will be used
 332     virtual size_t GetTextLength() const { return m_text.Len() + 1; }
 333     virtual wxString GetText() const { return m_text; }
 334     virtual void SetText(const wxString& text) { m_text = text; }
 335
 336     // implement base class pure virtuals
 337     // ----------------------------------
 338     virtual size_t GetDataSize() const;
 339     virtual bool GetDataHere(void *buf) const;
 340     virtual bool SetData(size_t len, const void *buf);
 341
 342 private:
 343     wxString m_text;
 344
 345     // virtual function hiding supression
 346     size_t GetDataSize(const wxDataFormat& format) const
 347         { return(wxDataObjectSimple::GetDataSize(format)); }
 348     bool GetDataHere(const wxDataFormat& format, void *pBuf) const
 349         { return(wxDataObjectSimple::GetDataHere(format, pBuf)); }
 350     bool SetData(const wxDataFormat& format, size_t nLen, const void* pBuf)
 351         { return(wxDataObjectSimple::SetData(format, nLen, pBuf)); }
 352
 353     DECLARE_NO_COPY_CLASS(wxTextDataObject)
 354 };
 355
 356 // ----------------------------------------------------------------------------
 357 // wxBitmapDataObject contains a bitmap
 358 // ----------------------------------------------------------------------------
 359
 360 class WXDLLEXPORT wxBitmapDataObjectBase : public wxDataObjectSimple
 361 {
 362 public:
 363     // ctor: you can specify the bitmap here or in SetBitmap(), or override
 364     // GetBitmap()
 365     wxBitmapDataObjectBase(const wxBitmap& bitmap = wxNullBitmap)
 366         : wxDataObjectSimple(wxDF_BITMAP), m_bitmap(bitmap)
 367         {
 368         }
 369
 370     // virtual functions which you may override if you want to provide data on
 371     // demand only - otherwise, the trivial default versions will be used
 372     virtual wxBitmap GetBitmap() const { return m_bitmap; }
 373     virtual void SetBitmap(const wxBitmap& bitmap) { m_bitmap = bitmap; }
 374
 375 protected:
 376     wxBitmap m_bitmap;
 377
 378     DECLARE_NO_COPY_CLASS(wxBitmapDataObjectBase)
 379 };
 380
 381 // ----------------------------------------------------------------------------
 382 // wxFileDataObject contains a list of filenames
 383 //
 384 // NB: notice that this is a "write only" object, it can only be filled with
 385 //     data from drag and drop operation.
 386 // ----------------------------------------------------------------------------
 387
 388 class WXDLLEXPORT wxFileDataObjectBase : public wxDataObjectSimple
 389 {
 390 public:
 391     // ctor: use AddFile() later to fill the array
 392     wxFileDataObjectBase() : wxDataObjectSimple(wxDF_FILENAME) { }
 393
 394     // get a reference to our array
 395     const wxArrayString& GetFilenames() const { return m_filenames; }
 396
 397     // the Get() functions do nothing for us
 398     virtual size_t GetDataSize() const { return 0; }
 399     virtual bool GetDataHere(void *WXUNUSED(buf)) const { return FALSE; }
 400
 401 protected:
 402     wxArrayString m_filenames;
 403
 404 private:
 405     // Virtual function hiding supression
 406     size_t GetDataSize(const wxDataFormat& format) const
 407         { return(wxDataObjectSimple::GetDataSize(format)); }
 408     bool GetDataHere(const wxDataFormat& format, void* pBuf) const
 409         { return(wxDataObjectSimple::GetDataHere(format, pBuf)); }
 410
 411     DECLARE_NO_COPY_CLASS(wxFileDataObjectBase)
 412 };
 413
 414 // ----------------------------------------------------------------------------
 415 // wxCustomDataObject contains arbitrary untyped user data.
 416 //
 417 // It is understood that this data can be copied bitwise.
 418 // ----------------------------------------------------------------------------
 419
 420 class WXDLLEXPORT wxCustomDataObject : public wxDataObjectSimple
 421 {
 422 public:
 423     // if you don't specify the format in the ctor, you can still use
 424     // SetFormat() later
 425     wxCustomDataObject(const wxDataFormat& format = wxFormatInvalid);
 426
 427     // the dtor calls Free()
 428     virtual ~wxCustomDataObject();
 429
 430     // you can call SetData() to set m_data: it will make a copy of the data
 431     // you pass - or you can use TakeData() which won't copy anything, but
 432     // will take ownership of data (i.e. will call Free() on it later)
 433     void TakeData(size_t size, void *data);
 434
 435     // this function is called to allocate "size" bytes of memory from
 436     // SetData(). The default version uses operator new[].
 437     virtual void *Alloc(size_t size);
 438
 439     // this function is called when the data is freed, you may override it to
 440     // anything you want (or may be nothing at all). The default version calls
 441     // operator delete[] on m_data
 442     virtual void Free();
 443
 444     // get data: you may override these functions if you wish to provide data
 445     // only when it's requested
 446     virtual size_t GetSize() const { return m_size; }
 447     virtual void *GetData() const { return m_data; }
 448
 449     // implement base class pure virtuals
 450     // ----------------------------------
 451     virtual size_t GetDataSize() const;
 452     virtual bool GetDataHere(void *buf) const;
 453     virtual bool SetData(size_t size, const void *buf);
 454
 455 private:
 456     size_t m_size;
 457     void  *m_data;
 458
 459     // virtual function hiding supression
 460     size_t GetDataSize(const wxDataFormat& format) const
 461         { return(wxDataObjectSimple::GetDataSize(format)); }
 462     bool GetDataHere(const wxDataFormat& format, void* pBuf) const
 463         { return(wxDataObjectSimple::GetDataHere(format, pBuf)); }
 464     bool SetData(const wxDataFormat& format, size_t nLen, const void* pBuf)
 465         { return(wxDataObjectSimple::SetData(format, nLen, pBuf)); }
 466
 467     DECLARE_NO_COPY_CLASS(wxCustomDataObject)
 468 };
 469
 470 // ----------------------------------------------------------------------------
 471 // include platform-specific declarations of wxXXXBase classes
 472 // ----------------------------------------------------------------------------
 473
 474 #if defined(__WXMSW__)
 475     #include "wx/msw/ole/dataobj2.h"
 476
 477     // wxURLDataObject defined in msw/ole/dataobj2.h
 478 #else // !__WXMSW__
 479     #if defined(__WXGTK__)
 480         #include "wx/gtk/dataobj2.h"
 481     #elif defined(__WXX11__)
 482         #include "wx/x11/dataobj2.h"
 483     #elif defined(__WXMOTIF__)
 484         #include "wx/motif/dataobj2.h"
 485     #elif defined(__WXMAC__)
 486         #include "wx/mac/dataobj2.h"
 487     #elif defined(__WXCOCOA__)
 488         #include "wx/cocoa/dataobj2.h"
 489     #elif defined(__WXPM__)
 490         #include "wx/os2/dataobj2.h"
 491     #endif
 492
 493     // wxURLDataObject is simply wxTextDataObject with a different name
 494     class WXDLLEXPORT wxURLDataObject : public wxTextDataObject
 495     {
 496     public:
 497         wxString GetURL() const { return GetText(); }
 498         void SetURL(const wxString& url) { SetText(url); }
 499     };
 500 #endif // __WXMSW__/!__WXMSW__
 501
 502 #endif // wxUSE_DATAOBJ
 503
 504 #endif // _WX_DATAOBJ_H_BASE_