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 const wxDataFormat wxFormatInvalid;
 122
 123
 124 /**
 125     @class wxDataObject
 126
 127     A wxDataObject represents data that can be copied to or from the clipboard,
 128     or dragged and dropped. The important thing about wxDataObject is that this
 129     is a 'smart' piece of data unlike 'dumb' data containers such as memory
 130     buffers or files. Being 'smart' here means that the data object itself
 131     should know what data formats it supports and how to render itself in each
 132     of its supported formats.
 133
 134     A supported format, incidentally, is exactly the format in which the data
 135     can be requested from a data object or from which the data object may be
 136     set. In the general case, an object may support different formats on
 137     'input' and 'output', i.e. it may be able to render itself in a given
 138     format but not be created from data on this format or vice versa.
 139     wxDataObject defines the wxDataObject::Direction enumeration type which
 140     distinguishes between them.
 141
 142     See wxDataFormat documentation for more about formats.
 143
 144     Not surprisingly, being 'smart' comes at a price of added complexity. This
 145     is reasonable for the situations when you really need to support multiple
 146     formats, but may be annoying if you only want to do something simple like
 147     cut and paste text.
 148
 149     To provide a solution for both cases, wxWidgets has two predefined classes
 150     which derive from wxDataObject: wxDataObjectSimple and
 151     wxDataObjectComposite. wxDataObjectSimple is the simplest wxDataObject
 152     possible and only holds data in a single format (such as HTML or text) and
 153     wxDataObjectComposite is the simplest way to implement a wxDataObject that
 154     does support multiple formats because it achieves this by simply holding
 155     several wxDataObjectSimple objects.
 156
 157     So, you have several solutions when you need a wxDataObject class (and you
 158     need one as soon as you want to transfer data via the clipboard or drag and
 159     drop):
 160
 161     -# Use one of the built-in classes.
 162         - You may use wxTextDataObject, wxBitmapDataObject wxFileDataObject,
 163           wxURLDataObject in the simplest cases when you only need to support
 164           one format and your data is either text, bitmap or list of files.
 165     -# Use wxDataObjectSimple
 166         - Deriving from wxDataObjectSimple is the simplest solution for custom
 167           data - you will only support one format and so probably won't be able
 168           to communicate with other programs, but data transfer will work in
 169           your program (or between different instances of it).
 170     -# Use wxDataObjectComposite
 171         - This is a simple but powerful solution which allows you to support
 172           any number of formats (either standard or custom if you combine it
 173           with the previous solution).
 174     -# Use wxDataObject directly
 175         - This is the solution for maximum flexibility and efficiency, but it
 176           is also the most difficult to implement.
 177
 178     Please note that the easiest way to use drag and drop and the clipboard
 179     with multiple formats is by using wxDataObjectComposite, but it is not the
 180     most efficient one as each wxDataObjectSimple would contain the whole data
 181     in its respective formats. Now imagine that you want to paste 200 pages of
 182     text in your proprietary format, as well as Word, RTF, HTML, Unicode and
 183     plain text to the clipboard and even today's computers are in trouble. For
 184     this case, you will have to derive from wxDataObject directly and make it
 185     enumerate its formats and provide the data in the requested format on
 186     demand.
 187
 188     Note that neither the GTK+ data transfer mechanisms for clipboard and drag
 189     and drop, nor OLE data transfer, @e copies any data until another application
 190     actually requests the data. This is in contrast to the 'feel' offered to
 191     the user of a program who would normally think that the data resides in the
 192     clipboard after having pressed 'Copy' - in reality it is only declared to
 193     be @e available.
 194
 195     You may also derive your own data object classes from wxCustomDataObject
 196     for user-defined types. The format of user-defined data is given as a
 197     mime-type string literal, such as "application/word" or "image/png". These
 198     strings are used as they are under Unix (so far only GTK+) to identify a
 199     format and are translated into their Windows equivalent under Win32 (using
 200     the OLE IDataObject for data exchange to and from the clipboard and for
 201     drag and drop). Note that the format string translation under Windows is
 202     not yet finished.
 203
 204     Each class derived directly from wxDataObject must override and implement
 205     all of its functions which are pure virtual in the base class. The data
 206     objects which only render their data or only set it (i.e. work in only one
 207     direction), should return 0 from GetFormatCount().
 208
 209     @beginWxPerlOnly
 210     This class is not currently usable from wxPerl; you may use
 211     Wx::PlDataObjectSimple instead.
 212     @endWxPerlOnly
 213
 214     @library{wxcore}
 215     @category{dnd}
 216
 217     @see @ref overview_dnd, @ref page_samples_dnd, wxFileDataObject,
 218          wxTextDataObject, wxBitmapDataObject, wxCustomDataObject,
 219          wxDropTarget, wxDropSource, wxTextDropTarget, wxFileDropTarget
 220 */
 221 class wxDataObject
 222 {
 223 public:
 224     enum Direction
 225     {
 226         /** Format is supported by GetDataHere() */
 227         Get  = 0x01,
 228
 229         /** Format is supported by SetData() */
 230         Set  = 0x02,
 231
 232         /**
 233             Format is supported by both GetDataHere() and SetData()
 234             (unused currently)
 235          */
 236         Both = 0x03
 237     };
 238
 239     /**
 240         Constructor.
 241     */
 242     wxDataObject();
 243
 244     /**
 245         Destructor.
 246     */
 247     virtual ~wxDataObject();
 248
 249     /**
 250         Copies all formats supported in the given direction @a dir to the array
 251         pointed to by @a formats.
 252         There must be enough space for GetFormatCount(dir) formats in it.
 253
 254         @beginWxPerlOnly
 255         In wxPerl this method only takes the @a dir parameter.  In scalar
 256         context it returns the first format in the list, in list
 257         context it returns a list containing all the supported
 258         formats.
 259         @endWxPerlOnly
 260     */
 261     virtual void GetAllFormats(wxDataFormat* formats,
 262                                Direction dir = Get) const = 0;
 263
 264     /**
 265         The method will write the data of the format @a format to the buffer
 266         @a buf.  In other words, copy the data from this object in the given
 267         format to the supplied buffer. Returns @true on success, @false on
 268         failure.
 269     */
 270     virtual bool GetDataHere(const wxDataFormat& format, void* buf) const = 0;
 271
 272     /**
 273         Returns the data size of the given format @a format.
 274     */
 275     virtual size_t GetDataSize(const wxDataFormat& format) const = 0;
 276
 277     /**
 278         Returns the number of available formats for rendering or setting the
 279         data.
 280     */
 281     virtual size_t GetFormatCount(Direction dir = Get) const = 0;
 282
 283     /**
 284         Returns the preferred format for either rendering the data (if @a dir
 285         is @c Get, its default value) or for setting it. Usually this will be
 286         the native format of the wxDataObject.
 287     */
 288     virtual wxDataFormat GetPreferredFormat(Direction dir = Get) const = 0;
 289
 290     /**
 291         Set the data in the format @a format of the length @a len provided in
 292         the buffer @a buf.  In other words, copy length bytes of data from the
 293         buffer to this data object.
 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     virtual bool SetData(size_t size, const void* data);
 383
 384     /**
 385         Like SetData(), but doesn't copy the data - instead the object takes
 386         ownership of the pointer.
 387     */
 388     void TakeData(size_t size, void* data);
 389 };
 390
 391
 392
 393 /**
 394     @class wxDataObjectComposite
 395
 396     wxDataObjectComposite is the simplest wxDataObject derivation which may be
 397     used to support multiple formats. It contains several wxDataObjectSimple
 398     objects and supports any format supported by at least one of them. Only one
 399     of these data objects is @e preferred (the first one if not explicitly
 400     changed by using the second parameter of Add()) and its format determines
 401     the preferred format of the composite data object as well.
 402
 403     See wxDataObject documentation for the reasons why you might prefer to use
 404     wxDataObject directly instead of wxDataObjectComposite for efficiency
 405     reasons.
 406
 407     This example shows how a composite data object capable of storing either
 408     bitmaps or file names (presumably of bitmap files) can be initialized and
 409     used:
 410
 411     @code
 412     MyDropTarget::MyDropTarget()
 413     {
 414         wxDataObjectComposite* dataobj = new wxDataObjectComposite();
 415         dataobj->Add(new wxBitmapDataObject(), true);
 416         dataobj->Add(new wxFileDataObject());
 417         SetDataObject(dataobj);
 418     }
 419
 420     wxDragResult MyDropTarget::OnData(wxCoord x, wxCoord y,
 421                                       wxDragResult defaultDragResult)
 422     {
 423         wxDragResult dragResult = wxDropTarget::OnData(x, y, defaultDragResult);
 424         if ( dragResult == defaultDragResult )
 425         {
 426             wxDataObjectComposite *
 427                 dataobjComp = static_cast<wxDataObjectComposite *>(GetDataObject());
 428
 429             wxDataFormat format = dataObjects->GetReceivedFormat();
 430             wxDataObject *dataobj = dataobjComp->GetObject(format);
 431             switch ( format.GetType() )
 432             {
 433                 case wxDF_BITMAP:
 434                     {
 435                         wxBitmapDataObject *
 436                             dataobjBitmap = static_cast<wxBitmapDataObject *>(dataobj);
 437
 438                         ... use dataobj->GetBitmap() ...
 439                     }
 440                     break;
 441
 442                 case wxDF_FILENAME:
 443                     {
 444                         wxFileDataObject *
 445                             dataobjFile = static_cast<wxFileDataObject *>(dataobj);
 446
 447                         ... use dataobj->GetFilenames() ...
 448                     }
 449                     break;
 450
 451                 default:
 452                     wxFAIL_MSG( "unexpected data object format" );
 453             }
 454         }
 455
 456         return dragResult;
 457     }
 458     @endcode
 459
 460     @library{wxcore}
 461     @category{dnd}
 462
 463     @see @ref overview_dnd, wxDataObject, wxDataObjectSimple, wxFileDataObject,
 464          wxTextDataObject, wxBitmapDataObject
 465 */
 466 class wxDataObjectComposite : public wxDataObject
 467 {
 468 public:
 469     /**
 470         The default constructor.
 471     */
 472     wxDataObjectComposite();
 473
 474     /**
 475         Adds the @a dataObject to the list of supported objects and it becomes
 476         the preferred object if @a preferred is @true.
 477     */
 478     void Add(wxDataObjectSimple* dataObject, bool preferred = false);
 479
 480     /**
 481         Report the format passed to the SetData() method.  This should be the
 482         format of the data object within the composite that received data from
 483         the clipboard or the DnD operation.  You can use this method to find
 484         out what kind of data object was received.
 485     */
 486     wxDataFormat GetReceivedFormat() const;
 487
 488     /**
 489         Returns the pointer to the object which supports the passed format for
 490         the specified direction.
 491
 492         @NULL is returned if the specified @a format is not supported for this
 493         direction @a dir. The returned pointer is owned by wxDataObjectComposite
 494         itself and shouldn't be deleted by caller.
 495
 496         @since 2.9.1
 497     */
 498     wxDataObjectSimple *GetObject(const wxDataFormat& format,
 499                                   wxDataObjectBase::Direction dir = Get) const;
 500 };
 501
 502
 503
 504 /**
 505     @class wxDataObjectSimple
 506
 507     This is the simplest possible implementation of the wxDataObject class.
 508     The data object of (a class derived from) this class only supports
 509     <strong>one format</strong>, so the number of virtual functions to
 510     be implemented is reduced.
 511
 512     Notice that this is still an abstract base class and cannot be used
 513     directly, it must be derived. The objects supporting rendering the data
 514     must override GetDataSize() and GetDataHere() while the objects which may
 515     be set must override SetData(). Of course, the objects supporting both
 516     operations must override all three methods.
 517
 518     @beginWxPerlOnly
 519     In wxPerl, you need to derive your data object class from
 520     Wx::PlDataObjectSimple.
 521     @endWxPerlOnly
 522
 523     @library{wxcore}
 524     @category{dnd}
 525
 526     @see @ref overview_dnd, @ref page_samples_dnd, wxFileDataObject,
 527          wxTextDataObject, wxBitmapDataObject
 528 */
 529 class wxDataObjectSimple : public wxDataObject
 530 {
 531 public:
 532     /**
 533         Constructor accepts the supported format (none by default) which may
 534         also be set later with SetFormat().
 535     */
 536     wxDataObjectSimple(const wxDataFormat& format = wxFormatInvalid);
 537
 538     /**
 539         Copy the data to the buffer, return @true on success.
 540         Must be implemented in the derived class if the object supports rendering
 541         its data.
 542     */
 543     virtual bool GetDataHere(void* buf) const;
 544
 545     /**
 546         Gets the size of our data. Must be implemented in the derived class if
 547         the object supports rendering its data.
 548     */
 549     virtual size_t GetDataSize() const;
 550
 551     /**
 552         Returns the (one and only one) format supported by this object.
 553         It is assumed that the format is supported in both directions.
 554     */
 555     const wxDataFormat& GetFormat() const;
 556
 557     /**
 558         Copy the data from the buffer, return @true on success.
 559         Must be implemented in the derived class if the object supports setting
 560         its data.
 561     */
 562     virtual bool SetData(size_t len, const void* buf);
 563
 564     /**
 565         Sets the supported format.
 566     */
 567     void SetFormat(const wxDataFormat& format);
 568 };
 569
 570
 571
 572 /**
 573     @class wxBitmapDataObject
 574
 575     wxBitmapDataObject is a specialization of wxDataObject for bitmap data. It
 576     can be used without change to paste data into the wxClipboard or a
 577     wxDropSource. A user may wish to derive a new class from this class for
 578     providing a bitmap on-demand in order to minimize memory consumption when
 579     offering data in several formats, such as a bitmap and GIF.
 580
 581     This class may be used as is, but GetBitmap() may be overridden to increase
 582     efficiency.
 583
 584     @library{wxcore}
 585     @category{dnd}
 586
 587     @see @ref overview_dnd, wxDataObject, wxDataObjectSimple, wxFileDataObject,
 588          wxTextDataObject, wxDataObject
 589 */
 590 class wxBitmapDataObject : public wxDataObjectSimple
 591 {
 592 public:
 593     /**
 594         Constructor, optionally passing a bitmap (otherwise use SetBitmap()
 595         later).
 596     */
 597     wxBitmapDataObject(const wxBitmap& bitmap = wxNullBitmap);
 598
 599     /**
 600         Returns the bitmap associated with the data object. You may wish to
 601         override this method when offering data on-demand, but this is not
 602         required by wxWidgets' internals. Use this method to get data in bitmap
 603         form from the wxClipboard.
 604     */
 605     virtual wxBitmap GetBitmap() const;
 606
 607     /**
 608         Sets the bitmap associated with the data object. This method is called
 609         when the data object receives data. Usually there will be no reason to
 610         override this function.
 611     */
 612     virtual void SetBitmap(const wxBitmap& bitmap);
 613 };
 614
 615
 616
 617 /**
 618     @class wxURLDataObject
 619
 620     wxURLDataObject is a wxDataObject containing an URL and can be used e.g.
 621     when you need to put an URL on or retrieve it from the clipboard:
 622
 623     @code
 624     wxTheClipboard->SetData(new wxURLDataObject(url));
 625     @endcode
 626
 627     @note This class is derived from wxDataObjectComposite on Windows rather
 628           than wxTextDataObject on all other platforms.
 629
 630     @library{wxcore}
 631     @category{dnd}
 632
 633     @see @ref overview_dnd, wxDataObject
 634 */
 635 class wxURLDataObject: public wxTextDataObject
 636 {
 637 public:
 638     /**
 639         Constructor, may be used to initialize the URL. If @a url is empty,
 640         SetURL() can be used later.
 641     */
 642     wxURLDataObject(const wxString& url = wxEmptyString);
 643
 644     /**
 645         Returns the URL stored by this object, as a string.
 646     */
 647     wxString GetURL() const;
 648
 649     /**
 650         Sets the URL stored by this object.
 651     */
 652     void SetURL(const wxString& url);
 653 };
 654
 655
 656 /**
 657     @class wxTextDataObject
 658
 659     wxTextDataObject is a specialization of wxDataObjectSimple for text data.
 660     It can be used without change to paste data into the wxClipboard or a
 661     wxDropSource. A user may wish to derive a new class from this class for
 662     providing text on-demand in order to minimize memory consumption when
 663     offering data in several formats, such as plain text and RTF because by
 664     default the text is stored in a string in this class, but it might as well
 665     be generated when requested. For this, GetTextLength() and GetText() will
 666     have to be overridden.
 667
 668     Note that if you already have the text inside a string, you will not
 669     achieve any efficiency gain by overriding these functions because copying
 670     wxStrings is already a very efficient operation (data is not actually
 671     copied because wxStrings are reference counted).
 672
 673     @library{wxcore}
 674     @category{dnd}
 675
 676     @see @ref overview_dnd, wxDataObject, wxDataObjectSimple, wxFileDataObject,
 677          wxBitmapDataObject
 678 */
 679 class wxTextDataObject : public wxDataObjectSimple
 680 {
 681 public:
 682     /**
 683         Constructor, may be used to initialise the text (otherwise SetText()
 684         should be used later).
 685     */
 686     wxTextDataObject(const wxString& text = wxEmptyString);
 687
 688     /**
 689         Returns the text associated with the data object. You may wish to
 690         override this method when offering data on-demand, but this is not
 691         required by wxWidgets' internals. Use this method to get data in text
 692         form from the wxClipboard.
 693     */
 694     virtual wxString GetText() const;
 695
 696     /**
 697         Returns the data size. By default, returns the size of the text data
 698         set in the constructor or using SetText(). This can be overridden to
 699         provide text size data on-demand. It is recommended to return the text
 700         length plus 1 for a trailing zero, but this is not strictly required.
 701     */
 702     virtual size_t GetTextLength() const;
 703
 704     /**
 705         Returns 2 under wxMac and wxGTK, where text data coming from the
 706         clipboard may be provided as ANSI (@c wxDF_TEXT) or as Unicode text
 707         (@c wxDF_UNICODETEXT, but only when @c wxUSE_UNICODE==1).
 708
 709         Returns 1 under other platforms (e.g. wxMSW) or when building in ANSI mode
 710         (@c wxUSE_UNICODE==0).
 711     */
 712     virtual size_t GetFormatCount(Direction dir = Get) const;
 713
 714     /**
 715         Returns the preferred format supported by this object.
 716
 717         This is @c wxDF_TEXT or @c wxDF_UNICODETEXT depending on the platform
 718         and from the build mode (i.e. from @c wxUSE_UNICODE).
 719     */
 720     const wxDataFormat& GetFormat() const;
 721
 722     /**
 723         Returns all the formats supported by wxTextDataObject.
 724
 725         Under wxMac and wxGTK they are @c wxDF_TEXT and @c wxDF_UNICODETEXT,
 726         under other ports returns only one of the two, depending on the build mode.
 727     */
 728     virtual void GetAllFormats(wxDataFormat* formats,
 729                                Direction dir = Get) const = 0;
 730
 731     /**
 732         Sets the text associated with the data object. This method is called
 733         when the data object receives the data and, by default, copies the text
 734         into the member variable. If you want to process the text on the fly
 735         you may wish to override this function.
 736     */
 737     virtual void SetText(const wxString& strText);
 738 };
 739
 740
 741
 742 /**
 743     @class wxFileDataObject
 744
 745     wxFileDataObject is a specialization of wxDataObject for file names. The
 746     program works with it just as if it were a list of absolute file names, but
 747     internally it uses the same format as Explorer and other compatible
 748     programs under Windows or GNOME/KDE filemanager under Unix which makes it
 749     possible to receive files from them using this class.
 750
 751     @warning Under all non-Windows platforms this class is currently
 752              "input-only", i.e. you can receive the files from another
 753              application, but copying (or dragging) file(s) from a wxWidgets
 754              application is not currently supported. PS: GTK2 should work as
 755              well.
 756
 757     @library{wxcore}
 758     @category{dnd}
 759
 760     @see wxDataObject, wxDataObjectSimple, wxTextDataObject,
 761          wxBitmapDataObject, wxDataObject
 762 */
 763 class wxFileDataObject : public wxDataObjectSimple
 764 {
 765 public:
 766     /**
 767         Constructor.
 768     */
 769     wxFileDataObject();
 770
 771     /**
 772         Adds a file to the file list represented by this data object (Windows only).
 773     */
 774     void AddFile(const wxString& file);
 775
 776     /**
 777         Returns the array of file names.
 778     */
 779     const wxArrayString& GetFilenames() const;
 780 };
 781
 782