interface/wx/dataobj.h

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