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& WXUNUSED(format),
 137                          size_t WXUNUSED(len), const void * WXUNUSED(buf))
 138     {
 139         return FALSE;
 140     }
 141 };
 142
 143 // ----------------------------------------------------------------------------
 144 // include the platform-specific declarations of wxDataObject
 145 // ----------------------------------------------------------------------------
 146
 147 #if defined(__WXMSW__)
 148     #include "wx/msw/ole/dataobj.h"
 149 #elif defined(__WXMOTIF__)
 150     #include "wx/motif/dataobj.h"
 151 #elif defined(__WXGTK__)
 152     #include "wx/gtk/dataobj.h"
 153 #elif defined(__WXQT__)
 154     #include "wx/qt/dnd.h"
 155 #elif defined(__WXMAC__)
 156     #include "wx/mac/dnd.h"
 157 #elif defined(__WXPM__)
 158     #include "wx/os2/dnd.h"
 159 #elif defined(__WXSTUBS__)
 160     #include "wx/stubs/dnd.h"
 161 #endif
 162
 163 // ----------------------------------------------------------------------------
 164 // wxDataObjectSimple is a wxDataObject which only supports one format (in
 165 // both Get and Set directions, but you may return FALSE from GetDataHere() or
 166 // SetData() if one of them is not supported). This is the simplest possible
 167 // wxDataObject implementation.
 168 //
 169 // This is still an "abstract base class" (although it doesn't have any pure
 170 // virtual functions), to use it you should derive from it and implement
 171 // GetDataSize(), GetDataHere() and SetData() functions because the base class
 172 // versions don't do anything - they just return "not implemented".
 173 //
 174 // This class should be used when you provide data in only one format (no
 175 // conversion to/from other formats), either a standard or a custom one.
 176 // Otherwise, you should use wxDataObjectComposite or wxDataObject directly.
 177 // ----------------------------------------------------------------------------
 178
 179 class WXDLLEXPORT wxDataObjectSimple : public wxDataObject
 180 {
 181 public:
 182     // ctor takes the format we support, but it can also be set later with
 183     // SetFormat()
 184     wxDataObjectSimple(const wxDataFormat& format = wxDF_INVALID)
 185         : m_format(format)
 186         {
 187         }
 188
 189     // get/set the format we support
 190     const wxDataFormat& GetFormat() const { return m_format; }
 191     void SetFormat(const wxDataFormat& format) { m_format = format; }
 192
 193     // virtual functions to override in derived class (the base class versions
 194     // just return "not implemented")
 195     // -----------------------------------------------------------------------
 196
 197     // get the size of our data
 198     virtual size_t GetDataSize() const
 199         { return 0; }
 200
 201     // copy our data to the buffer
 202     virtual bool GetDataHere(void *WXUNUSED(buf)) const
 203         { return FALSE; }
 204
 205     // copy data from buffer to our data
 206     virtual bool SetData(size_t len, const void *WXUNUSED(buf))
 207         { return FALSE; }
 208
 209     // implement base class pure virtuals
 210     // ----------------------------------
 211     virtual wxDataFormat GetPreferredFormat(Direction WXUNUSED(dir) = Get) const
 212         { return m_format; }
 213     virtual size_t GetFormatCount(Direction WXUNUSED(dir) = Get) const
 214         { return 1; }
 215     virtual void GetAllFormats(wxDataFormat *formats,
 216                                Direction WXUNUSED(dir) = Get) const
 217         { *formats = m_format; }
 218     virtual size_t GetDataSize(const wxDataFormat& WXUNUSED(format)) const
 219         { return GetDataSize(); }
 220     virtual bool GetDataHere(const wxDataFormat& WXUNUSED(format),
 221                              void *buf) const
 222         { return GetDataHere(buf); }
 223     virtual bool SetData(const wxDataFormat& WXUNUSED(format),
 224                          size_t len, const void *buf)
 225         { return SetData(len, buf); }
 226
 227 private:
 228     // the one and only format we support
 229     wxDataFormat m_format;
 230 };
 231
 232 // ----------------------------------------------------------------------------
 233 // wxDataObjectComposite is the simplest way to implement wxDataObject
 234 // supporting multiple formats. It contains several wxDataObjectSimple and
 235 // supports all formats supported by any of them.
 236 //
 237 // This class shouldn't be (normally) derived from, but may be used directly.
 238 // If you need more flexibility than what it provides, you should probably use
 239 // wxDataObject directly.
 240 // ----------------------------------------------------------------------------
 241
 242 WX_DECLARE_LIST(wxDataObjectSimple, wxSimpleDataObjectList);
 243
 244 class WXDLLEXPORT wxDataObjectComposite : public wxDataObject
 245 {
 246 public:
 247     // ctor
 248     wxDataObjectComposite() { m_preferred = 0; }
 249
 250     // add data object (it will be deleted by wxDataObjectComposite, hence it
 251     // must be allocated on the heap) whose format will become the preferred
 252     // one if preferred == TRUE
 253     void Add(wxDataObjectSimple *dataObject, bool preferred = FALSE);
 254
 255     // implement base class pure virtuals
 256     // ----------------------------------
 257     virtual wxDataFormat GetPreferredFormat(Direction dir = Get) const;
 258     virtual size_t GetFormatCount(Direction dir = Get) const;
 259     virtual void GetAllFormats(wxDataFormat *formats, Direction dir = Get) const;
 260     virtual size_t GetDataSize(const wxDataFormat& format) const;
 261     virtual bool GetDataHere(const wxDataFormat& format, void *buf) const;
 262     virtual bool SetData(const wxDataFormat& format, size_t len, const void *buf);
 263
 264 protected:
 265     // returns the pointer to the object which supports this format or NULL
 266     wxDataObjectSimple *GetObject(const wxDataFormat& format) const;
 267
 268 private:
 269     // the list of all (simple) data objects whose formats we support
 270     wxSimpleDataObjectList m_dataObjects;
 271
 272     // the index of the preferred one (0 initially, so by default the first
 273     // one is the preferred)
 274     size_t m_preferred;
 275 };
 276
 277 // ============================================================================
 278 // Standard implementations of wxDataObjectSimple which can be used directly
 279 // (i.e. without having to derive from them) for standard data type transfers.
 280 //
 281 // Note that although all of them can work with provided data, you can also
 282 // override their virtual GetXXX() functions to only provide data on demand.
 283 // ============================================================================
 284
 285 // ----------------------------------------------------------------------------
 286 // wxTextDataObject contains text data
 287 // ----------------------------------------------------------------------------
 288
 289 class WXDLLEXPORT wxTextDataObject : public wxDataObjectSimple
 290 {
 291 public:
 292     // ctor: you can specify the text here or in SetText(), or override
 293     // GetText()
 294     wxTextDataObject(const wxString& text = wxEmptyString)
 295         : wxDataObjectSimple(wxDF_TEXT), m_text(text)
 296         {
 297         }
 298
 299     // virtual functions which you may override if you want to provide text on
 300     // demand only - otherwise, the trivial default versions will be used
 301     virtual size_t GetTextLength() const { return m_text.Len() + 1; }
 302     virtual wxString GetText() const { return m_text; }
 303     virtual void SetText(const wxString& text) { m_text = text; }
 304
 305     // implement base class pure virtuals
 306     // ----------------------------------
 307     virtual size_t GetDataSize() const;
 308     virtual bool GetDataHere(void *buf) const;
 309     virtual bool SetData(size_t len, const void *buf);
 310
 311 private:
 312     wxString m_text;
 313 };
 314
 315 // ----------------------------------------------------------------------------
 316 // wxBitmapDataObject contains a bitmap
 317 // ----------------------------------------------------------------------------
 318
 319 class WXDLLEXPORT wxBitmapDataObjectBase : public wxDataObjectSimple
 320 {
 321 public:
 322     // ctor: you can specify the bitmap here or in SetBitmap(), or override
 323     // GetBitmap()
 324     wxBitmapDataObjectBase(const wxBitmap& bitmap = wxNullBitmap)
 325         : wxDataObjectSimple(wxDF_BITMAP), m_bitmap(bitmap)
 326         {
 327         }
 328
 329     // virtual functions which you may override if you want to provide data on
 330     // demand only - otherwise, the trivial default versions will be used
 331     virtual wxBitmap GetBitmap() const { return m_bitmap; }
 332     virtual void SetBitmap(const wxBitmap& bitmap) { m_bitmap = bitmap; }
 333
 334 protected:
 335     wxBitmap m_bitmap;
 336 };
 337
 338 // ----------------------------------------------------------------------------
 339 // wxFileDataObject contains a list of filenames
 340 //
 341 // NB: notice that this is a "write only" object, it can only be filled with
 342 //     data from drag and drop operation.
 343 // ----------------------------------------------------------------------------
 344
 345 class WXDLLEXPORT wxFileDataObjectBase : public wxDataObjectSimple
 346 {
 347 public:
 348     // ctor: use AddFile() later to fill the array
 349     wxFileDataObjectBase() : wxDataObjectSimple(wxDF_FILENAME) { }
 350
 351     // get a reference to our array
 352     const wxArrayString& GetFilenames() const { return m_filenames; }
 353
 354     // the Get() functions do nothing for us
 355     virtual size_t GetDataSize() const { return 0; }
 356     virtual bool GetDataHere(void *WXUNUSED(buf)) const { return FALSE; }
 357
 358 protected:
 359     wxArrayString m_filenames;
 360 };
 361
 362 // ----------------------------------------------------------------------------
 363 // wxCustomDataObject contains arbitrary untyped user data.
 364 //
 365 // It is understood that this data can be copied bitwise.
 366 // ----------------------------------------------------------------------------
 367
 368 class WXDLLEXPORT wxCustomDataObject : public wxDataObjectSimple
 369 {
 370 public:
 371     // if you don't specify the format in the ctor, you can still use
 372     // SetFormat() later
 373     wxCustomDataObject(const wxDataFormat& format = wxDF_INVALID);
 374
 375     // the dtor calls Free()
 376     virtual ~wxCustomDataObject();
 377
 378     // you can call SetData() to set m_data: it will make a copy of the data
 379     // you pass - or you can use TakeData() which won't copy anything, but
 380     // will take ownership of data (i.e. will call Free() on it later)
 381     void TakeData(size_t size, void *data);
 382
 383     // this function is called to allocate "size" bytes of memory from
 384     // SetData(). The default version uses operator new[].
 385     virtual void *Alloc(size_t size);
 386
 387     // this function is called when the data is freed, you may override it to
 388     // anything you want (or may be nothing at all). The default version calls
 389     // operator delete[] on m_data
 390     virtual void Free();
 391
 392     // get data: you may override these functions if you wish to provide data
 393     // only when it's requested
 394     virtual size_t GetSize() const { return m_size; }
 395     virtual void *GetData() const { return m_data; }
 396
 397     // implement base class pure virtuals
 398     // ----------------------------------
 399     virtual size_t GetDataSize() const;
 400     virtual bool GetDataHere(void *buf) const;
 401     virtual bool SetData(size_t size, const void *buf);
 402
 403 private:
 404     size_t m_size;
 405     void  *m_data;
 406 };
 407
 408 // ----------------------------------------------------------------------------
 409 // include platform-specific declarations of wxXXXBase classes
 410 // ----------------------------------------------------------------------------
 411
 412 #if defined(__WXMSW__)
 413     #include "wx/msw/ole/dataobj2.h"
 414 #elif defined(__WXMOTIF__)
 415     #include "wx/motif/dataobj2.h"
 416 #elif defined(__WXGTK__)
 417     #include "wx/gtk/dataobj2.h"
 418 #endif
 419
 420 #endif // _WX_DATAOBJ_H_BASE_