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         @param format
 281             The format for which to set the data.
 282         @param len
 283             The size of data in bytes.
 284         @param buf
 285             Non-@NULL pointer to the data.
 286         @return
 287             @true on success, @false on failure.
 288     */
 289     virtual bool SetData(const wxDataFormat& format, size_t len, const void* buf);
 290
 291     /**
 292        Returns true if this format is supported.
 293     */
 294     bool IsSupported(const wxDataFormat& format, Direction dir = Get) const;
 295 };
 296
 297
 298 /**
 299     @class wxCustomDataObject
 300
 301     wxCustomDataObject is a specialization of wxDataObjectSimple for some
 302     application-specific data in arbitrary (either custom or one of the
 303     standard ones). The only restriction is that it is supposed that this data
 304     can be copied bitwise (i.e. with @c memcpy()), so it would be a bad idea to
 305     make it contain a C++ object (though C struct is fine).
 306
 307     By default, wxCustomDataObject stores the data inside in a buffer. To put
 308     the data into the buffer you may use either SetData() or TakeData()
 309     depending on whether you want the object to make a copy of data or not.
 310
 311     This class may be used as is, but if you don't want store the data inside
 312     the object but provide it on demand instead, you should override GetSize(),
 313     GetData() and SetData() (or may be only the first two or only the last one
 314     if you only allow reading/writing the data).
 315
 316     @library{wxcore}
 317     @category{dnd}
 318
 319     @see wxDataObject
 320 */
 321 class wxCustomDataObject : public wxDataObjectSimple
 322 {
 323 public:
 324     /**
 325         The constructor accepts a @a format argument which specifies the
 326         (single) format supported by this object. If it isn't set here,
 327         wxDataObjectSimple::SetFormat() should be used.
 328     */
 329     wxCustomDataObject(const wxDataFormat& format = wxFormatInvalid);
 330
 331     /**
 332         The destructor will free the data held by the object. Notice that
 333         although it calls the virtual Free() function, the base class version
 334         will always be called (C++ doesn't allow calling virtual functions from
 335         constructors or destructors), so if you override Free(), you should
 336         override the destructor in your class as well (which would probably
 337         just call the derived class' version of Free()).
 338     */
 339     virtual ~wxCustomDataObject();
 340
 341     /**
 342         This function is called to allocate @a size bytes of memory from
 343         SetData(). The default version just uses the operator new.
 344     */
 345     virtual void* Alloc(size_t size);
 346
 347     /**
 348         This function is called when the data is freed, you may override it to
 349         anything you want (or may be nothing at all). The default version calls
 350         operator delete[] on the data.
 351     */
 352     virtual void Free();
 353
 354     /**
 355         Returns a pointer to the data.
 356     */
 357     virtual void* GetData() const;
 358
 359     /**
 360         Returns the data size in bytes.
 361     */
 362     virtual size_t GetSize() const;
 363
 364     /**
 365         Set the data. The data object will make an internal copy.
 366
 367         @beginWxPythonOnly
 368         This method expects a string in wxPython. You can pass nearly any
 369         object by pickling it first.
 370         @endWxPythonOnly
 371     */
 372     virtual bool SetData(size_t size, const void* data);
 373
 374     /**
 375         Like SetData(), but doesn't copy the data - instead the object takes
 376         ownership of the pointer.
 377
 378         @beginWxPythonOnly
 379         This method expects a string in wxPython. You can pass nearly any
 380         object by pickling it first.
 381         @endWxPythonOnly
 382     */
 383     void TakeData(size_t size, void* data);
 384 };
 385
 386
 387
 388 /**
 389     @class wxDataObjectComposite
 390
 391     wxDataObjectComposite is the simplest wxDataObject derivation which may be
 392     used to support multiple formats. It contains several wxDataObjectSimple
 393     objects and supports any format supported by at least one of them. Only one
 394     of these data objects is @e preferred (the first one if not explicitly
 395     changed by using the second parameter of Add()) and its format determines
 396     the preferred format of the composite data object as well.
 397
 398     See wxDataObject documentation for the reasons why you might prefer to use
 399     wxDataObject directly instead of wxDataObjectComposite for efficiency
 400     reasons.
 401
 402     @library{wxcore}
 403     @category{dnd}
 404
 405     @see @ref overview_dnd, wxDataObject, wxDataObjectSimple, wxFileDataObject,
 406          wxTextDataObject, wxBitmapDataObject
 407 */
 408 class wxDataObjectComposite : public wxDataObject
 409 {
 410 public:
 411     /**
 412         The default constructor.
 413     */
 414     wxDataObjectComposite();
 415
 416     /**
 417         Adds the @a dataObject to the list of supported objects and it becomes
 418         the preferred object if @a preferred is @true.
 419     */
 420     void Add(wxDataObjectSimple* dataObject, bool preferred = false);
 421
 422     /**
 423         Report the format passed to the SetData() method.  This should be the
 424         format of the data object within the composite that recieved data from
 425         the clipboard or the DnD operation.  You can use this method to find
 426         out what kind of data object was recieved.
 427     */
 428     wxDataFormat GetReceivedFormat() const;
 429 };
 430
 431
 432
 433 /**
 434     @class wxDataObjectSimple
 435
 436     This is the simplest possible implementation of the wxDataObject class.
 437     The data object of (a class derived from) this class only supports
 438     <strong>one format</strong>, so the number of virtual functions to
 439     be implemented is reduced.
 440
 441     Notice that this is still an abstract base class and cannot be used
 442     directly, it must be derived. The objects supporting rendering the data
 443     must override GetDataSize() and GetDataHere() while the objects which may
 444     be set must override SetData(). Of course, the objects supporting both
 445     operations must override all three methods.
 446
 447     @beginWxPythonOnly
 448     If you wish to create a derived wxDataObjectSimple class in wxPython you
 449     should derive the class from wxPyDataObjectSimple in order to get
 450     Python-aware capabilities for the various virtual methods.
 451     @endWxPythonOnly
 452
 453     @beginWxPerlOnly
 454     In wxPerl, you need to derive your data object class from
 455     Wx::PlDataObjectSimple.
 456     @endWxPerlOnly
 457
 458     @library{wxcore}
 459     @category{dnd}
 460
 461     @see @ref overview_dnd, @ref page_samples_dnd, wxFileDataObject,
 462          wxTextDataObject, wxBitmapDataObject
 463 */
 464 class wxDataObjectSimple : public wxDataObject
 465 {
 466 public:
 467     /**
 468         Constructor accepts the supported format (none by default) which may
 469         also be set later with SetFormat().
 470     */
 471     wxDataObjectSimple(const wxDataFormat& format = wxFormatInvalid);
 472
 473     /**
 474         Copy the data to the buffer, return @true on success.
 475         Must be implemented in the derived class if the object supports rendering
 476         its data.
 477
 478         @beginWxPythonOnly
 479         When implementing this method in wxPython, no additional parameters are
 480         required and the data should be returned from the method as a string.
 481         @endWxPythonOnly
 482     */
 483     virtual bool GetDataHere(void* buf) const;
 484
 485     /**
 486         Gets the size of our data. Must be implemented in the derived class if
 487         the object supports rendering its data.
 488     */
 489     virtual size_t GetDataSize() const;
 490
 491     /**
 492         Returns the (one and only one) format supported by this object.
 493         It is assumed that the format is supported in both directions.
 494     */
 495     const wxDataFormat& GetFormat() const;
 496
 497     /**
 498         Copy the data from the buffer, return @true on success.
 499         Must be implemented in the derived class if the object supports setting
 500         its data.
 501
 502         @beginWxPythonOnly
 503         When implementing this method in wxPython, the data comes as a single
 504         string parameter rather than the two shown here.
 505         @endWxPythonOnly
 506     */
 507     virtual bool SetData(size_t len, const void* buf);
 508
 509     /**
 510         Sets the supported format.
 511     */
 512     void SetFormat(const wxDataFormat& format);
 513 };
 514
 515
 516
 517 /**
 518     @class wxBitmapDataObject
 519
 520     wxBitmapDataObject is a specialization of wxDataObject for bitmap data. It
 521     can be used without change to paste data into the wxClipboard or a
 522     wxDropSource. A user may wish to derive a new class from this class for
 523     providing a bitmap on-demand in order to minimize memory consumption when
 524     offering data in several formats, such as a bitmap and GIF.
 525
 526     This class may be used as is, but GetBitmap() may be overridden to increase
 527     efficiency.
 528
 529     @beginWxPythonOnly
 530     If you wish to create a derived wxBitmapDataObject class in wxPython you
 531     should derive the class from wxPyBitmapDataObject in order to get
 532     Python-aware capabilities for the various virtual methods.
 533     @endWxPythonOnly
 534
 535     @library{wxcore}
 536     @category{dnd}
 537
 538     @see @ref overview_dnd, wxDataObject, wxDataObjectSimple, wxFileDataObject,
 539          wxTextDataObject, wxDataObject
 540 */
 541 class wxBitmapDataObject : public wxDataObjectSimple
 542 {
 543 public:
 544     /**
 545         Constructor, optionally passing a bitmap (otherwise use SetBitmap()
 546         later).
 547     */
 548     wxBitmapDataObject(const wxBitmap& bitmap = wxNullBitmap);
 549
 550     /**
 551         Returns the bitmap associated with the data object. You may wish to
 552         override this method when offering data on-demand, but this is not
 553         required by wxWidgets' internals. Use this method to get data in bitmap
 554         form from the wxClipboard.
 555     */
 556     virtual wxBitmap GetBitmap() const;
 557
 558     /**
 559         Sets the bitmap associated with the data object. This method is called
 560         when the data object receives data. Usually there will be no reason to
 561         override this function.
 562     */
 563     virtual void SetBitmap(const wxBitmap& bitmap);
 564 };
 565
 566
 567
 568 /**
 569     @class wxURLDataObject
 570
 571     wxURLDataObject is a wxDataObject containing an URL and can be used e.g.
 572     when you need to put an URL on or retrieve it from the clipboard:
 573
 574     @code
 575     wxTheClipboard->SetData(new wxURLDataObject(url));
 576     @endcode
 577
 578     @note This class is derived from wxDataObjectComposite on Windows rather
 579           than wxTextDataObject on all other platforms.
 580
 581     @library{wxcore}
 582     @category{dnd}
 583
 584     @see @ref overview_dnd, wxDataObject
 585 */
 586 class wxURLDataObject: public wxTextDataObject
 587 {
 588 public:
 589     /**
 590         Constructor, may be used to initialize the URL. If @a url is empty,
 591         SetURL() can be used later.
 592     */
 593     wxURLDataObject(const wxString& url = wxEmptyString);
 594
 595     /**
 596         Returns the URL stored by this object, as a string.
 597     */
 598     wxString GetURL() const;
 599
 600     /**
 601         Sets the URL stored by this object.
 602     */
 603     void SetURL(const wxString& url);
 604 };
 605
 606
 607 /**
 608     @class wxTextDataObject
 609
 610     wxTextDataObject is a specialization of wxDataObjectSimple for text data.
 611     It can be used without change to paste data into the wxClipboard or a
 612     wxDropSource. A user may wish to derive a new class from this class for
 613     providing text on-demand in order to minimize memory consumption when
 614     offering data in several formats, such as plain text and RTF because by
 615     default the text is stored in a string in this class, but it might as well
 616     be generated when requested. For this, GetTextLength() and GetText() will
 617     have to be overridden.
 618
 619     Note that if you already have the text inside a string, you will not
 620     achieve any efficiency gain by overriding these functions because copying
 621     wxStrings is already a very efficient operation (data is not actually
 622     copied because wxStrings are reference counted).
 623
 624     @beginWxPythonOnly
 625     If you wish to create a derived wxTextDataObject class in wxPython you
 626     should derive the class from wxPyTextDataObject in order to get
 627     Python-aware capabilities for the various virtual methods.
 628     @endWxPythonOnly
 629
 630     @library{wxcore}
 631     @category{dnd}
 632
 633     @see @ref overview_dnd, wxDataObject, wxDataObjectSimple, wxFileDataObject,
 634          wxBitmapDataObject
 635 */
 636 class wxTextDataObject : public wxDataObjectSimple
 637 {
 638 public:
 639     /**
 640         Constructor, may be used to initialise the text (otherwise SetText()
 641         should be used later).
 642     */
 643     wxTextDataObject(const wxString& text = wxEmptyString);
 644
 645     /**
 646         Returns the text associated with the data object. You may wish to
 647         override this method when offering data on-demand, but this is not
 648         required by wxWidgets' internals. Use this method to get data in text
 649         form from the wxClipboard.
 650     */
 651     virtual wxString GetText() const;
 652
 653     /**
 654         Returns the data size. By default, returns the size of the text data
 655         set in the constructor or using SetText(). This can be overridden to
 656         provide text size data on-demand. It is recommended to return the text
 657         length plus 1 for a trailing zero, but this is not strictly required.
 658     */
 659     virtual size_t GetTextLength() const;
 660
 661     /**
 662         Returns 2 under wxMac and wxGTK, where text data coming from the
 663         clipboard may be provided as ANSI (@c wxDF_TEXT) or as Unicode text
 664         (@c wxDF_UNICODETEXT, but only when @c wxUSE_UNICODE==1).
 665
 666         Returns 1 under other platforms (e.g. wxMSW) or when building in ANSI mode
 667         (@c wxUSE_UNICODE==0).
 668     */
 669     virtual size_t GetFormatCount(Direction dir = Get);
 670
 671     /**
 672         Returns the preferred format supported by this object.
 673
 674         This is @c wxDF_TEXT or @c wxDF_UNICODETEXT depending on the platform
 675         and from the build mode (i.e. from @c wxUSE_UNICODE).
 676     */
 677     const wxDataFormat& GetFormat() const;
 678
 679     /**
 680         Returns all the formats supported by wxTextDataObject.
 681
 682         Under wxMac and wxGTK they are @c wxDF_TEXT and @c wxDF_UNICODETEXT,
 683         under other ports returns only one of the two, depending on the build mode.
 684     */
 685     virtual void GetAllFormats(wxDataFormat* formats,
 686                                Direction dir = Get) const = 0;
 687
 688     /**
 689         Sets the text associated with the data object. This method is called
 690         when the data object receives the data and, by default, copies the text
 691         into the member variable. If you want to process the text on the fly
 692         you may wish to override this function.
 693     */
 694     virtual void SetText(const wxString& strText);
 695 };
 696
 697
 698
 699 /**
 700     @class wxFileDataObject
 701
 702     wxFileDataObject is a specialization of wxDataObject for file names. The
 703     program works with it just as if it were a list of absolute file names, but
 704     internally it uses the same format as Explorer and other compatible
 705     programs under Windows or GNOME/KDE filemanager under Unix which makes it
 706     possible to receive files from them using this class.
 707
 708     @warning Under all non-Windows platforms this class is currently
 709              "input-only", i.e. you can receive the files from another
 710              application, but copying (or dragging) file(s) from a wxWidgets
 711              application is not currently supported. PS: GTK2 should work as
 712              well.
 713
 714     @library{wxcore}
 715     @category{dnd}
 716
 717     @see wxDataObject, wxDataObjectSimple, wxTextDataObject,
 718          wxBitmapDataObject, wxDataObject
 719 */
 720 class wxFileDataObject : public wxDataObjectSimple
 721 {
 722 public:
 723     /**
 724         Constructor.
 725     */
 726     wxFileDataObject();
 727
 728     /**
 729         Adds a file to the file list represented by this data object (Windows only).
 730     */
 731     void AddFile(const wxString& file);
 732
 733     /**
 734         Returns the array of file names.
 735     */
 736     const wxArrayString& GetFilenames() const;
 737 };
 738
 739