interface/wx/dataobj.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        dataobj.h
   3 // Purpose:     interface of wx*DataObject
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     @class wxDataFormat
  12
  13     A wxDataFormat is an encapsulation of a platform-specific format handle
  14     which is used by the system for the clipboard and drag and drop operations.
  15     The applications are usually only interested in, for example, pasting data
  16     from the clipboard only if the data is in a format the program understands
  17     and a data format is something which uniquely identifies this format.
  18
  19     On the system level, a data format is usually just a number (@c CLIPFORMAT
  20     under Windows or @c Atom under X11, for example) and the standard formats
  21     are, indeed, just numbers which can be implicitly converted to wxDataFormat.
  22     The standard formats are:
  23
  24     @beginDefList
  25     @itemdef{wxDF_INVALID,
  26              An invalid format - used as default argument for functions taking
  27              a wxDataFormat argument sometimes.}
  28     @itemdef{wxDF_TEXT,
  29              Text format (wxString).}
  30     @itemdef{wxDF_BITMAP,
  31              A bitmap (wxBitmap).}
  32     @itemdef{wxDF_METAFILE,
  33              A metafile (wxMetafile, Windows only).}
  34     @itemdef{wxDF_FILENAME,
  35              A list of filenames.}
  36     @itemdef{wxDF_HTML,
  37              An HTML string. This is only valid when passed to
  38              wxSetClipboardData when compiled with Visual C++ in non-Unicode
  39              mode.}
  40     @endDefList
  41
  42     As mentioned above, these standard formats may be passed to any function
  43     taking wxDataFormat argument because wxDataFormat has an implicit
  44     conversion from them (or, to be precise from the type
  45     @c wxDataFormat::NativeFormat which is the type used by the underlying
  46     platform for data formats).
  47
  48     Aside the standard formats, the application may also use custom formats
  49     which are identified by their names (strings) and not numeric identifiers.
  50     Although internally custom format must be created (or @e registered) first,
  51     you shouldn't care about it because it is done automatically the first time
  52     the wxDataFormat object corresponding to a given format name is created.
  53     The only implication of this is that you should avoid having global
  54     wxDataFormat objects with non-default constructor because their
  55     constructors are executed before the program has time to perform all
  56     necessary initialisations and so an attempt to do clipboard format
  57     registration at this time will usually lead to a crash!
  58
  59     @library{wxbase}
  60     @category{dnd}
  61
  62     @see @ref overview_dnd, @ref page_samples_dnd, wxDataObject
  63 */
  64 class wxDataFormat
  65 {
  66 public:
  67     /**
  68         Constructs a data format object for one of the standard data formats or
  69         an empty data object (use SetType() or SetId() later in this case).
  70
  71         @beginWxPerlOnly
  72         In wxPerl use Wx::Bitmap->newNative(format).
  73         @endWxPerlOnly
  74     */
  75     wxDataFormat(wxDataFormatId format = wxDF_INVALID);
  76
  77     /**
  78         Constructs a data format object for a custom format identified by its
  79         name @a format.
  80
  81         @beginWxPerlOnly
  82         In wxPerl use Wx::Bitmap->newUser(format).
  83         @endWxPerlOnly
  84     */
  85     wxDataFormat(const wxString& format);
  86
  87     /**
  88         Returns the name of a custom format (this function will fail for a
  89         standard format).
  90     */
  91     wxString GetId() const;
  92
  93     /**
  94         Returns the platform-specific number identifying the format.
  95     */
  96     wxDataFormatId GetType() const;
  97
  98     /**
  99         Sets the format to be the custom format identified by the given name.
 100     */
 101     void SetId(const wxString& format);
 102
 103     /**
 104         Sets the format to the given value, which should be one of wxDF_XXX
 105         constants.
 106     */
 107     void SetType(wxDataFormatId type);
 108
 109     /**
 110         Returns @true if the formats are different.
 111     */
 112     bool operator !=(wxDataFormatId format) const;
 113
 114     /**
 115         Returns @true if the formats are equal.
 116     */
 117     bool operator ==(wxDataFormatId format) const;
 118 };
 119
 120
 121
 122 /**
 123     @class wxDataObject
 124
 125     A wxDataObject represents data that can be copied to or from the clipboard,
 126     or dragged and dropped. The important thing about wxDataObject is that this
 127     is a 'smart' piece of data unlike 'dumb' data containers such as memory
 128     buffers or files. Being 'smart' here means that the data object itself
 129     should know what data formats it supports and how to render itself in each
 130     of its supported formats.
 131
 132     A supported format, incidentally, is exactly the format in which the data
 133     can be requested from a data object or from which the data object may be
 134     set. In the general case, an object may support different formats on
 135     'input' and 'output', i.e. it may be able to render itself in a given
 136     format but not be created from data on this format or vice versa.
 137     wxDataObject defines the wxDataObject::Direction enumeration type which
 138     distinguishes between them.
 139
 140     See wxDataFormat documentation for more about formats.
 141
 142     Not surprisingly, being 'smart' comes at a price of added complexity. This
 143     is reasonable for the situations when you really need to support multiple
 144     formats, but may be annoying if you only want to do something simple like
 145     cut and paste text.
 146
 147     To provide a solution for both cases, wxWidgets has two predefined classes
 148     which derive from wxDataObject: wxDataObjectSimple and
 149     wxDataObjectComposite. wxDataObjectSimple is the simplest wxDataObject
 150     possible and only holds data in a single format (such as HTML or text) and
 151     wxDataObjectComposite is the simplest way to implement a wxDataObject that
 152     does support multiple formats because it achieves this by simply holding
 153     several wxDataObjectSimple objects.
 154
 155     So, you have several solutions when you need a wxDataObject class (and you
 156     need one as soon as you want to transfer data via the clipboard or drag and
 157     drop):
 158
 159     -# Use one of the built-in classes.
 160         - You may use wxTextDataObject, wxBitmapDataObject wxFileDataObject,
 161           wxURLDataObject in the simplest cases when you only need to support
 162           one format and your data is either text, bitmap or list of files.
 163     -# Use wxDataObjectSimple
 164         - Deriving from wxDataObjectSimple is the simplest solution for custom
 165           data - you will only support one format and so probably won't be able
 166           to communicate with other programs, but data transfer will work in
 167           your program (or between different instances of it).
 168     -# Use wxDataObjectComposite
 169         - This is a simple but powerful solution which allows you to support
 170           any number of formats (either standard or custom if you combine it
 171           with the previous solution).
 172     -# Use wxDataObject directly
 173         - This is the solution for maximum flexibility and efficiency, but it
 174           is also the most difficult to implement.
 175
 176     Please note that the easiest way to use drag and drop and the clipboard
 177     with multiple formats is by using wxDataObjectComposite, but it is not the
 178     most efficient one as each wxDataObjectSimple would contain the whole data
 179     in its respective formats. Now imagine that you want to paste 200 pages of
 180     text in your proprietary format, as well as Word, RTF, HTML, Unicode and
 181     plain text to the clipboard and even today's computers are in trouble. For
 182     this case, you will have to derive from wxDataObject directly and make it
 183     enumerate its formats and provide the data in the requested format on
 184     demand.
 185
 186     Note that neither the GTK+ data transfer mechanisms for clipboard and drag
 187     and drop, nor OLE data transfer, @e copies any data until another application
 188     actually requests the data. This is in contrast to the 'feel' offered to
 189     the user of a program who would normally think that the data resides in the
 190     clipboard after having pressed 'Copy' - in reality it is only declared to
 191     be @e available.
 192
 193     You may also derive your own data object classes from wxCustomDataObject
 194     for user-defined types. The format of user-defined data is given as a
 195     mime-type string literal, such as "application/word" or "image/png". These
 196     strings are used as they are under Unix (so far only GTK+) to identify a
 197     format and are translated into their Windows equivalent under Win32 (using
 198     the OLE IDataObject for data exchange to and from the clipboard and for
 199     drag and drop). Note that the format string translation under Windows is
 200     not yet finished.
 201
 202     Each class derived directly from wxDataObject must override and implement
 203     all of its functions which are pure virtual in the base class. The data
 204     objects which only render their data or only set it (i.e. work in only one
 205     direction), should return 0 from GetFormatCount().
 206
 207     @beginWxPythonOnly
 208     At this time this class is not directly usable from wxPython. Derive a
 209     class from wxPyDataObjectSimple() instead.
 210     @endWxPythonOnly
 211
 212     @beginWxPerlOnly
 213     This class is not currently usable from wxPerl; you may use
 214     Wx::PlDataObjectSimple instead.
 215     @endWxPerlOnly
 216
 217     @library{wxcore}
 218     @category{dnd}
 219
 220     @see @ref overview_dnd, @ref page_samples_dnd, wxFileDataObject,
 221          wxTextDataObject, wxBitmapDataObject, wxCustomDataObject,
 222          wxDropTarget, wxDropSource, wxTextDropTarget, wxFileDropTarget
 223 */
 224 class wxDataObject
 225 {
 226 public:
 227     enum Direction
 228     {
 229         /** Format is supported by GetDataHere() */
 230         Get  = 0x01,
 231
 232         /** Format is supported by SetData() */
 233         Set  = 0x02,
 234
 235         /**
 236             Format is supported by both GetDataHere() and SetData()
 237             (unused currently)
 238          */
 239         Both = 0x03
 240     };
 241
 242     /**
 243         Constructor.
 244     */
 245     wxDataObject();
 246
 247     /**
 248         Destructor.
 249     */
 250     virtual ~wxDataObject();
 251
 252     /**
 253         Copies all formats supported in the given direction @a dir to the array
 254         pointed to by @a formats.
 255         There must be enough space for GetFormatCount(dir) formats in it.
 256
 257         @beginWxPerlOnly
 258         In wxPerl this method only takes the @a dir parameter.  In scalar
 259         context it returns the first format in the list, in list
 260         context it returns a list containing all the supported
 261         formats.
 262         @endWxPerlOnly
 263     */
 264     virtual void GetAllFormats(wxDataFormat* formats,
 265                                Direction dir = Get) const = 0;
 266
 267     /**
 268         The method will write the data of the format @a format in the buffer
 269         @a buf and return @true on success, @false on failure.
 270     */
 271     virtual bool GetDataHere(const wxDataFormat& format, void* buf) const = 0;
 272
 273     /**
 274         Returns the data size of the given format @a format.
 275     */
 276     virtual size_t GetDataSize(const wxDataFormat& format) const = 0;
 277
 278     /**
 279         Returns the number of available formats for rendering or setting the
 280         data.
 281     */
 282     virtual size_t GetFormatCount(Direction dir = Get) const = 0;
 283
 284     /**
 285         Returns the preferred format for either rendering the data (if @a dir
 286         is @c Get, its default value) or for setting it. Usually this will be
 287         the native format of the wxDataObject.
 288     */
 289     virtual wxDataFormat GetPreferredFormat(Direction dir = Get) const = 0;
 290
 291     /**
 292         Set the data in the format @a format of the length @a len provided in
 293         the buffer @a buf.
 294
 295         @param format
 296             The format for which to set the data.
 297         @param len
 298             The size of data in bytes.
 299         @param buf
 300             Non-@NULL pointer to the data.
 301         @return
 302             @true on success, @false on failure.
 303     */
 304     virtual bool SetData(const wxDataFormat& format, size_t len, const void* buf);
 305
 306     /**
 307        Returns true if this format is supported.
 308     */
 309     bool IsSupported(const wxDataFormat& format, Direction dir = Get) const;
 310 };
 311
 312
 313 /**
 314     @class wxCustomDataObject
 315
 316     wxCustomDataObject is a specialization of wxDataObjectSimple for some
 317     application-specific data in arbitrary (either custom or one of the
 318     standard ones). The only restriction is that it is supposed that this data
 319     can be copied bitwise (i.e. with @c memcpy()), so it would be a bad idea to
 320     make it contain a C++ object (though C struct is fine).
 321
 322     By default, wxCustomDataObject stores the data inside in a buffer. To put
 323     the data into the buffer you may use either SetData() or TakeData()
 324     depending on whether you want the object to make a copy of data or not.
 325
 326     This class may be used as is, but if you don't want store the data inside
 327     the object but provide it on demand instead, you should override GetSize(),
 328     GetData() and SetData() (or may be only the first two or only the last one
 329     if you only allow reading/writing the data).
 330
 331     @library{wxcore}
 332     @category{dnd}
 333
 334     @see wxDataObject
 335 */
 336 class wxCustomDataObject : public wxDataObjectSimple
 337 {
 338 public:
 339     /**
 340         The constructor accepts a @a format argument which specifies the
 341         (single) format supported by this object. If it isn't set here,
 342         wxDataObjectSimple::SetFormat() should be used.
 343     */
 344     wxCustomDataObject(const wxDataFormat& format = wxFormatInvalid);
 345
 346     /**
 347         The destructor will free the data held by the object. Notice that
 348         although it calls the virtual Free() function, the base class version
 349         will always be called (C++ doesn't allow calling virtual functions from
 350         constructors or destructors), so if you override Free(), you should
 351         override the destructor in your class as well (which would probably
 352         just call the derived class' version of Free()).
 353     */
 354     virtual ~wxCustomDataObject();
 355
 356     /**
 357         This function is called to allocate @a size bytes of memory from
 358         SetData(). The default version just uses the operator new.
 359     */
 360     virtual void* Alloc(size_t size);
 361
 362     /**
 363         This function is called when the data is freed, you may override it to
 364         anything you want (or may be nothing at all). The default version calls
 365         operator delete[] on the data.
 366     */
 367     virtual void Free();
 368
 369     /**
 370         Returns a pointer to the data.
 371     */
 372     virtual void* GetData() const;
 373
 374     /**
 375         Returns the data size in bytes.
 376     */
 377     virtual size_t GetSize() const;
 378
 379     /**
 380         Set the data. The data object will make an internal copy.
 381
 382         @beginWxPythonOnly
 383         This method expects a string in wxPython. You can pass nearly any
 384         object by pickling it first.
 385         @endWxPythonOnly
 386     */
 387     virtual bool SetData(size_t size, const void* data);
 388
 389     /**
 390         Like SetData(), but doesn't copy the data - instead the object takes
 391         ownership of the pointer.
 392
 393         @beginWxPythonOnly
 394         This method expects a string in wxPython. You can pass nearly any
 395         object by pickling it first.
 396         @endWxPythonOnly
 397     */
 398     void TakeData(size_t size, void* data);
 399 };
 400
 401
 402
 403 /**
 404     @class wxDataObjectComposite
 405
 406     wxDataObjectComposite is the simplest wxDataObject derivation which may be
 407     used to support multiple formats. It contains several wxDataObjectSimple
 408     objects and supports any format supported by at least one of them. Only one
 409     of these data objects is @e preferred (the first one if not explicitly
 410     changed by using the second parameter of Add()) and its format determines
 411     the preferred format of the composite data object as well.
 412
 413     See wxDataObject documentation for the reasons why you might prefer to use
 414     wxDataObject directly instead of wxDataObjectComposite for efficiency
 415     reasons.
 416
 417     This example shows how a composite data object capable of storing either
 418     bitmaps or file names (presumably of bitmap files) can be initialized and
 419     used:
 420
 421     @code
 422     MyDropTarget::MyDropTarget()
 423     {
 424         wxDataObjectComposite* dataobj = new wxDataObjectComposite();
 425         dataobj->Add(new wxBitmapDataObject(), true);
 426         dataobj->Add(new wxFileDataObject());
 427         SetDataObject(dataobj);
 428     }
 429
 430     wxDragResult MyDropTarget::OnData(wxCoord x, wxCoord y,
 431                                       wxDragResult defaultDragResult)
 432     {
 433         wxDragResult dragResult = wxDropTarget::OnData(x, y, defaultDragResult);
 434         if ( dragResult == defaultDragResult )
 435         {
 436             wxDataObjectComposite *
 437                 dataobjComp = static_cast<wxDataObjectComposite *>(GetDataObject());
 438
 439             wxDataFormat format = dataObjects->GetReceivedFormat();
 440             wxDataObject *dataobj = dataobjComp->GetObject(format);
 441             switch ( format.GetType() )
 442             {
 443                 case wxDF_BITMAP:
 444                     {
 445                         wxBitmapDataObject *
 446                             dataobjBitmap = static_cast<wxBitmapDataObject *>(dataobj);
 447
 448                         ... use dataobj->GetBitmap() ...
 449                     }
 450                     break;
 451
 452                 case wxDF_FILENAME:
 453                     {
 454                         wxFileDataObject *
 455                             dataobjFile = static_cast<wxFileDataObject *>(dataobj);
 456
 457                         ... use dataobj->GetFilenames() ...
 458                     }
 459                     break;
 460
 461                 default:
 462                     wxFAIL_MSG( "unexpected data object format" );
 463             }
 464         }
 465
 466         return dragResult;
 467     }
 468     @endcode
 469
 470     @library{wxcore}
 471     @category{dnd}
 472
 473     @see @ref overview_dnd, wxDataObject, wxDataObjectSimple, wxFileDataObject,
 474          wxTextDataObject, wxBitmapDataObject
 475 */
 476 class wxDataObjectComposite : public wxDataObject
 477 {
 478 public:
 479     /**
 480         The default constructor.
 481     */
 482     wxDataObjectComposite();
 483
 484     /**
 485         Adds the @a dataObject to the list of supported objects and it becomes
 486         the preferred object if @a preferred is @true.
 487     */
 488     void Add(wxDataObjectSimple* dataObject, bool preferred = false);
 489
 490     /**
 491         Report the format passed to the SetData() method.  This should be the
 492         format of the data object within the composite that received data from
 493         the clipboard or the DnD operation.  You can use this method to find
 494         out what kind of data object was received.
 495     */
 496     wxDataFormat GetReceivedFormat() const;
 497
 498     /**
 499         Returns the pointer to the object which supports the passed format for
 500         the specified direction.
 501
 502         @NULL is returned if the specified @a format is not supported for this
 503         direction @a dir. The returned pointer is owned by wxDataObjectComposite
 504         itself and shouldn't be deleted by caller.
 505
 506         @since 2.9.1
 507     */
 508     wxDataObjectSimple *GetObject(const wxDataFormat& format,
 509                                   wxDataObjectBase::Direction dir = Get) const;
 510 };
 511
 512
 513
 514 /**
 515     @class wxDataObjectSimple
 516
 517     This is the simplest possible implementation of the wxDataObject class.
 518     The data object of (a class derived from) this class only supports
 519     <strong>one format</strong>, so the number of virtual functions to
 520     be implemented is reduced.
 521
 522     Notice that this is still an abstract base class and cannot be used
 523     directly, it must be derived. The objects supporting rendering the data
 524     must override GetDataSize() and GetDataHere() while the objects which may
 525     be set must override SetData(). Of course, the objects supporting both
 526     operations must override all three methods.
 527
 528     @beginWxPythonOnly
 529     If you wish to create a derived wxDataObjectSimple class in wxPython you
 530     should derive the class from wxPyDataObjectSimple in order to get
 531     Python-aware capabilities for the various virtual methods.
 532     @endWxPythonOnly
 533
 534     @beginWxPerlOnly
 535     In wxPerl, you need to derive your data object class from
 536     Wx::PlDataObjectSimple.
 537     @endWxPerlOnly
 538
 539     @library{wxcore}
 540     @category{dnd}
 541
 542     @see @ref overview_dnd, @ref page_samples_dnd, wxFileDataObject,
 543          wxTextDataObject, wxBitmapDataObject
 544 */
 545 class wxDataObjectSimple : public wxDataObject
 546 {
 547 public:
 548     /**
 549         Constructor accepts the supported format (none by default) which may
 550         also be set later with SetFormat().
 551     */
 552     wxDataObjectSimple(const wxDataFormat& format = wxFormatInvalid);
 553
 554     /**
 555         Copy the data to the buffer, return @true on success.
 556         Must be implemented in the derived class if the object supports rendering
 557         its data.
 558
 559         @beginWxPythonOnly
 560         When implementing this method in wxPython, no additional parameters are
 561         required and the data should be returned from the method as a string.
 562         @endWxPythonOnly
 563     */
 564     virtual bool GetDataHere(void* buf) const;
 565
 566     /**
 567         Gets the size of our data. Must be implemented in the derived class if
 568         the object supports rendering its data.
 569     */
 570     virtual size_t GetDataSize() const;
 571
 572     /**
 573         Returns the (one and only one) format supported by this object.
 574         It is assumed that the format is supported in both directions.
 575     */
 576     const wxDataFormat& GetFormat() const;
 577
 578     /**
 579         Copy the data from the buffer, return @true on success.
 580         Must be implemented in the derived class if the object supports setting
 581         its data.
 582
 583         @beginWxPythonOnly
 584         When implementing this method in wxPython, the data comes as a single
 585         string parameter rather than the two shown here.
 586         @endWxPythonOnly
 587     */
 588     virtual bool SetData(size_t len, const void* buf);
 589
 590     /**
 591         Sets the supported format.
 592     */
 593     void SetFormat(const wxDataFormat& format);
 594 };
 595
 596
 597
 598 /**
 599     @class wxBitmapDataObject
 600
 601     wxBitmapDataObject is a specialization of wxDataObject for bitmap data. It
 602     can be used without change to paste data into the wxClipboard or a
 603     wxDropSource. A user may wish to derive a new class from this class for
 604     providing a bitmap on-demand in order to minimize memory consumption when
 605     offering data in several formats, such as a bitmap and GIF.
 606
 607     This class may be used as is, but GetBitmap() may be overridden to increase
 608     efficiency.
 609
 610     @beginWxPythonOnly
 611     If you wish to create a derived wxBitmapDataObject class in wxPython you
 612     should derive the class from wxPyBitmapDataObject in order to get
 613     Python-aware capabilities for the various virtual methods.
 614     @endWxPythonOnly
 615
 616     @library{wxcore}
 617     @category{dnd}
 618
 619     @see @ref overview_dnd, wxDataObject, wxDataObjectSimple, wxFileDataObject,
 620          wxTextDataObject, wxDataObject
 621 */
 622 class wxBitmapDataObject : public wxDataObjectSimple
 623 {
 624 public:
 625     /**
 626         Constructor, optionally passing a bitmap (otherwise use SetBitmap()
 627         later).
 628     */
 629     wxBitmapDataObject(const wxBitmap& bitmap = wxNullBitmap);
 630
 631     /**
 632         Returns the bitmap associated with the data object. You may wish to
 633         override this method when offering data on-demand, but this is not
 634         required by wxWidgets' internals. Use this method to get data in bitmap
 635         form from the wxClipboard.
 636     */
 637     virtual wxBitmap GetBitmap() const;
 638
 639     /**
 640         Sets the bitmap associated with the data object. This method is called
 641         when the data object receives data. Usually there will be no reason to
 642         override this function.
 643     */
 644     virtual void SetBitmap(const wxBitmap& bitmap);
 645 };
 646
 647
 648
 649 /**
 650     @class wxURLDataObject
 651
 652     wxURLDataObject is a wxDataObject containing an URL and can be used e.g.
 653     when you need to put an URL on or retrieve it from the clipboard:
 654
 655     @code
 656     wxTheClipboard->SetData(new wxURLDataObject(url));
 657     @endcode
 658
 659     @note This class is derived from wxDataObjectComposite on Windows rather
 660           than wxTextDataObject on all other platforms.
 661
 662     @library{wxcore}
 663     @category{dnd}
 664
 665     @see @ref overview_dnd, wxDataObject
 666 */
 667 class wxURLDataObject: public wxTextDataObject
 668 {
 669 public:
 670     /**
 671         Constructor, may be used to initialize the URL. If @a url is empty,
 672         SetURL() can be used later.
 673     */
 674     wxURLDataObject(const wxString& url = wxEmptyString);
 675
 676     /**
 677         Returns the URL stored by this object, as a string.
 678     */
 679     wxString GetURL() const;
 680
 681     /**
 682         Sets the URL stored by this object.
 683     */
 684     void SetURL(const wxString& url);
 685 };
 686
 687
 688 /**
 689     @class wxTextDataObject
 690
 691     wxTextDataObject is a specialization of wxDataObjectSimple for text data.
 692     It can be used without change to paste data into the wxClipboard or a
 693     wxDropSource. A user may wish to derive a new class from this class for
 694     providing text on-demand in order to minimize memory consumption when
 695     offering data in several formats, such as plain text and RTF because by
 696     default the text is stored in a string in this class, but it might as well
 697     be generated when requested. For this, GetTextLength() and GetText() will
 698     have to be overridden.
 699
 700     Note that if you already have the text inside a string, you will not
 701     achieve any efficiency gain by overriding these functions because copying
 702     wxStrings is already a very efficient operation (data is not actually
 703     copied because wxStrings are reference counted).
 704
 705     @beginWxPythonOnly
 706     If you wish to create a derived wxTextDataObject class in wxPython you
 707     should derive the class from wxPyTextDataObject in order to get
 708     Python-aware capabilities for the various virtual methods.
 709     @endWxPythonOnly
 710
 711     @library{wxcore}
 712     @category{dnd}
 713
 714     @see @ref overview_dnd, wxDataObject, wxDataObjectSimple, wxFileDataObject,
 715          wxBitmapDataObject
 716 */
 717 class wxTextDataObject : public wxDataObjectSimple
 718 {
 719 public:
 720     /**
 721         Constructor, may be used to initialise the text (otherwise SetText()
 722         should be used later).
 723     */
 724     wxTextDataObject(const wxString& text = wxEmptyString);
 725
 726     /**
 727         Returns the text associated with the data object. You may wish to
 728         override this method when offering data on-demand, but this is not
 729         required by wxWidgets' internals. Use this method to get data in text
 730         form from the wxClipboard.
 731     */
 732     virtual wxString GetText() const;
 733
 734     /**
 735         Returns the data size. By default, returns the size of the text data
 736         set in the constructor or using SetText(). This can be overridden to
 737         provide text size data on-demand. It is recommended to return the text
 738         length plus 1 for a trailing zero, but this is not strictly required.
 739     */
 740     virtual size_t GetTextLength() const;
 741
 742     /**
 743         Returns 2 under wxMac and wxGTK, where text data coming from the
 744         clipboard may be provided as ANSI (@c wxDF_TEXT) or as Unicode text
 745         (@c wxDF_UNICODETEXT, but only when @c wxUSE_UNICODE==1).
 746
 747         Returns 1 under other platforms (e.g. wxMSW) or when building in ANSI mode
 748         (@c wxUSE_UNICODE==0).
 749     */
 750     virtual size_t GetFormatCount(Direction dir = Get) const;
 751
 752     /**
 753         Returns the preferred format supported by this object.
 754
 755         This is @c wxDF_TEXT or @c wxDF_UNICODETEXT depending on the platform
 756         and from the build mode (i.e. from @c wxUSE_UNICODE).
 757     */
 758     const wxDataFormat& GetFormat() const;
 759
 760     /**
 761         Returns all the formats supported by wxTextDataObject.
 762
 763         Under wxMac and wxGTK they are @c wxDF_TEXT and @c wxDF_UNICODETEXT,
 764         under other ports returns only one of the two, depending on the build mode.
 765     */
 766     virtual void GetAllFormats(wxDataFormat* formats,
 767                                Direction dir = Get) const = 0;
 768
 769     /**
 770         Sets the text associated with the data object. This method is called
 771         when the data object receives the data and, by default, copies the text
 772         into the member variable. If you want to process the text on the fly
 773         you may wish to override this function.
 774     */
 775     virtual void SetText(const wxString& strText);
 776 };
 777
 778
 779
 780 /**
 781     @class wxFileDataObject
 782
 783     wxFileDataObject is a specialization of wxDataObject for file names. The
 784     program works with it just as if it were a list of absolute file names, but
 785     internally it uses the same format as Explorer and other compatible
 786     programs under Windows or GNOME/KDE filemanager under Unix which makes it
 787     possible to receive files from them using this class.
 788
 789     @warning Under all non-Windows platforms this class is currently
 790              "input-only", i.e. you can receive the files from another
 791              application, but copying (or dragging) file(s) from a wxWidgets
 792              application is not currently supported. PS: GTK2 should work as
 793              well.
 794
 795     @library{wxcore}
 796     @category{dnd}
 797
 798     @see wxDataObject, wxDataObjectSimple, wxTextDataObject,
 799          wxBitmapDataObject, wxDataObject
 800 */
 801 class wxFileDataObject : public wxDataObjectSimple
 802 {
 803 public:
 804     /**
 805         Constructor.
 806     */
 807     wxFileDataObject();
 808
 809     /**
 810         Adds a file to the file list represented by this data object (Windows only).
 811     */
 812     void AddFile(const wxString& file);
 813
 814     /**
 815         Returns the array of file names.
 816     */
 817     const wxArrayString& GetFilenames() const;
 818 };
 819
 820