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
 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     @beginWxPerlOnly
 208     This class is not currently usable from wxPerl; you may use
 209     Wx::PlDataObjectSimple instead.
 210     @endWxPerlOnly
 211
 212     @library{wxcore}
 213     @category{dnd}
 214
 215     @see @ref overview_dnd, @ref page_samples_dnd, wxFileDataObject,
 216          wxTextDataObject, wxBitmapDataObject, wxCustomDataObject,
 217          wxDropTarget, wxDropSource, wxTextDropTarget, wxFileDropTarget
 218 */
 219 class wxDataObject
 220 {
 221 public:
 222     enum Direction
 223     {
 224         /** Format is supported by GetDataHere() */
 225         Get  = 0x01,
 226
 227         /** Format is supported by SetData() */
 228         Set  = 0x02,
 229
 230         /**
 231             Format is supported by both GetDataHere() and SetData()
 232             (unused currently)
 233          */
 234         Both = 0x03
 235     };
 236
 237     /**
 238         Constructor.
 239     */
 240     wxDataObject();
 241
 242     /**
 243         Destructor.
 244     */
 245     virtual ~wxDataObject();
 246
 247     /**
 248         Copies all formats supported in the given direction @a dir to the array
 249         pointed to by @a formats.
 250         There must be enough space for GetFormatCount(dir) formats in it.
 251
 252         @beginWxPerlOnly
 253         In wxPerl this method only takes the @a dir parameter.  In scalar
 254         context it returns the first format in the list, in list
 255         context it returns a list containing all the supported
 256         formats.
 257         @endWxPerlOnly
 258     */
 259     virtual void GetAllFormats(wxDataFormat* formats,
 260                                Direction dir = Get) const = 0;
 261
 262     /**
 263         The method will write the data of the format @a format in the buffer
 264         @a buf and return @true on success, @false on failure.
 265     */
 266     virtual bool GetDataHere(const wxDataFormat& format, void* buf) const = 0;
 267
 268     /**
 269         Returns the data size of the given format @a format.
 270     */
 271     virtual size_t GetDataSize(const wxDataFormat& format) const = 0;
 272
 273     /**
 274         Returns the number of available formats for rendering or setting the
 275         data.
 276     */
 277     virtual size_t GetFormatCount(Direction dir = Get) const = 0;
 278
 279     /**
 280         Returns the preferred format for either rendering the data (if @a dir
 281         is @c Get, its default value) or for setting it. Usually this will be
 282         the native format of the wxDataObject.
 283     */
 284     virtual wxDataFormat GetPreferredFormat(Direction dir = Get) const = 0;
 285
 286     /**
 287         Set the data in the format @a format of the length @a len provided in
 288         the buffer @a buf.
 289
 290         @param format
 291             The format for which to set the data.
 292         @param len
 293             The size of data in bytes.
 294         @param buf
 295             Non-@NULL pointer to the data.
 296         @return
 297             @true on success, @false on failure.
 298     */
 299     virtual bool SetData(const wxDataFormat& format, size_t len, const void* buf);
 300
 301     /**
 302        Returns true if this format is supported.
 303     */
 304     bool IsSupported(const wxDataFormat& format, Direction dir = Get) const;
 305 };
 306
 307
 308 /**
 309     @class wxCustomDataObject
 310
 311     wxCustomDataObject is a specialization of wxDataObjectSimple for some
 312     application-specific data in arbitrary (either custom or one of the
 313     standard ones). The only restriction is that it is supposed that this data
 314     can be copied bitwise (i.e. with @c memcpy()), so it would be a bad idea to
 315     make it contain a C++ object (though C struct is fine).
 316
 317     By default, wxCustomDataObject stores the data inside in a buffer. To put
 318     the data into the buffer you may use either SetData() or TakeData()
 319     depending on whether you want the object to make a copy of data or not.
 320
 321     This class may be used as is, but if you don't want store the data inside
 322     the object but provide it on demand instead, you should override GetSize(),
 323     GetData() and SetData() (or may be only the first two or only the last one
 324     if you only allow reading/writing the data).
 325
 326     @library{wxcore}
 327     @category{dnd}
 328
 329     @see wxDataObject
 330 */
 331 class wxCustomDataObject : public wxDataObjectSimple
 332 {
 333 public:
 334     /**
 335         The constructor accepts a @a format argument which specifies the
 336         (single) format supported by this object. If it isn't set here,
 337         wxDataObjectSimple::SetFormat() should be used.
 338     */
 339     wxCustomDataObject(const wxDataFormat& format = wxFormatInvalid);
 340
 341     /**
 342         The destructor will free the data held by the object. Notice that
 343         although it calls the virtual Free() function, the base class version
 344         will always be called (C++ doesn't allow calling virtual functions from
 345         constructors or destructors), so if you override Free(), you should
 346         override the destructor in your class as well (which would probably
 347         just call the derived class' version of Free()).
 348     */
 349     virtual ~wxCustomDataObject();
 350
 351     /**
 352         This function is called to allocate @a size bytes of memory from
 353         SetData(). The default version just uses the operator new.
 354     */
 355     virtual void* Alloc(size_t size);
 356
 357     /**
 358         This function is called when the data is freed, you may override it to
 359         anything you want (or may be nothing at all). The default version calls
 360         operator delete[] on the data.
 361     */
 362     virtual void Free();
 363
 364     /**
 365         Returns a pointer to the data.
 366     */
 367     virtual void* GetData() const;
 368
 369     /**
 370         Returns the data size in bytes.
 371     */
 372     virtual size_t GetSize() const;
 373
 374     /**
 375         Set the data. The data object will make an internal copy.
 376     */
 377     virtual bool SetData(size_t size, const void* data);
 378
 379     /**
 380         Like SetData(), but doesn't copy the data - instead the object takes
 381         ownership of the pointer.
 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     This example shows how a composite data object capable of storing either
 403     bitmaps or file names (presumably of bitmap files) can be initialized and
 404     used:
 405
 406     @code
 407     MyDropTarget::MyDropTarget()
 408     {
 409         wxDataObjectComposite* dataobj = new wxDataObjectComposite();
 410         dataobj->Add(new wxBitmapDataObject(), true);
 411         dataobj->Add(new wxFileDataObject());
 412         SetDataObject(dataobj);
 413     }
 414
 415     wxDragResult MyDropTarget::OnData(wxCoord x, wxCoord y,
 416                                       wxDragResult defaultDragResult)
 417     {
 418         wxDragResult dragResult = wxDropTarget::OnData(x, y, defaultDragResult);
 419         if ( dragResult == defaultDragResult )
 420         {
 421             wxDataObjectComposite *
 422                 dataobjComp = static_cast<wxDataObjectComposite *>(GetDataObject());
 423
 424             wxDataFormat format = dataObjects->GetReceivedFormat();
 425             wxDataObject *dataobj = dataobjComp->GetObject(format);
 426             switch ( format.GetType() )
 427             {
 428                 case wxDF_BITMAP:
 429                     {
 430                         wxBitmapDataObject *
 431                             dataobjBitmap = static_cast<wxBitmapDataObject *>(dataobj);
 432
 433                         ... use dataobj->GetBitmap() ...
 434                     }
 435                     break;
 436
 437                 case wxDF_FILENAME:
 438                     {
 439                         wxFileDataObject *
 440                             dataobjFile = static_cast<wxFileDataObject *>(dataobj);
 441
 442                         ... use dataobj->GetFilenames() ...
 443                     }
 444                     break;
 445
 446                 default:
 447                     wxFAIL_MSG( "unexpected data object format" );
 448             }
 449         }
 450
 451         return dragResult;
 452     }
 453     @endcode
 454
 455     @library{wxcore}
 456     @category{dnd}
 457
 458     @see @ref overview_dnd, wxDataObject, wxDataObjectSimple, wxFileDataObject,
 459          wxTextDataObject, wxBitmapDataObject
 460 */
 461 class wxDataObjectComposite : public wxDataObject
 462 {
 463 public:
 464     /**
 465         The default constructor.
 466     */
 467     wxDataObjectComposite();
 468
 469     /**
 470         Adds the @a dataObject to the list of supported objects and it becomes
 471         the preferred object if @a preferred is @true.
 472     */
 473     void Add(wxDataObjectSimple* dataObject, bool preferred = false);
 474
 475     /**
 476         Report the format passed to the SetData() method.  This should be the
 477         format of the data object within the composite that received data from
 478         the clipboard or the DnD operation.  You can use this method to find
 479         out what kind of data object was received.
 480     */
 481     wxDataFormat GetReceivedFormat() const;
 482
 483     /**
 484         Returns the pointer to the object which supports the passed format for
 485         the specified direction.
 486
 487         @NULL is returned if the specified @a format is not supported for this
 488         direction @a dir. The returned pointer is owned by wxDataObjectComposite
 489         itself and shouldn't be deleted by caller.
 490
 491         @since 2.9.1
 492     */
 493     wxDataObjectSimple *GetObject(const wxDataFormat& format,
 494                                   wxDataObjectBase::Direction dir = Get) const;
 495 };
 496
 497
 498
 499 /**
 500     @class wxDataObjectSimple
 501
 502     This is the simplest possible implementation of the wxDataObject class.
 503     The data object of (a class derived from) this class only supports
 504     <strong>one format</strong>, so the number of virtual functions to
 505     be implemented is reduced.
 506
 507     Notice that this is still an abstract base class and cannot be used
 508     directly, it must be derived. The objects supporting rendering the data
 509     must override GetDataSize() and GetDataHere() while the objects which may
 510     be set must override SetData(). Of course, the objects supporting both
 511     operations must override all three methods.
 512
 513     @beginWxPerlOnly
 514     In wxPerl, you need to derive your data object class from
 515     Wx::PlDataObjectSimple.
 516     @endWxPerlOnly
 517
 518     @library{wxcore}
 519     @category{dnd}
 520
 521     @see @ref overview_dnd, @ref page_samples_dnd, wxFileDataObject,
 522          wxTextDataObject, wxBitmapDataObject
 523 */
 524 class wxDataObjectSimple : public wxDataObject
 525 {
 526 public:
 527     /**
 528         Constructor accepts the supported format (none by default) which may
 529         also be set later with SetFormat().
 530     */
 531     wxDataObjectSimple(const wxDataFormat& format = wxFormatInvalid);
 532
 533     /**
 534         Copy the data to the buffer, return @true on success.
 535         Must be implemented in the derived class if the object supports rendering
 536         its data.
 537     */
 538     virtual bool GetDataHere(void* buf) const;
 539
 540     /**
 541         Gets the size of our data. Must be implemented in the derived class if
 542         the object supports rendering its data.
 543     */
 544     virtual size_t GetDataSize() const;
 545
 546     /**
 547         Returns the (one and only one) format supported by this object.
 548         It is assumed that the format is supported in both directions.
 549     */
 550     const wxDataFormat& GetFormat() const;
 551
 552     /**
 553         Copy the data from the buffer, return @true on success.
 554         Must be implemented in the derived class if the object supports setting
 555         its data.
 556     */
 557     virtual bool SetData(size_t len, const void* buf);
 558
 559     /**
 560         Sets the supported format.
 561     */
 562     void SetFormat(const wxDataFormat& format);
 563 };
 564
 565
 566
 567 /**
 568     @class wxBitmapDataObject
 569
 570     wxBitmapDataObject is a specialization of wxDataObject for bitmap data. It
 571     can be used without change to paste data into the wxClipboard or a
 572     wxDropSource. A user may wish to derive a new class from this class for
 573     providing a bitmap on-demand in order to minimize memory consumption when
 574     offering data in several formats, such as a bitmap and GIF.
 575
 576     This class may be used as is, but GetBitmap() may be overridden to increase
 577     efficiency.
 578
 579     @library{wxcore}
 580     @category{dnd}
 581
 582     @see @ref overview_dnd, wxDataObject, wxDataObjectSimple, wxFileDataObject,
 583          wxTextDataObject, wxDataObject
 584 */
 585 class wxBitmapDataObject : public wxDataObjectSimple
 586 {
 587 public:
 588     /**
 589         Constructor, optionally passing a bitmap (otherwise use SetBitmap()
 590         later).
 591     */
 592     wxBitmapDataObject(const wxBitmap& bitmap = wxNullBitmap);
 593
 594     /**
 595         Returns the bitmap associated with the data object. You may wish to
 596         override this method when offering data on-demand, but this is not
 597         required by wxWidgets' internals. Use this method to get data in bitmap
 598         form from the wxClipboard.
 599     */
 600     virtual wxBitmap GetBitmap() const;
 601
 602     /**
 603         Sets the bitmap associated with the data object. This method is called
 604         when the data object receives data. Usually there will be no reason to
 605         override this function.
 606     */
 607     virtual void SetBitmap(const wxBitmap& bitmap);
 608 };
 609
 610
 611
 612 /**
 613     @class wxURLDataObject
 614
 615     wxURLDataObject is a wxDataObject containing an URL and can be used e.g.
 616     when you need to put an URL on or retrieve it from the clipboard:
 617
 618     @code
 619     wxTheClipboard->SetData(new wxURLDataObject(url));
 620     @endcode
 621
 622     @note This class is derived from wxDataObjectComposite on Windows rather
 623           than wxTextDataObject on all other platforms.
 624
 625     @library{wxcore}
 626     @category{dnd}
 627
 628     @see @ref overview_dnd, wxDataObject
 629 */
 630 class wxURLDataObject: public wxTextDataObject
 631 {
 632 public:
 633     /**
 634         Constructor, may be used to initialize the URL. If @a url is empty,
 635         SetURL() can be used later.
 636     */
 637     wxURLDataObject(const wxString& url = wxEmptyString);
 638
 639     /**
 640         Returns the URL stored by this object, as a string.
 641     */
 642     wxString GetURL() const;
 643
 644     /**
 645         Sets the URL stored by this object.
 646     */
 647     void SetURL(const wxString& url);
 648 };
 649
 650
 651 /**
 652     @class wxTextDataObject
 653
 654     wxTextDataObject is a specialization of wxDataObjectSimple for text data.
 655     It can be used without change to paste data into the wxClipboard or a
 656     wxDropSource. A user may wish to derive a new class from this class for
 657     providing text on-demand in order to minimize memory consumption when
 658     offering data in several formats, such as plain text and RTF because by
 659     default the text is stored in a string in this class, but it might as well
 660     be generated when requested. For this, GetTextLength() and GetText() will
 661     have to be overridden.
 662
 663     Note that if you already have the text inside a string, you will not
 664     achieve any efficiency gain by overriding these functions because copying
 665     wxStrings is already a very efficient operation (data is not actually
 666     copied because wxStrings are reference counted).
 667
 668     @library{wxcore}
 669     @category{dnd}
 670
 671     @see @ref overview_dnd, wxDataObject, wxDataObjectSimple, wxFileDataObject,
 672          wxBitmapDataObject
 673 */
 674 class wxTextDataObject : public wxDataObjectSimple
 675 {
 676 public:
 677     /**
 678         Constructor, may be used to initialise the text (otherwise SetText()
 679         should be used later).
 680     */
 681     wxTextDataObject(const wxString& text = wxEmptyString);
 682
 683     /**
 684         Returns the text associated with the data object. You may wish to
 685         override this method when offering data on-demand, but this is not
 686         required by wxWidgets' internals. Use this method to get data in text
 687         form from the wxClipboard.
 688     */
 689     virtual wxString GetText() const;
 690
 691     /**
 692         Returns the data size. By default, returns the size of the text data
 693         set in the constructor or using SetText(). This can be overridden to
 694         provide text size data on-demand. It is recommended to return the text
 695         length plus 1 for a trailing zero, but this is not strictly required.
 696     */
 697     virtual size_t GetTextLength() const;
 698
 699     /**
 700         Returns 2 under wxMac and wxGTK, where text data coming from the
 701         clipboard may be provided as ANSI (@c wxDF_TEXT) or as Unicode text
 702         (@c wxDF_UNICODETEXT, but only when @c wxUSE_UNICODE==1).
 703
 704         Returns 1 under other platforms (e.g. wxMSW) or when building in ANSI mode
 705         (@c wxUSE_UNICODE==0).
 706     */
 707     virtual size_t GetFormatCount(Direction dir = Get) const;
 708
 709     /**
 710         Returns the preferred format supported by this object.
 711
 712         This is @c wxDF_TEXT or @c wxDF_UNICODETEXT depending on the platform
 713         and from the build mode (i.e. from @c wxUSE_UNICODE).
 714     */
 715     const wxDataFormat& GetFormat() const;
 716
 717     /**
 718         Returns all the formats supported by wxTextDataObject.
 719
 720         Under wxMac and wxGTK they are @c wxDF_TEXT and @c wxDF_UNICODETEXT,
 721         under other ports returns only one of the two, depending on the build mode.
 722     */
 723     virtual void GetAllFormats(wxDataFormat* formats,
 724                                Direction dir = Get) const = 0;
 725
 726     /**
 727         Sets the text associated with the data object. This method is called
 728         when the data object receives the data and, by default, copies the text
 729         into the member variable. If you want to process the text on the fly
 730         you may wish to override this function.
 731     */
 732     virtual void SetText(const wxString& strText);
 733 };
 734
 735
 736
 737 /**
 738     @class wxFileDataObject
 739
 740     wxFileDataObject is a specialization of wxDataObject for file names. The
 741     program works with it just as if it were a list of absolute file names, but
 742     internally it uses the same format as Explorer and other compatible
 743     programs under Windows or GNOME/KDE filemanager under Unix which makes it
 744     possible to receive files from them using this class.
 745
 746     @warning Under all non-Windows platforms this class is currently
 747              "input-only", i.e. you can receive the files from another
 748              application, but copying (or dragging) file(s) from a wxWidgets
 749              application is not currently supported. PS: GTK2 should work as
 750              well.
 751
 752     @library{wxcore}
 753     @category{dnd}
 754
 755     @see wxDataObject, wxDataObjectSimple, wxTextDataObject,
 756          wxBitmapDataObject, wxDataObject
 757 */
 758 class wxFileDataObject : public wxDataObjectSimple
 759 {
 760 public:
 761     /**
 762         Constructor.
 763     */
 764     wxFileDataObject();
 765
 766     /**
 767         Adds a file to the file list represented by this data object (Windows only).
 768     */
 769     void AddFile(const wxString& file);
 770
 771     /**
 772         Returns the array of file names.
 773     */
 774     const wxArrayString& GetFilenames() const;
 775 };
 776
 777