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