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