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