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