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