| 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 | DocStr(wxDataObject, |
| 136 | "A wx.DataObject represents data that can be copied to or from the |
| 137 | clipboard, or dragged and dropped. The important thing about |
| 138 | wx.DataObject is that this is a 'smart' piece of data unlike usual |
| 139 | 'dumb' data containers such as memory buffers or files. Being 'smart' |
| 140 | here means that the data object itself should know what data formats |
| 141 | it supports and how to render itself in each of supported formats. |
| 142 | |
| 143 | **NOTE**: This class is an abstract base class and can not be used |
| 144 | directly from Python. If you need a custom type of data object then |
| 145 | you should instead derive from `wx.PyDataObjectSimple` or use |
| 146 | `wx.CustomDataObject`. |
| 147 | ", " |
| 148 | Not surprisingly, being 'smart' comes at a price of added |
| 149 | complexity. This is reasonable for the situations when you really need |
| 150 | to support multiple formats, but may be annoying if you only want to |
| 151 | do something simple like cut and paste text. |
| 152 | |
| 153 | To provide a solution for both cases, wxWidgets has two predefined |
| 154 | classes which derive from wx.DataObject: `wx.DataObjectSimple` and |
| 155 | `wx.DataObjectComposite`. `wx.DataObjectSimple` is the simplest |
| 156 | wx.DataObject possible and only holds data in a single format (such as |
| 157 | text or bitmap) and `wx.DataObjectComposite` is the simplest way to |
| 158 | implement a wx.DataObject which supports multiple simultaneous formats |
| 159 | because it achievs this by simply holding several |
| 160 | `wx.DataObjectSimple` objects. |
| 161 | |
| 162 | Please note that the easiest way to use drag and drop and the |
| 163 | clipboard with multiple formats is by using `wx.DataObjectComposite`, |
| 164 | but it is not the most efficient one as each `wx.DataObjectSimple` |
| 165 | would contain the whole data in its respective formats. Now imagine |
| 166 | that you want to paste 200 pages of text in your proprietary format, |
| 167 | as well as Word, RTF, HTML, Unicode and plain text to the clipboard |
| 168 | and even today's computers are in trouble. For this case, you will |
| 169 | have to derive from wx.DataObject directly and make it enumerate its |
| 170 | formats and provide the data in the requested format on |
| 171 | demand. (**TODO**: This is currently not possible from Python. Make |
| 172 | it so.) |
| 173 | |
| 174 | Note that the platform transfer mechanisms for the clipboard and drag |
| 175 | and drop, do not copy any data out of the source application until |
| 176 | another application actually requests the data. This is in contrast to |
| 177 | the 'feel' offered to the user of a program who would normally think |
| 178 | that the data resides in the clipboard after having pressed 'Copy' - |
| 179 | in reality it is only declared to be available. |
| 180 | "); |
| 181 | |
| 182 | // [other docs...] |
| 183 | // There are several predefined data object classes derived from |
| 184 | // wxDataObjectSimple: wxFileDataObject, wxTextDataObject and |
| 185 | // wxBitmapDataObject which can be used without change. |
| 186 | |
| 187 | // You may also derive your own data object classes from |
| 188 | // wxCustomDataObject for user-defined types. The format of user-defined |
| 189 | // data is given as mime-type string literal, such as 'application/word' |
| 190 | // or 'image/png'. These strings are used as they are under Unix (so far |
| 191 | // only GTK) to identify a format and are translated into their Windows |
| 192 | // equivalent under Win32 (using the OLE IDataObject for data exchange to |
| 193 | // and from the clipboard and for drag and drop). Note that the format |
| 194 | // string translation under Windows is not yet finished. |
| 195 | |
| 196 | |
| 197 | |
| 198 | class wxDataObject { |
| 199 | public: |
| 200 | enum Direction { |
| 201 | Get = 0x01, // format is supported by GetDataHere() |
| 202 | Set = 0x02, // format is supported by SetData() |
| 203 | Both = 0x03 // format is supported by both (unused currently) |
| 204 | }; |
| 205 | |
| 206 | // wxDataObject(); // *** It's an ABC. |
| 207 | ~wxDataObject(); |
| 208 | |
| 209 | DocDeclStr( |
| 210 | virtual wxDataFormat , GetPreferredFormat(Direction dir = Get) const, |
| 211 | "Returns the preferred format for either rendering the data (if dir is |
| 212 | Get, its default value) or for setting it. Usually this will be the |
| 213 | native format of the wx.DataObject.", ""); |
| 214 | |
| 215 | |
| 216 | DocDeclStr( |
| 217 | virtual size_t , GetFormatCount(Direction dir = Get) const, |
| 218 | "Returns the number of available formats for rendering or setting the |
| 219 | data.", ""); |
| 220 | |
| 221 | |
| 222 | DocDeclStr( |
| 223 | bool , IsSupported(const wxDataFormat& format, Direction dir = Get) const, |
| 224 | "Returns True if this format is supported.", ""); |
| 225 | |
| 226 | |
| 227 | DocDeclStr( |
| 228 | virtual size_t , GetDataSize(const wxDataFormat& format) const, |
| 229 | "Get the (total) size of data for the given format", ""); |
| 230 | |
| 231 | |
| 232 | |
| 233 | // return all formats in the provided array (of size GetFormatCount()) |
| 234 | //virtual void GetAllFormats(wxDataFormat *formats, |
| 235 | // Direction dir = Get) const; |
| 236 | DocAStr(GetAllFormats, |
| 237 | "GetAllFormats(self, int dir=Get) -> [formats]", |
| 238 | "Returns a list of all the wx.DataFormats that this dataobject supports |
| 239 | in the given direction.", ""); |
| 240 | %extend { |
| 241 | PyObject* GetAllFormats(Direction dir = Get) { |
| 242 | size_t count = self->GetFormatCount(dir); |
| 243 | wxDataFormat* formats = new wxDataFormat[count]; |
| 244 | self->GetAllFormats(formats, dir); |
| 245 | |
| 246 | bool blocked = wxPyBeginBlockThreads(); |
| 247 | PyObject* list = PyList_New(count); |
| 248 | for (size_t i=0; i<count; i++) { |
| 249 | wxDataFormat* format = new wxDataFormat(formats[i]); |
| 250 | PyObject* obj = wxPyConstructObject((void*)format, wxT("wxDataFormat"), true); |
| 251 | PyList_Append(list, obj); |
| 252 | Py_DECREF(obj); |
| 253 | } |
| 254 | wxPyEndBlockThreads(blocked); |
| 255 | delete [] formats; |
| 256 | return list; |
| 257 | } |
| 258 | } |
| 259 | |
| 260 | |
| 261 | |
| 262 | // copy raw data (in the specified format) to the provided buffer, return |
| 263 | // True if data copied successfully, False otherwise |
| 264 | // virtual bool GetDataHere(const wxDataFormat& format, void *buf) const; |
| 265 | |
| 266 | DocAStr(GetDataHere, |
| 267 | "GetDataHere(self, DataFormat format) -> String", |
| 268 | "Get the data bytes in the specified format, returns None on failure. |
| 269 | ", " |
| 270 | :todo: This should use the python buffer interface isntead..."); |
| 271 | %extend { |
| 272 | PyObject* GetDataHere(const wxDataFormat& format) { |
| 273 | PyObject* rval = NULL; |
| 274 | size_t size = self->GetDataSize(format); |
| 275 | bool blocked = wxPyBeginBlockThreads(); |
| 276 | if (size) { |
| 277 | char* buf = new char[size]; |
| 278 | if (self->GetDataHere(format, buf)) |
| 279 | rval = PyString_FromStringAndSize(buf, size); |
| 280 | delete [] buf; |
| 281 | } |
| 282 | if (! rval) { |
| 283 | rval = Py_None; |
| 284 | Py_INCREF(rval); |
| 285 | } |
| 286 | wxPyEndBlockThreads(blocked); |
| 287 | return rval; |
| 288 | } |
| 289 | } |
| 290 | |
| 291 | |
| 292 | // get data from the buffer of specified length (in the given format), |
| 293 | // return True if the data was read successfully, False otherwise |
| 294 | //virtual bool SetData(const wxDataFormat& format, |
| 295 | // size_t len, const void * buf); |
| 296 | DocAStr(SetData, |
| 297 | "SetData(self, DataFormat format, String data) -> bool", |
| 298 | "Set the data in the specified format from the bytes in the the data string. |
| 299 | ", " |
| 300 | :todo: This should use the python buffer interface isntead..."); |
| 301 | %extend { |
| 302 | bool SetData(const wxDataFormat& format, PyObject* data) { |
| 303 | bool rval; |
| 304 | bool blocked = wxPyBeginBlockThreads(); |
| 305 | if (PyString_Check(data)) { |
| 306 | rval = self->SetData(format, PyString_Size(data), PyString_AsString(data)); |
| 307 | } |
| 308 | else { |
| 309 | // raise a TypeError if not a string |
| 310 | PyErr_SetString(PyExc_TypeError, "String expected."); |
| 311 | rval = false; |
| 312 | } |
| 313 | wxPyEndBlockThreads(blocked); |
| 314 | return rval; |
| 315 | } |
| 316 | } |
| 317 | |
| 318 | |
| 319 | }; |
| 320 | |
| 321 | |
| 322 | //--------------------------------------------------------------------------- |
| 323 | |
| 324 | |
| 325 | DocStr(wxDataObjectSimple, |
| 326 | "wx.DataObjectSimple is a `wx.DataObject` which only supports one |
| 327 | format. This is the simplest possible `wx.DataObject` implementation. |
| 328 | |
| 329 | This is still an \"abstract base class\" meaning that you can't use it |
| 330 | directly. You either need to use one of the predefined base classes, |
| 331 | or derive your own class from `wx.PyDataObjectSimple`. |
| 332 | ", ""); |
| 333 | |
| 334 | class wxDataObjectSimple : public wxDataObject { |
| 335 | public: |
| 336 | DocCtorStr( |
| 337 | wxDataObjectSimple(const wxDataFormat& format = wxFormatInvalid), |
| 338 | "Constructor accepts the supported format (none by default) which may |
| 339 | also be set later with `SetFormat`.",""); |
| 340 | |
| 341 | |
| 342 | DocDeclStr( |
| 343 | const wxDataFormat& , GetFormat(), |
| 344 | "Returns the (one and only one) format supported by this object. It is |
| 345 | assumed that the format is supported in both directions.", ""); |
| 346 | |
| 347 | DocDeclStr( |
| 348 | void , SetFormat(const wxDataFormat& format), |
| 349 | "Sets the supported format.", ""); |
| 350 | |
| 351 | DocDeclStr( |
| 352 | virtual size_t , GetDataSize() const, |
| 353 | "Get the size of our data.", ""); |
| 354 | |
| 355 | |
| 356 | |
| 357 | DocAStr(GetDataHere, |
| 358 | "GetDataHere(self) -> String", |
| 359 | "Returns the data bytes from the data object as a string, returns None |
| 360 | on failure. Must be implemented in the derived class if the object |
| 361 | supports rendering its data.", ""); |
| 362 | %extend { |
| 363 | PyObject* GetDataHere() { |
| 364 | PyObject* rval = NULL; |
| 365 | size_t size = self->GetDataSize(); |
| 366 | bool blocked = wxPyBeginBlockThreads(); |
| 367 | if (size) { |
| 368 | char* buf = new char[size]; |
| 369 | if (self->GetDataHere(buf)) |
| 370 | rval = PyString_FromStringAndSize(buf, size); |
| 371 | delete [] buf; |
| 372 | } |
| 373 | if (! rval) { |
| 374 | rval = Py_None; |
| 375 | Py_INCREF(rval); |
| 376 | } |
| 377 | wxPyEndBlockThreads(blocked); |
| 378 | return rval; |
| 379 | } |
| 380 | } |
| 381 | |
| 382 | |
| 383 | DocAStr(SetData, |
| 384 | "SetData(self, String data) -> bool", |
| 385 | "Copy the data value to the data object. Must be implemented in the |
| 386 | derived class if the object supports setting its data. |
| 387 | ", ""); |
| 388 | %extend { |
| 389 | bool SetData(PyObject* data) { |
| 390 | bool rval; |
| 391 | bool blocked = wxPyBeginBlockThreads(); |
| 392 | if (PyString_Check(data)) { |
| 393 | rval = self->SetData(PyString_Size(data), PyString_AsString(data)); |
| 394 | } |
| 395 | else { |
| 396 | // raise a TypeError if not a string |
| 397 | PyErr_SetString(PyExc_TypeError, "String expected."); |
| 398 | rval = false; |
| 399 | } |
| 400 | wxPyEndBlockThreads(blocked); |
| 401 | return rval; |
| 402 | } |
| 403 | } |
| 404 | |
| 405 | }; |
| 406 | |
| 407 | |
| 408 | |
| 409 | |
| 410 | %{ // Create a new class for wxPython to use |
| 411 | class wxPyDataObjectSimple : public wxDataObjectSimple { |
| 412 | public: |
| 413 | wxPyDataObjectSimple(const wxDataFormat& format = wxFormatInvalid) |
| 414 | : wxDataObjectSimple(format) {} |
| 415 | |
| 416 | DEC_PYCALLBACK_SIZET__const(GetDataSize); |
| 417 | bool GetDataHere(void *buf) const; |
| 418 | bool SetData(size_t len, const void *buf) const; |
| 419 | PYPRIVATE; |
| 420 | }; |
| 421 | |
| 422 | IMP_PYCALLBACK_SIZET__const(wxPyDataObjectSimple, wxDataObjectSimple, GetDataSize); |
| 423 | |
| 424 | bool wxPyDataObjectSimple::GetDataHere(void *buf) const { |
| 425 | // We need to get the data for this object and write it to buf. I think |
| 426 | // the best way to do this for wxPython is to have the Python method |
| 427 | // return either a string or None and then act appropriately with the |
| 428 | // C++ version. |
| 429 | |
| 430 | bool rval = false; |
| 431 | bool blocked = wxPyBeginBlockThreads(); |
| 432 | if (wxPyCBH_findCallback(m_myInst, "GetDataHere")) { |
| 433 | PyObject* ro; |
| 434 | ro = wxPyCBH_callCallbackObj(m_myInst, Py_BuildValue("()")); |
| 435 | if (ro) { |
| 436 | rval = (ro != Py_None && PyString_Check(ro)); |
| 437 | if (rval) |
| 438 | memcpy(buf, PyString_AsString(ro), PyString_Size(ro)); |
| 439 | Py_DECREF(ro); |
| 440 | } |
| 441 | } |
| 442 | wxPyEndBlockThreads(blocked); |
| 443 | return rval; |
| 444 | } |
| 445 | |
| 446 | bool wxPyDataObjectSimple::SetData(size_t len, const void *buf) const{ |
| 447 | // For this one we simply need to make a string from buf and len |
| 448 | // and send it to the Python method. |
| 449 | bool rval = false; |
| 450 | bool blocked = wxPyBeginBlockThreads(); |
| 451 | if (wxPyCBH_findCallback(m_myInst, "SetData")) { |
| 452 | PyObject* data = PyString_FromStringAndSize((char*)buf, len); |
| 453 | rval = wxPyCBH_callCallback(m_myInst, Py_BuildValue("(O)", data)); |
| 454 | Py_DECREF(data); |
| 455 | } |
| 456 | wxPyEndBlockThreads(blocked); |
| 457 | return rval; |
| 458 | } |
| 459 | %} |
| 460 | |
| 461 | |
| 462 | |
| 463 | // Now define it for SWIG |
| 464 | DocStr(wxPyDataObjectSimple, |
| 465 | "wx.PyDataObjectSimple is a version of `wx.DataObjectSimple` that is |
| 466 | Python-aware and knows how to reflect calls to its C++ virtual methods |
| 467 | to methods in the Python derived class. You should derive from this |
| 468 | class and overload `GetDataSize`, `GetDataHere` and `SetData` when you |
| 469 | need to create your own simple single-format type of `wx.DataObject`. |
| 470 | ", " |
| 471 | Here is a simple example:: |
| 472 | |
| 473 | class MyDataObject(wx.PyDataObjectSimple): |
| 474 | def __init__(self): |
| 475 | wx.PyDataObjectSimple.__init__( |
| 476 | self, wx.CustomDataFormat('MyDOFormat')) |
| 477 | self.data = '' |
| 478 | |
| 479 | def GetDataSize(self): |
| 480 | return len(self.data) |
| 481 | def GetDataHere(self): |
| 482 | return self.data # returns a string |
| 483 | def SetData(self, data): |
| 484 | self.data = data |
| 485 | return True |
| 486 | |
| 487 | Note that there is already a `wx.CustomDataObject` class that behaves |
| 488 | very similarly to this example. The value of creating your own |
| 489 | derived class like this is to be able to do additional things when the |
| 490 | data is requested or given via the clipboard or drag and drop |
| 491 | operation, such as generate the data value or decode it into needed |
| 492 | data structures. |
| 493 | "); |
| 494 | class wxPyDataObjectSimple : public wxDataObjectSimple { |
| 495 | public: |
| 496 | %pythonAppend wxPyDataObjectSimple "self._setCallbackInfo(self, PyDataObjectSimple)" |
| 497 | |
| 498 | wxPyDataObjectSimple(const wxDataFormat& format = wxFormatInvalid); |
| 499 | void _setCallbackInfo(PyObject* self, PyObject* _class); |
| 500 | }; |
| 501 | |
| 502 | |
| 503 | //--------------------------------------------------------------------------- |
| 504 | |
| 505 | |
| 506 | DocStr(wxDataObjectComposite, |
| 507 | "wx.DataObjectComposite is the simplest `wx.DataObject` derivation |
| 508 | which may be sued to support multiple formats. It contains several |
| 509 | 'wx.DataObjectSimple` objects and supports any format supported by at |
| 510 | least one of them. Only one of these data objects is *preferred* (the |
| 511 | first one if not explicitly changed by using the second parameter of |
| 512 | `Add`) and its format determines the preferred format of the composite |
| 513 | data object as well. |
| 514 | |
| 515 | See `wx.DataObject` documentation for the reasons why you might prefer |
| 516 | to use wx.DataObject directly instead of wx.DataObjectComposite for |
| 517 | efficiency reasons. |
| 518 | ", ""); |
| 519 | |
| 520 | class wxDataObjectComposite : public wxDataObject { |
| 521 | public: |
| 522 | wxDataObjectComposite(); |
| 523 | |
| 524 | %apply SWIGTYPE *DISOWN { wxDataObjectSimple *dataObject }; |
| 525 | |
| 526 | DocDeclStr( |
| 527 | void , Add(wxDataObjectSimple *dataObject, bool preferred = false), |
| 528 | "Adds the dataObject to the list of supported objects and it becomes |
| 529 | the preferred object if preferred is True.", ""); |
| 530 | |
| 531 | %clear wxDataObjectSimple *dataObject; |
| 532 | }; |
| 533 | |
| 534 | //--------------------------------------------------------------------------- |
| 535 | |
| 536 | DocStr(wxTextDataObject, |
| 537 | "wx.TextDataObject is a specialization of `wx.DataObject` for text |
| 538 | data. It can be used without change to paste data into the `wx.Clipboard` |
| 539 | or a `wx.DropSource`. |
| 540 | |
| 541 | Alternativly, you may wish to derive a new class from the |
| 542 | `wx.PyTextDataObject` class for providing text on-demand in order to |
| 543 | minimize memory consumption when offering data in several formats, |
| 544 | such as plain text and RTF, because by default the text is stored in a |
| 545 | string in this class, but it might as well be generated on demand when |
| 546 | requested. For this, `GetTextLength` and `GetText` will have to be |
| 547 | overridden.", ""); |
| 548 | class wxTextDataObject : public wxDataObjectSimple { |
| 549 | public: |
| 550 | DocCtorStr( |
| 551 | wxTextDataObject(const wxString& text = wxPyEmptyString), |
| 552 | "Constructor, may be used to initialise the text (otherwise `SetText` |
| 553 | should be used later).", ""); |
| 554 | |
| 555 | DocDeclStr( |
| 556 | size_t , GetTextLength(), |
| 557 | "Returns the data size. By default, returns the size of the text data |
| 558 | set in the constructor or using `SetText`. This can be overridden (via |
| 559 | `wx.PyTextDataObject`) to provide text size data on-demand. It is |
| 560 | recommended to return the text length plus 1 for a trailing zero, but |
| 561 | this is not strictly required.", ""); |
| 562 | |
| 563 | DocDeclStr( |
| 564 | wxString , GetText(), |
| 565 | "Returns the text associated with the data object.", ""); |
| 566 | |
| 567 | DocDeclStr( |
| 568 | void , SetText(const wxString& text), |
| 569 | "Sets the text associated with the data object. This method is called |
| 570 | when the data object receives the data and, by default, copies the |
| 571 | text into the member variable. If you want to process the text on the |
| 572 | fly you may wish to override this function (via |
| 573 | `wx.PyTextDataObject`.)", ""); |
| 574 | |
| 575 | }; |
| 576 | |
| 577 | |
| 578 | |
| 579 | |
| 580 | |
| 581 | |
| 582 | %{ // Create a new class for wxPython to use |
| 583 | class wxPyTextDataObject : public wxTextDataObject { |
| 584 | public: |
| 585 | wxPyTextDataObject(const wxString& text = wxPyEmptyString) |
| 586 | : wxTextDataObject(text) {} |
| 587 | |
| 588 | DEC_PYCALLBACK_SIZET__const(GetTextLength); |
| 589 | DEC_PYCALLBACK_STRING__const(GetText); |
| 590 | DEC_PYCALLBACK__STRING(SetText); |
| 591 | PYPRIVATE; |
| 592 | }; |
| 593 | |
| 594 | IMP_PYCALLBACK_SIZET__const(wxPyTextDataObject, wxTextDataObject, GetTextLength); |
| 595 | IMP_PYCALLBACK_STRING__const(wxPyTextDataObject, wxTextDataObject, GetText); |
| 596 | IMP_PYCALLBACK__STRING(wxPyTextDataObject, wxTextDataObject, SetText); |
| 597 | |
| 598 | %} |
| 599 | |
| 600 | |
| 601 | // Now define it for SWIG |
| 602 | |
| 603 | DocStr(wxPyTextDataObject, |
| 604 | "wx.PyTextDataObject is a version of `wx.TextDataObject` that is |
| 605 | Python-aware and knows how to reflect calls to its C++ virtual methods |
| 606 | to methods in the Python derived class. You should derive from this |
| 607 | class and overload `GetTextLength`, `GetText`, and `SetText` when you |
| 608 | want to be able to provide text on demand instead of preloading it |
| 609 | into the data object.", ""); |
| 610 | |
| 611 | class wxPyTextDataObject : public wxTextDataObject { |
| 612 | public: |
| 613 | %pythonAppend wxPyTextDataObject "self._setCallbackInfo(self, PyTextDataObject)" |
| 614 | |
| 615 | wxPyTextDataObject(const wxString& text = wxPyEmptyString); |
| 616 | void _setCallbackInfo(PyObject* self, PyObject* _class); |
| 617 | }; |
| 618 | |
| 619 | //--------------------------------------------------------------------------- |
| 620 | |
| 621 | DocStr(wxBitmapDataObject, |
| 622 | "wx.BitmapDataObject is a specialization of wxDataObject for bitmap |
| 623 | data. It can be used without change to paste data into the `wx.Clipboard` |
| 624 | or a `wx.DropSource`. |
| 625 | ", " |
| 626 | :see: `wx.PyBitmapDataObject` if you wish to override `GetBitmap` to increase efficiency."); |
| 627 | |
| 628 | class wxBitmapDataObject : public wxDataObjectSimple { |
| 629 | public: |
| 630 | DocCtorStr( |
| 631 | wxBitmapDataObject(const wxBitmap& bitmap = wxNullBitmap), |
| 632 | "Constructor, optionally passing a bitmap (otherwise use `SetBitmap` |
| 633 | later).", ""); |
| 634 | |
| 635 | DocDeclStr( |
| 636 | wxBitmap , GetBitmap() const, |
| 637 | "Returns the bitmap associated with the data object. You may wish to |
| 638 | override this method (by deriving from `wx.PyBitmapDataObject`) when |
| 639 | offering data on-demand, but this is not required by wxWidgets' |
| 640 | internals. Use this method to get data in bitmap form from the |
| 641 | `wx.Clipboard`.", ""); |
| 642 | |
| 643 | DocDeclStr( |
| 644 | void , SetBitmap(const wxBitmap& bitmap), |
| 645 | "Sets the bitmap associated with the data object. This method is called |
| 646 | when the data object receives data. Usually there will be no reason to |
| 647 | override this function.", ""); |
| 648 | |
| 649 | }; |
| 650 | |
| 651 | |
| 652 | |
| 653 | |
| 654 | |
| 655 | %{ // Create a new class for wxPython to use |
| 656 | class wxPyBitmapDataObject : public wxBitmapDataObject { |
| 657 | public: |
| 658 | wxPyBitmapDataObject(const wxBitmap& bitmap = wxNullBitmap) |
| 659 | : wxBitmapDataObject(bitmap) {} |
| 660 | |
| 661 | wxBitmap GetBitmap() const; |
| 662 | void SetBitmap(const wxBitmap& bitmap); |
| 663 | PYPRIVATE; |
| 664 | }; |
| 665 | |
| 666 | wxBitmap wxPyBitmapDataObject::GetBitmap() const { |
| 667 | wxBitmap* rval = &wxNullBitmap; |
| 668 | bool blocked = wxPyBeginBlockThreads(); |
| 669 | if (wxPyCBH_findCallback(m_myInst, "GetBitmap")) { |
| 670 | PyObject* ro; |
| 671 | wxBitmap* ptr; |
| 672 | ro = wxPyCBH_callCallbackObj(m_myInst, Py_BuildValue("()")); |
| 673 | if (ro) { |
| 674 | if (wxPyConvertSwigPtr(ro, (void **)&ptr, wxT("wxBitmap"))) |
| 675 | rval = ptr; |
| 676 | Py_DECREF(ro); |
| 677 | } |
| 678 | } |
| 679 | wxPyEndBlockThreads(blocked); |
| 680 | return *rval; |
| 681 | } |
| 682 | |
| 683 | void wxPyBitmapDataObject::SetBitmap(const wxBitmap& bitmap) { |
| 684 | bool blocked = wxPyBeginBlockThreads(); |
| 685 | if (wxPyCBH_findCallback(m_myInst, "SetBitmap")) { |
| 686 | PyObject* bo = wxPyConstructObject((void*)&bitmap, wxT("wxBitmap"), false); |
| 687 | wxPyCBH_callCallback(m_myInst, Py_BuildValue("(O)", bo)); |
| 688 | Py_DECREF(bo); |
| 689 | } |
| 690 | wxPyEndBlockThreads(blocked); |
| 691 | } |
| 692 | %} |
| 693 | |
| 694 | |
| 695 | |
| 696 | |
| 697 | DocStr(wxPyBitmapDataObject, |
| 698 | "wx.PyBitmapDataObject is a version of `wx.BitmapDataObject` that is |
| 699 | Python-aware and knows how to reflect calls to its C++ virtual methods |
| 700 | to methods in the Python derived class. To be able to provide bitmap |
| 701 | data on demand derive from this class and overload `GetBitmap`.", ""); |
| 702 | |
| 703 | class wxPyBitmapDataObject : public wxBitmapDataObject { |
| 704 | public: |
| 705 | %pythonAppend wxPyBitmapDataObject "self._setCallbackInfo(self, PyBitmapDataObject)" |
| 706 | |
| 707 | wxPyBitmapDataObject(const wxBitmap& bitmap = wxNullBitmap); |
| 708 | void _setCallbackInfo(PyObject* self, PyObject* _class); |
| 709 | }; |
| 710 | |
| 711 | //--------------------------------------------------------------------------- |
| 712 | |
| 713 | |
| 714 | DocStr(wxFileDataObject, |
| 715 | "wx.FileDataObject is a specialization of `wx.DataObjectSimple` for |
| 716 | file names. The program works with it just as if it were a list of |
| 717 | absolute file names, but internally it uses the same format as |
| 718 | Explorer and other compatible programs under Windows or GNOME/KDE |
| 719 | filemanager under Unix which makes it possible to receive files from |
| 720 | them using this class. |
| 721 | |
| 722 | :Warning: Under all non-Windows platforms this class is currently |
| 723 | \"input-only\", i.e. you can receive the files from another |
| 724 | application, but copying (or dragging) file(s) from a wxWidgets |
| 725 | application is not currently supported. |
| 726 | ", ""); |
| 727 | |
| 728 | class wxFileDataObject : public wxDataObjectSimple |
| 729 | { |
| 730 | public: |
| 731 | DocCtorStr( |
| 732 | wxFileDataObject(), |
| 733 | "", ""); |
| 734 | |
| 735 | DocDeclAStr( |
| 736 | const wxArrayString& , GetFilenames(), |
| 737 | "GetFilenames(self) -> [names]", |
| 738 | "Returns a list of file names.", ""); |
| 739 | |
| 740 | DocDeclStr( |
| 741 | void , AddFile(const wxString &filename), |
| 742 | "Adds a file to the list of files represented by this data object.", ""); |
| 743 | |
| 744 | }; |
| 745 | |
| 746 | //--------------------------------------------------------------------------- |
| 747 | |
| 748 | DocStr(wxCustomDataObject, |
| 749 | "wx.CustomDataObject is a specialization of `wx.DataObjectSimple` for |
| 750 | some application-specific data in arbitrary format. Python strings |
| 751 | are used for getting and setting data, but any picklable object can |
| 752 | easily be transfered via strings. A copy of the data is stored in the |
| 753 | data object.", ""); |
| 754 | |
| 755 | class wxCustomDataObject : public wxDataObjectSimple { |
| 756 | public: |
| 757 | wxCustomDataObject(const wxDataFormat& format = wxFormatInvalid); |
| 758 | |
| 759 | |
| 760 | DocAStr(SetData, |
| 761 | "SetData(self, String data) -> bool", |
| 762 | "Copy the data value to the data object.", ""); |
| 763 | %extend { |
| 764 | bool SetData(PyObject* data) { |
| 765 | bool rval; |
| 766 | bool blocked = wxPyBeginBlockThreads(); |
| 767 | if (PyString_Check(data)) { |
| 768 | rval = self->SetData(PyString_Size(data), PyString_AsString(data)); |
| 769 | } |
| 770 | else { |
| 771 | // raise a TypeError if not a string |
| 772 | PyErr_SetString(PyExc_TypeError, "String expected."); |
| 773 | rval = false; |
| 774 | } |
| 775 | wxPyEndBlockThreads(blocked); |
| 776 | return rval; |
| 777 | } |
| 778 | } |
| 779 | %pythoncode { TakeData = SetData } |
| 780 | |
| 781 | DocDeclStr( |
| 782 | size_t , GetSize(), |
| 783 | "Get the size of the data.", ""); |
| 784 | |
| 785 | |
| 786 | DocAStr(GetData, |
| 787 | "GetData(self) -> String", |
| 788 | "Returns the data bytes from the data object as a string.", ""); |
| 789 | %extend { |
| 790 | PyObject* GetData() { |
| 791 | PyObject* obj; |
| 792 | bool blocked = wxPyBeginBlockThreads(); |
| 793 | obj = PyString_FromStringAndSize((char*)self->GetData(), self->GetSize()); |
| 794 | wxPyEndBlockThreads(blocked); |
| 795 | return obj; |
| 796 | } |
| 797 | } |
| 798 | }; |
| 799 | |
| 800 | |
| 801 | //--------------------------------------------------------------------------- |
| 802 | |
| 803 | DocStr(wxURLDataObject, |
| 804 | "This data object holds a URL in a format that is compatible with some |
| 805 | browsers such that it is able to be dragged to or from them.", ""); |
| 806 | class wxURLDataObject : public wxDataObjectComposite { |
| 807 | public: |
| 808 | wxURLDataObject(); |
| 809 | |
| 810 | DocDeclStr( |
| 811 | wxString , GetURL(), |
| 812 | "Returns a string containing the current URL.", ""); |
| 813 | |
| 814 | DocDeclStr( |
| 815 | void , SetURL(const wxString& url), |
| 816 | "Set the URL.", ""); |
| 817 | |
| 818 | }; |
| 819 | |
| 820 | //--------------------------------------------------------------------------- |
| 821 | |
| 822 | #if defined(__WXMSW__) || defined(__WXMAC__) |
| 823 | |
| 824 | %{ |
| 825 | #include <wx/metafile.h> |
| 826 | %} |
| 827 | |
| 828 | class wxMetafileDataObject : public wxDataObjectSimple |
| 829 | { |
| 830 | public: |
| 831 | wxMetafileDataObject(); |
| 832 | |
| 833 | void SetMetafile(const wxMetafile& metafile); |
| 834 | wxMetafile GetMetafile() const; |
| 835 | }; |
| 836 | |
| 837 | |
| 838 | #else |
| 839 | %{ |
| 840 | class wxMetafileDataObject : public wxDataObjectSimple |
| 841 | { |
| 842 | public: |
| 843 | wxMetafileDataObject() { wxPyRaiseNotImplemented(); } |
| 844 | }; |
| 845 | %} |
| 846 | |
| 847 | class wxMetafileDataObject : public wxDataObjectSimple |
| 848 | { |
| 849 | public: |
| 850 | wxMetafileDataObject(); |
| 851 | }; |
| 852 | |
| 853 | #endif |
| 854 | |
| 855 | //--------------------------------------------------------------------------- |
| 856 | //--------------------------------------------------------------------------- |
| 857 | |