include/wx/dataobj.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/dataobj.h
   3 // Purpose:     common data object classes
   4 // Author:      Vadim Zeitlin, Robert Roebling
   5 // Modified by:
   6 // Created:     26.05.99
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) wxWindows Team
   9 // Licence:     wxWindows license
  10 ///////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_DATAOBJ_H_BASE_
  13 #define _WX_DATAOBJ_H_BASE_
  14
  15 #ifdef __GNUG__
  16     #pragma interface "dataobjbase.h"
  17 #endif
  18
  19 // ----------------------------------------------------------------------------
  20 // headers
  21 // ----------------------------------------------------------------------------
  22
  23 #include "wx/defs.h"
  24 #include "wx/string.h"
  25 #include "wx/bitmap.h"
  26 #include "wx/list.h"
  27
  28 // ============================================================================
  29 /*
  30    Generic data transfer related classes. The class hierarchy is as follows:
  31
  32                                 - wxDataObject-
  33                                /               \
  34                               /                 \
  35             wxDataObjectSimple                  wxDataObjectComposite
  36            /           |      \
  37           /            |       \
  38    wxTextDataObject    |     wxBitmapDataObject
  39                        |
  40                wxCustomDataObject
  41
  42 */
  43 // ============================================================================
  44
  45 // ----------------------------------------------------------------------------
  46 // wxDataFormat class is declared in platform-specific headers: it represents
  47 // a format for data which may be either one of the standard ones (text,
  48 // bitmap, ...) or a custom one which is then identified by a unique string.
  49 // ----------------------------------------------------------------------------
  50
  51 /* the class interface looks like this (pseudo code):
  52
  53 class wxDataFormat
  54 {
  55 public:
  56     typedef <integral type> NativeFormat;
  57
  58     wxDataFormat(NativeFormat format = wxDF_INVALID);
  59     wxDataFormat(const wxChar *format);
  60
  61     wxDataFormat& operator=(NativeFormat format);
  62     wxDataFormat& operator=(const wxDataFormat& format);
  63
  64     bool operator==(NativeFormat format) const;
  65     bool operator!=(NativeFormat format) const;
  66
  67     void SetType(NativeFormat format);
  68     NativeFormat GetType() const;
  69
  70     wxString GetId() const;
  71     void SetId(const wxChar *format);
  72 };
  73
  74 */
  75
  76 #if defined(__WXMSW__)
  77     #include "wx/msw/ole/dataform.h"
  78 #elif defined(__WXMOTIF__)
  79     #include "wx/motif/dataform.h"
  80 #elif defined(__WXGTK__)
  81     #include "wx/gtk/dataform.h"
  82 #endif
  83
  84 // ----------------------------------------------------------------------------
  85 // wxDataObject represents a piece of data which knows which formats it
  86 // supports and knows how to render itself in each of them - GetDataHere(),
  87 // and how to restore data from the buffer (SetData()).
  88 //
  89 // Although this class may be used directly (i.e. custom classes may be
  90 // derived from it), in many cases it might be simpler to use either
  91 // wxDataObjectSimple or wxDataObjectComposite classes.
  92 //
  93 // A data object may be "read only", i.e. support only GetData() functions or
  94 // "read-write", i.e. support both GetData() and SetData() (in principle, it
  95 // might be "write only" too, but this is rare). Moreover, it doesn't have to
  96 // support the same formats in Get() and Set() directions: for example, a data
  97 // object containing JPEG image might accept BMPs in GetData() because JPEG
  98 // image may be easily transformed into BMP but not in SetData(). Accordingly,
  99 // all methods dealing with formats take an additional "direction" argument
 100 // which is either SET or GET and which tells the function if the format needs
 101 // to be supported by SetData() or GetDataHere().
 102 // ----------------------------------------------------------------------------
 103
 104 class WXDLLEXPORT wxDataObjectBase
 105 {
 106 public:
 107     enum Direction
 108     {
 109         Get  = 0x01,    // format is supported by GetDataHere()
 110         Set  = 0x02,    // format is supported by SetData()
 111         Both = 0x03     // format is supported by both (unused currently)
 112     };
 113
 114     // this class is polymorphic, hence it needs a virtual dtor
 115     virtual ~wxDataObjectBase();
 116
 117     // get the best suited format for rendering our data
 118     virtual wxDataFormat GetPreferredFormat(Direction dir = Get) const = 0;
 119
 120     // get the number of formats we support
 121     virtual size_t GetFormatCount(Direction dir = Get) const = 0;
 122
 123     // return all formats in the provided array (of size GetFormatCount())
 124     virtual void GetAllFormats(wxDataFormat *formats,
 125                                Direction dir = Get) const = 0;
 126
 127     // get the (total) size of data for the given format
 128     virtual size_t GetDataSize(const wxDataFormat& format) const = 0;
 129
 130     // copy raw data (in the specified format) to the provided buffer, return
 131     // TRUE if data copied successfully, FALSE otherwise
 132     virtual bool GetDataHere(const wxDataFormat& format, void *buf) const = 0;
 133
 134     // get data from the buffer of specified length (in the given format),
 135     // return TRUE if the data was read successfully, FALSE otherwise
 136     virtual bool SetData(const wxDataFormat& format,
 137                          size_t len, const void *buf) = 0;
 138 };
 139
 140 // ----------------------------------------------------------------------------
 141 // include the platform-specific declarations of wxDataObject
 142 // ----------------------------------------------------------------------------
 143
 144 #if defined(__WXMSW__)
 145     #include "wx/msw/ole/dataobj.h"
 146 #elif defined(__WXMOTIF__)
 147     #include "wx/motif/dataobj.h"
 148 #elif defined(__WXGTK__)
 149     #include "wx/gtk/dataobj.h"
 150 #elif defined(__WXQT__)
 151     #include "wx/qt/dnd.h"
 152 #elif defined(__WXMAC__)
 153     #include "wx/mac/dnd.h"
 154 #elif defined(__WXPM__)
 155     #include "wx/os2/dnd.h"
 156 #elif defined(__WXSTUBS__)
 157     #include "wx/stubs/dnd.h"
 158 #endif
 159
 160 // ----------------------------------------------------------------------------
 161 // wxDataObjectSimple is a wxDataObject which only supports one format (in
 162 // both Get and Set directions, but you may return FALSE from GetDataHere() or
 163 // SetData() if one of them is not supported). This is the simplest possible
 164 // wxDataObject implementation.
 165 //
 166 // This is still an "abstract base class" (although it doesn't have any pure
 167 // virtual functions), to use it you should derive from it and implement
 168 // GetDataSize(), GetDataHere() and SetData() functions because the base class
 169 // versions don't do anything - they just return "not implemented".
 170 //
 171 // This class should be used when you provide data in only one format (no
 172 // conversion to/from other formats), either a standard or a custom one.
 173 // Otherwise, you should use wxDataObjectComposite or wxDataObject directly.
 174 // ----------------------------------------------------------------------------
 175
 176 class WXDLLEXPORT wxDataObjectSimple : public wxDataObject
 177 {
 178 public:
 179     // ctor takes the format we support, but it can also be set later with
 180     // SetFormat()
 181     wxDataObjectSimple(const wxDataFormat& format = wxDF_INVALID)
 182         : m_format(format)
 183         {
 184         }
 185
 186     // get/set the format we support
 187     const wxDataFormat& GetFormat() const { return m_format; }
 188     void SetFormat(const wxDataFormat& format) { m_format = format; }
 189
 190     // virtual functions to override in derived class (the base class versions
 191     // just return "not implemented")
 192     // -----------------------------------------------------------------------
 193
 194     // get the size of our data
 195     virtual size_t GetDataSize() const
 196         { return 0; }
 197
 198     // copy our data to the buffer
 199     virtual bool GetDataHere(void *WXUNUSED(buf)) const
 200         { return FALSE; }
 201
 202     // copy data from buffer to our data
 203     virtual bool SetData(size_t len, const void *WXUNUSED(buf))
 204         { return FALSE; }
 205
 206     // implement base class pure virtuals
 207     // ----------------------------------
 208     virtual wxDataFormat GetPreferredFormat(Direction WXUNUSED(dir) = Get) const
 209         { return m_format; }
 210     virtual size_t GetFormatCount(Direction WXUNUSED(dir) = Get) const
 211         { return 1; }
 212     virtual void GetAllFormats(wxDataFormat *formats,
 213                                Direction WXUNUSED(dir) = Get) const
 214         { *formats = m_format; }
 215     virtual size_t GetDataSize(const wxDataFormat& WXUNUSED(format)) const
 216         { return GetDataSize(); }
 217     virtual bool GetDataHere(const wxDataFormat& WXUNUSED(format),
 218                              void *buf) const
 219         { return GetDataHere(buf); }
 220     virtual bool SetData(const wxDataFormat& WXUNUSED(format),
 221                          size_t len, const void *buf)
 222         { return SetData(len, buf); }
 223
 224 private:
 225     // the one and only format we support
 226     wxDataFormat m_format;
 227 };
 228
 229 // ----------------------------------------------------------------------------
 230 // wxDataObjectComposite is the simplest way to implement wxDataObject
 231 // supporting multiple formats. It contains several wxDataObjectSimple and
 232 // supports all formats supported by any of them.
 233 //
 234 // This class shouldn't be (normally) derived from, but may be used directly.
 235 // If you need more flexibility than what it provides, you should probably use
 236 // wxDataObject directly.
 237 // ----------------------------------------------------------------------------
 238
 239 WX_DECLARE_LIST(wxDataObjectSimple, wxSimpleDataObjectList);
 240
 241 class WXDLLEXPORT wxDataObjectComposite : public wxDataObject
 242 {
 243 public:
 244     // ctor
 245     wxDataObjectComposite() { m_preferred = 0; }
 246
 247     // add data object (it will be deleted by wxDataObjectComposite, hence it
 248     // must be allocated on the heap) whose format will become the preferred
 249     // one if preferred == TRUE
 250     void Add(wxDataObjectSimple *dataObject, bool preferred = FALSE);
 251
 252     // implement base class pure virtuals
 253     // ----------------------------------
 254     virtual wxDataFormat GetPreferredFormat(Direction dir = Get) const;
 255     virtual size_t GetFormatCount(Direction dir = Get) const;
 256     virtual void GetAllFormats(wxDataFormat *formats, Direction dir = Get) const;
 257     virtual size_t GetDataSize(const wxDataFormat& format) const;
 258     virtual bool GetDataHere(const wxDataFormat& format, void *buf) const;
 259     virtual bool SetData(const wxDataFormat& format, size_t len, const void *buf);
 260
 261 protected:
 262     // returns the pointer to the object which supports this format or NULL
 263     wxDataObjectSimple *GetObject(const wxDataFormat& format) const;
 264
 265 private:
 266     // the list of all (simple) data objects whose formats we support
 267     wxSimpleDataObjectList m_dataObjects;
 268
 269     // the index of the preferred one (0 initially, so by default the first
 270     // one is the preferred)
 271     size_t m_preferred;
 272 };
 273
 274 // ============================================================================
 275 // Standard implementations of wxDataObjectSimple which can be used directly
 276 // (i.e. without having to derive from them) for standard data type transfers.
 277 //
 278 // Note that although all of them can work with provided data, you can also
 279 // override their virtual GetXXX() functions to only provide data on demand.
 280 // ============================================================================
 281
 282 // ----------------------------------------------------------------------------
 283 // wxTextDataObject contains text data
 284 // ----------------------------------------------------------------------------
 285
 286 class WXDLLEXPORT wxTextDataObject : public wxDataObjectSimple
 287 {
 288 public:
 289     // ctor: you can specify the text here or in SetText(), or override
 290     // GetText()
 291     wxTextDataObject(const wxString& text = wxEmptyString)
 292         : wxDataObjectSimple(wxDF_TEXT), m_text(text)
 293         {
 294         }
 295
 296     // virtual functions which you may override if you want to provide text on
 297     // demand only - otherwise, the trivial default versions will be used
 298     virtual size_t GetTextLength() const { return m_text.Len() + 1; }
 299     virtual wxString GetText() const { return m_text; }
 300     virtual void SetText(const wxString& text) { m_text = text; }
 301
 302     // implement base class pure virtuals
 303     // ----------------------------------
 304     virtual size_t GetDataSize() const;
 305     virtual bool GetDataHere(void *buf) const;
 306     virtual bool SetData(size_t len, const void *buf);
 307
 308 private:
 309     wxString m_text;
 310 };
 311
 312 // ----------------------------------------------------------------------------
 313 // wxBitmapDataObject contains a bitmap
 314 // ----------------------------------------------------------------------------
 315
 316 class WXDLLEXPORT wxBitmapDataObjectBase : public wxDataObjectSimple
 317 {
 318 public:
 319     // ctor: you can specify the bitmap here or in SetBitmap(), or override
 320     // GetBitmap()
 321     wxBitmapDataObjectBase(const wxBitmap& bitmap = wxNullBitmap)
 322         : wxDataObjectSimple(wxDF_BITMAP), m_bitmap(bitmap)
 323         {
 324         }
 325
 326     // virtual functions which you may override if you want to provide data on
 327     // demand only - otherwise, the trivial default versions will be used
 328     virtual wxBitmap GetBitmap() const { return m_bitmap; }
 329     virtual void SetBitmap(const wxBitmap& bitmap) { m_bitmap = bitmap; }
 330
 331 private:
 332     wxBitmap m_bitmap;
 333 };
 334
 335 // ----------------------------------------------------------------------------
 336 // wxFileDataObject contains a list of filenames
 337 // ----------------------------------------------------------------------------
 338
 339 class WXDLLEXPORT wxFileDataObjectBase : public wxDataObjectSimple
 340 {
 341 public:
 342     // ctor: you can specify the bitmap here or in SetBitmap(), or override
 343     // GetBitmap()
 344     wxFileDataObjectBase() : wxDataObjectSimple(wxDF_FILENAME) { }
 345
 346     // get a reference to our array - you may modify it (i.e. add/remove
 347     // filenames to it then)
 348     wxArrayString& GetFilenames() { return m_filenames; }
 349
 350     // a helper function
 351     void AddFile(const wxString& filename) { m_filenames.Add(filename); }
 352
 353     // virtual functions which you may override if you want to provide data on
 354     // demand only - otherwise, the trivial default versions will be used.
 355     //
 356     // they work with a NUL-separated string of filenames, the base class
 357     // versions concatenate/extract filenames from this string
 358     virtual wxString GetFilenames() const;
 359     virtual void SetFilenames(const wxChar* filenames);
 360
 361 private:
 362     wxArrayString m_filenames;
 363 };
 364
 365 // ----------------------------------------------------------------------------
 366 // wxCustomDataObject contains arbitrary untyped user data.
 367 //
 368 // It is understood that this data can be copied bitwise.
 369 // ----------------------------------------------------------------------------
 370
 371 class WXDLLEXPORT wxCustomDataObject : public wxDataObjectSimple
 372 {
 373 public:
 374     // if you don't specify the format in the ctor, you can still use
 375     // SetFormat() later
 376     wxCustomDataObject(const wxDataFormat& format = wxDF_INVALID);
 377
 378     // the dtor calls Free()
 379     virtual ~wxCustomDataObject();
 380
 381     // you can call SetData() to set m_data: it will make a copy of the data
 382     // you pass - or you can use TakeData() which won't copy anything, but
 383     // will take ownership of data (i.e. will call Free() on it later)
 384     void TakeData(size_t size, void *data);
 385
 386     // this function is called to allocate "size" bytes of memory from
 387     // SetData(). The default version uses operator new[].
 388     virtual void *Alloc(size_t size);
 389
 390     // this function is called when the data is freed, you may override it to
 391     // anything you want (or may be nothing at all). The default version calls
 392     // operator delete[] on m_data
 393     virtual void Free();
 394
 395     // get data: you may override these functions if you wish to provide data
 396     // only when it's requested
 397     virtual size_t GetSize() const { return m_size; }
 398     virtual void *GetData() const { return m_data; }
 399
 400     // implement base class pure virtuals
 401     // ----------------------------------
 402     virtual size_t GetDataSize() const;
 403     virtual bool GetDataHere(void *buf) const;
 404     virtual bool SetData(size_t size, const void *buf);
 405
 406 private:
 407     size_t m_size;
 408     void  *m_data;
 409 };
 410
 411 // ----------------------------------------------------------------------------
 412 // include platform-specific declarations of wxXXXBase classes
 413 // ----------------------------------------------------------------------------
 414
 415 #if defined(__WXMSW__)
 416     #include "wx/msw/ole/dataobj2.h"
 417 #elif defined(__WXMOTIF__)
 418     #include "wx/motif/dataobj2.h"
 419 #elif defined(__WXGTK__)
 420     #include "wx/gtk/dataobj2.h"
 421 #endif
 422
 423 #endif // _WX_DATAOBJ_H_BASE_