wxPython/src/_dataobj.i

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        _dataobj.i
   3 // Purpose:     SWIG definitions for the Data Object classes
   4 //
   5 // Author:      Robin Dunn
   6 //
   7 // Created:     31-October-1999
   8 // RCS-ID:      $Id$
   9 // Copyright:   (c) 2003 by Total Control Software
  10 // Licence:     wxWindows license
  11 /////////////////////////////////////////////////////////////////////////////
  12
  13 // Not a %module
  14
  15
  16 //---------------------------------------------------------------------------
  17
  18 %{
  19 #include <wx/dataobj.h>
  20 %}
  21
  22 //---------------------------------------------------------------------------
  23 %newgroup
  24
  25
  26 enum wxDataFormatId
  27 {
  28     wxDF_INVALID,
  29     wxDF_TEXT,
  30     wxDF_BITMAP,
  31     wxDF_METAFILE,
  32     wxDF_SYLK,
  33     wxDF_DIF,
  34     wxDF_TIFF,
  35     wxDF_OEMTEXT,
  36     wxDF_DIB,
  37     wxDF_PALETTE,
  38     wxDF_PENDATA,
  39     wxDF_RIFF,
  40     wxDF_WAVE,
  41     wxDF_UNICODETEXT,
  42     wxDF_ENHMETAFILE,
  43     wxDF_FILENAME,
  44     wxDF_LOCALE,
  45     wxDF_PRIVATE,
  46     wxDF_HTML,
  47     wxDF_MAX,
  48 };
  49
  50
  51 DocStr(wxDataFormat,
  52 "A wx.DataFormat is an encapsulation of a platform-specific format
  53 handle which is used by the system for the clipboard and drag and drop
  54 operations. The applications are usually only interested in, for
  55 example, pasting data from the clipboard only if the data is in a
  56 format the program understands.  A data format is is used to uniquely
  57 identify this format.",
  58 "
  59 On the system level, a data format is usually just a number, (which
  60 may be the CLIPFORMAT under Windows or Atom under X11, for example.)
  61
  62 The standard format IDs are:
  63
  64     ================    =====================================
  65     wx.DF_INVALID       An invalid format
  66     wx.DF_TEXT          Text format
  67     wx.DF_BITMAP        A bitmap (wx.Bitmap)
  68     wx.DF_METAFILE      A metafile (wx.Metafile, Windows only)
  69     wx.DF_FILENAME      A list of filenames
  70     wx.DF_HTML          An HTML string. This is only valid on
  71                         Windows and non-unicode builds
  72     ================    =====================================
  73
  74 Aside the standard formats, the application may also use custom
  75 formats which are identified by their names (strings) and not numeric
  76 identifiers. Although internally custom format must be created (or
  77 registered) first, you shouldn\'t care about it because it is done
  78 automatically the first time the wxDataFormat object corresponding to
  79 a given format name is created.
  80
  81 ");
  82
  83 class wxDataFormat {
  84 public:
  85     DocCtorStr(
  86         wxDataFormat( wxDataFormatId type ),
  87         "Constructs a data format object for one of the standard data formats
  88 or an empty data object (use SetType or SetId later in this case)", "");
  89
  90     DocCtorStrName(
  91         wxDataFormat(const wxString& format),
  92         "Constructs a data format object for a custom format identified by its
  93 name.", "",
  94         CustomDataFormat);
  95
  96     ~wxDataFormat();
  97
  98
  99     %nokwargs operator==;
 100     %nokwargs operator!=;
 101     bool operator==(wxDataFormatId format) const;
 102     bool operator!=(wxDataFormatId format) const;
 103     bool operator==(const wxDataFormat& format) const;
 104     bool operator!=(const wxDataFormat& format) const;
 105
 106
 107     DocDeclStr(
 108         void , SetType(wxDataFormatId format),
 109         "Sets the format to the given value, which should be one of wx.DF_XXX
 110 constants.", "");
 111
 112     DocDeclStr(
 113         wxDataFormatId , GetType() const,
 114         "Returns the platform-specific number identifying the format.", "");
 115
 116
 117     DocDeclStr(
 118         wxString , GetId() const,
 119         "Returns the name of a custom format (this function will fail for a
 120 standard format).", "");
 121
 122     DocDeclStr(
 123         void , SetId(const wxString& format),
 124         "Sets the format to be the custom format identified by the given name.", "");
 125 };
 126
 127
 128 %immutable;
 129 const wxDataFormat wxFormatInvalid;
 130 %mutable;
 131
 132
 133 //---------------------------------------------------------------------------
 134
 135
 136 // wxDataObject represents a piece of data which knows which formats it
 137 // supports and knows how to render itself in each of them - GetDataHere(),
 138 // and how to restore data from the buffer (SetData()).
 139 //
 140 // Although this class may be used directly (i.e. custom classes may be
 141 // derived from it), in many cases it might be simpler to use either
 142 // wxDataObjectSimple or wxDataObjectComposite classes.
 143 //
 144 // A data object may be "read only", i.e. support only GetData() functions or
 145 // "read-write", i.e. support both GetData() and SetData() (in principle, it
 146 // might be "write only" too, but this is rare). Moreover, it doesn't have to
 147 // support the same formats in Get() and Set() directions: for example, a data
 148 // object containing JPEG image might accept BMPs in GetData() because JPEG
 149 // image may be easily transformed into BMP but not in SetData(). Accordingly,
 150 // all methods dealing with formats take an additional "direction" argument
 151 // which is either SET or GET and which tells the function if the format needs
 152 // to be supported by SetData() or GetDataHere().
 153 class wxDataObject {
 154 public:
 155     enum Direction {
 156         Get  = 0x01,    // format is supported by GetDataHere()
 157         Set  = 0x02,    // format is supported by SetData()
 158         Both = 0x03     // format is supported by both (unused currently)
 159     };
 160
 161     // wxDataObject();  // ***  It's an ABC.
 162     ~wxDataObject();
 163
 164     // get the best suited format for rendering our data
 165     virtual wxDataFormat GetPreferredFormat(Direction dir = Get) const;
 166
 167     // get the number of formats we support
 168     virtual size_t GetFormatCount(Direction dir = Get) const;
 169
 170     // returns True if this format is supported
 171     bool IsSupported(const wxDataFormat& format, Direction dir = Get) const;
 172
 173     // get the (total) size of data for the given format
 174     virtual size_t GetDataSize(const wxDataFormat& format) const;
 175
 176
 177     //-------------------------------------------------------------------
 178     // TODO:  Fix these three methods to do the right Pythonic things...
 179     //-------------------------------------------------------------------
 180
 181     // return all formats in the provided array (of size GetFormatCount())
 182     virtual void GetAllFormats(wxDataFormat *formats,
 183                                Direction dir = Get) const;
 184
 185     // copy raw data (in the specified format) to the provided buffer, return
 186     // True if data copied successfully, False otherwise
 187     virtual bool GetDataHere(const wxDataFormat& format, void *buf) const;
 188
 189     // get data from the buffer of specified length (in the given format),
 190     // return True if the data was read successfully, False otherwise
 191     virtual bool SetData(const wxDataFormat& format,
 192                          size_t len, const void * buf);
 193 };
 194
 195
 196 //---------------------------------------------------------------------------
 197
 198
 199
 200 // wxDataObjectSimple is a wxDataObject which only supports one format (in
 201 // both Get and Set directions, but you may return False from GetDataHere() or
 202 // SetData() if one of them is not supported). This is the simplest possible
 203 // wxDataObject implementation.
 204 //
 205 // This is still an "abstract base class" (although it doesn't have any pure
 206 // virtual functions), to use it you should derive from it and implement
 207 // GetDataSize(), GetDataHere() and SetData() functions because the base class
 208 // versions don't do anything - they just return "not implemented".
 209 //
 210 // This class should be used when you provide data in only one format (no
 211 // conversion to/from other formats), either a standard or a custom one.
 212 // Otherwise, you should use wxDataObjectComposite or wxDataObject directly.
 213 class wxDataObjectSimple : public wxDataObject {
 214 public:
 215     wxDataObjectSimple(const wxDataFormat& format = wxFormatInvalid);
 216
 217     // get/set the format we support
 218     const wxDataFormat& GetFormat();
 219     void SetFormat(const wxDataFormat& format);
 220
 221 };
 222
 223
 224 %{  // Create a new class for wxPython to use
 225 class wxPyDataObjectSimple : public wxDataObjectSimple {
 226 public:
 227     wxPyDataObjectSimple(const wxDataFormat& format = wxFormatInvalid)
 228         : wxDataObjectSimple(format) {}
 229
 230     DEC_PYCALLBACK_SIZET__const(GetDataSize);
 231     bool GetDataHere(void *buf) const;
 232     bool SetData(size_t len, const void *buf) const;
 233     PYPRIVATE;
 234 };
 235
 236 IMP_PYCALLBACK_SIZET__const(wxPyDataObjectSimple, wxDataObjectSimple, GetDataSize);
 237
 238 bool wxPyDataObjectSimple::GetDataHere(void *buf) const {
 239     // We need to get the data for this object and write it to buf.  I think
 240     // the best way to do this for wxPython is to have the Python method
 241     // return either a string or None and then act appropriately with the
 242     // C++ version.
 243
 244     bool rval = False;
 245     bool blocked = wxPyBeginBlockThreads();
 246     if (wxPyCBH_findCallback(m_myInst, "GetDataHere")) {
 247         PyObject* ro;
 248         ro = wxPyCBH_callCallbackObj(m_myInst, Py_BuildValue("()"));
 249         if (ro) {
 250             rval = (ro != Py_None && PyString_Check(ro));
 251             if (rval)
 252                 memcpy(buf, PyString_AsString(ro), PyString_Size(ro));
 253             Py_DECREF(ro);
 254         }
 255     }
 256     wxPyEndBlockThreads(blocked);
 257     return rval;
 258 }
 259
 260 bool wxPyDataObjectSimple::SetData(size_t len, const void *buf) const{
 261     // For this one we simply need to make a string from buf and len
 262     // and send it to the Python method.
 263     bool rval = False;
 264     bool blocked = wxPyBeginBlockThreads();
 265     if (wxPyCBH_findCallback(m_myInst, "SetData")) {
 266         PyObject* data = PyString_FromStringAndSize((char*)buf, len);
 267         rval = wxPyCBH_callCallback(m_myInst, Py_BuildValue("(O)", data));
 268         Py_DECREF(data);
 269     }
 270     wxPyEndBlockThreads(blocked);
 271     return rval;
 272 }
 273 %}
 274
 275
 276
 277 // Now define it for SWIG
 278 class wxPyDataObjectSimple : public wxDataObjectSimple {
 279 public:
 280     %pythonAppend wxPyDataObjectSimple   "self._setCallbackInfo(self, PyDataObjectSimple)"
 281
 282     wxPyDataObjectSimple(const wxDataFormat& format = wxFormatInvalid);
 283     void _setCallbackInfo(PyObject* self, PyObject* _class);
 284 };
 285
 286
 287 //---------------------------------------------------------------------------
 288
 289
 290 // wxDataObjectComposite is the simplest way to implement wxDataObject
 291 // supporting multiple formats. It contains several wxDataObjectSimple and
 292 // supports all formats supported by any of them.
 293 //
 294 class wxDataObjectComposite : public wxDataObject {
 295 public:
 296     wxDataObjectComposite();
 297
 298     %apply SWIGTYPE *DISOWN { wxDataObjectSimple *dataObject };
 299     void Add(wxDataObjectSimple *dataObject, int preferred = False);
 300     %clear wxDataObjectSimple *dataObject;
 301 };
 302
 303 //---------------------------------------------------------------------------
 304
 305 // wxTextDataObject contains text data
 306 class wxTextDataObject : public wxDataObjectSimple {
 307 public:
 308     wxTextDataObject(const wxString& text = wxPyEmptyString);
 309
 310     size_t GetTextLength();
 311     wxString GetText();
 312     void SetText(const wxString& text);
 313 };
 314
 315
 316
 317 %{  // Create a new class for wxPython to use
 318 class wxPyTextDataObject : public wxTextDataObject {
 319 public:
 320     wxPyTextDataObject(const wxString& text = wxPyEmptyString)
 321         : wxTextDataObject(text) {}
 322
 323     DEC_PYCALLBACK_SIZET__const(GetTextLength);
 324     DEC_PYCALLBACK_STRING__const(GetText);
 325     DEC_PYCALLBACK__STRING(SetText);
 326     PYPRIVATE;
 327 };
 328
 329 IMP_PYCALLBACK_SIZET__const(wxPyTextDataObject, wxTextDataObject, GetTextLength);
 330 IMP_PYCALLBACK_STRING__const(wxPyTextDataObject, wxTextDataObject, GetText);
 331 IMP_PYCALLBACK__STRING(wxPyTextDataObject, wxTextDataObject, SetText);
 332
 333 %}
 334
 335
 336 // Now define it for SWIG
 337 class wxPyTextDataObject : public wxTextDataObject {
 338 public:
 339     %pythonAppend wxPyTextDataObject   "self._setCallbackInfo(self, PyTextDataObject)"
 340
 341     wxPyTextDataObject(const wxString& text = wxPyEmptyString);
 342     void _setCallbackInfo(PyObject* self, PyObject* _class);
 343 };
 344
 345 //---------------------------------------------------------------------------
 346
 347 // wxBitmapDataObject contains a bitmap
 348 class wxBitmapDataObject : public wxDataObjectSimple {
 349 public:
 350     wxBitmapDataObject(const wxBitmap& bitmap = wxNullBitmap);
 351
 352     wxBitmap GetBitmap() const;
 353     void SetBitmap(const wxBitmap& bitmap);
 354 };
 355
 356
 357
 358 %{  // Create a new class for wxPython to use
 359 class wxPyBitmapDataObject : public wxBitmapDataObject {
 360 public:
 361     wxPyBitmapDataObject(const wxBitmap& bitmap = wxNullBitmap)
 362         : wxBitmapDataObject(bitmap) {}
 363
 364     wxBitmap GetBitmap() const;
 365     void SetBitmap(const wxBitmap& bitmap);
 366     PYPRIVATE;
 367 };
 368
 369 wxBitmap wxPyBitmapDataObject::GetBitmap() const {
 370     wxBitmap* rval = &wxNullBitmap;
 371     bool blocked = wxPyBeginBlockThreads();
 372     if (wxPyCBH_findCallback(m_myInst, "GetBitmap")) {
 373         PyObject* ro;
 374         wxBitmap* ptr;
 375         ro = wxPyCBH_callCallbackObj(m_myInst, Py_BuildValue("()"));
 376         if (ro) {
 377             if (wxPyConvertSwigPtr(ro, (void **)&ptr, wxT("wxBitmap")))
 378                 rval = ptr;
 379             Py_DECREF(ro);
 380         }
 381     }
 382     wxPyEndBlockThreads(blocked);
 383     return *rval;
 384 }
 385
 386 void wxPyBitmapDataObject::SetBitmap(const wxBitmap& bitmap) {
 387     bool blocked = wxPyBeginBlockThreads();
 388     if (wxPyCBH_findCallback(m_myInst, "SetBitmap")) {
 389         PyObject* bo = wxPyConstructObject((void*)&bitmap, wxT("wxBitmap"), False);
 390         wxPyCBH_callCallback(m_myInst, Py_BuildValue("(O)", bo));
 391         Py_DECREF(bo);
 392     }
 393     wxPyEndBlockThreads(blocked);
 394 }
 395 %}
 396
 397
 398
 399 // Now define it for SWIG
 400 class wxPyBitmapDataObject : public wxBitmapDataObject {
 401 public:
 402     %pythonAppend wxPyBitmapDataObject   "self._setCallbackInfo(self, PyBitmapDataObject)"
 403
 404     wxPyBitmapDataObject(const wxBitmap& bitmap = wxNullBitmap);
 405     void _setCallbackInfo(PyObject* self, PyObject* _class);
 406 };
 407
 408 //---------------------------------------------------------------------------
 409
 410
 411 // wxFileDataObject contains a list of filenames
 412 class wxFileDataObject : public wxDataObjectSimple
 413 {
 414 public:
 415     wxFileDataObject();
 416
 417     const wxArrayString& GetFilenames();
 418     void AddFile(const wxString &filename);
 419 };
 420
 421
 422 //---------------------------------------------------------------------------
 423
 424 // wxCustomDataObject contains arbitrary untyped user data.
 425 // It is understood that this data can be copied bitwise.
 426 class wxCustomDataObject : public wxDataObjectSimple {
 427 public:
 428     wxCustomDataObject(const wxDataFormat& format = wxFormatInvalid);
 429
 430     //void TakeData(size_t size, void *data);
 431     //bool SetData(size_t size, const void *buf);
 432     %extend {
 433         void TakeData(PyObject* data) {
 434             if (PyString_Check(data)) {
 435                 // for Python we just call SetData here since we always need it to make a copy.
 436                 self->SetData(PyString_Size(data), PyString_AsString(data));
 437             }
 438             else {
 439                 // raise a TypeError if not a string
 440                 PyErr_SetString(PyExc_TypeError, "String expected.");
 441             }
 442         }
 443         bool SetData(PyObject* data) {
 444             if (PyString_Check(data)) {
 445                 return self->SetData(PyString_Size(data), PyString_AsString(data));
 446             }
 447             else {
 448                 // raise a TypeError if not a string
 449                 PyErr_SetString(PyExc_TypeError, "String expected.");
 450                 return False;
 451             }
 452         }
 453     }
 454
 455     size_t GetSize();
 456
 457     //void *GetData();
 458     %extend {
 459         PyObject* GetData() {
 460             return PyString_FromStringAndSize((char*)self->GetData(), self->GetSize());
 461         }
 462     }
 463 };
 464
 465
 466 // TODO: Implement wxPyCustomDataObject allowing GetSize, GetData and SetData
 467 // to be overloaded.
 468
 469 //---------------------------------------------------------------------------
 470
 471 class wxURLDataObject : public wxDataObjectComposite {
 472 public:
 473     wxURLDataObject();
 474
 475     wxString GetURL();
 476     void SetURL(const wxString& url);
 477 };
 478
 479 //---------------------------------------------------------------------------
 480
 481 #if defined(__WXMSW__) || defined(__WXMAC__)
 482
 483 %{
 484 #include <wx/metafile.h>
 485 %}
 486
 487 class wxMetafileDataObject : public wxDataObjectSimple
 488 {
 489 public:
 490     wxMetafileDataObject();
 491
 492     void SetMetafile(const wxMetafile& metafile);
 493     wxMetafile GetMetafile() const;
 494 };
 495
 496
 497 #else
 498 %{
 499 class wxMetafileDataObject : public wxDataObjectSimple
 500 {
 501 public:
 502     wxMetafileDataObject() { wxPyRaiseNotImplemented(); }
 503 };
 504 %}
 505
 506 class wxMetafileDataObject : public wxDataObjectSimple
 507 {
 508 public:
 509     wxMetafileDataObject();
 510 };
 511
 512 #endif
 513
 514 //---------------------------------------------------------------------------
 515 //---------------------------------------------------------------------------
 516