]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/dataobj.h
no real changes, just refactor to remove some code duplication in wxToolBarTool
[wxWidgets.git] / 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 virtual void TakeData(size_t size, const 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(NativeFormat format = wxDF_INVALID);
340 /**
341 Constructs a data format object for a custom format identified by its
342 name @a format.
343 */
344 wxDataFormat(const wxChar format);
345
346 /**
347 Returns the name of a custom format (this function will fail for a
348 standard format).
349 */
350 wxString GetId() const;
351
352 /**
353 Returns the platform-specific number identifying the format.
354 */
355 NativeFormat GetType() const;
356
357 /**
358 Sets the format to be the custom format identified by the given name.
359 */
360 void SetId(const wxChar format);
361
362 /**
363 Sets the format to the given value, which should be one of wxDF_XXX
364 constants.
365 */
366 void SetType(NativeFormat format);
367
368 /**
369 Returns @true if the formats are different.
370 */
371 bool operator !=(const wxDataFormat& format) const;
372
373 /**
374 Returns @true if the formats are equal.
375 */
376 bool operator ==(const wxDataFormat& format) const;
377 };
378
379
380
381 /**
382 @class wxURLDataObject
383
384 wxURLDataObject is a wxDataObject containing an URL and can be used e.g.
385 when you need to put an URL on or retrieve it from the clipboard:
386
387 @code
388 wxTheClipboard->SetData(new wxURLDataObject(url));
389 @endcode
390
391 @note This class is derived from wxDataObjectComposite on Windows rather
392 than wxTextDataObject on all other platforms.
393
394 @library{wxcore}
395 @category{dnd}
396
397 @see @ref overview_dnd, wxDataObject
398 */
399 class wxURLDataObject: public wxTextDataObject
400 {
401 public:
402 /**
403 Constructor, may be used to initialize the URL. If @a url is empty,
404 SetURL() can be used later.
405 */
406 wxURLDataObject(const wxString& url = wxEmptyString);
407
408 /**
409 Returns the URL stored by this object, as a string.
410 */
411 wxString GetURL() const;
412
413 /**
414 Sets the URL stored by this object.
415 */
416 void SetURL(const wxString& url);
417 };
418
419
420
421 /**
422 @class wxDataObject
423
424 A wxDataObject represents data that can be copied to or from the clipboard,
425 or dragged and dropped. The important thing about wxDataObject is that this
426 is a 'smart' piece of data unlike 'dumb' data containers such as memory
427 buffers or files. Being 'smart' here means that the data object itself
428 should know what data formats it supports and how to render itself in each
429 of its supported formats.
430
431 A supported format, incidentally, is exactly the format in which the data
432 can be requested from a data object or from which the data object may be
433 set. In the general case, an object may support different formats on
434 'input' and 'output', i.e. it may be able to render itself in a given
435 format but not be created from data on this format or vice versa.
436 wxDataObject defines an enumeration type which distinguishes between them:
437
438 @code
439 enum Direction
440 {
441 Get = 0x01, // format is supported by GetDataHere()
442 Set = 0x02 // format is supported by SetData()
443 };
444 @endcode
445
446 See wxDataFormat documentation for more about formats.
447
448 Not surprisingly, being 'smart' comes at a price of added complexity. This
449 is reasonable for the situations when you really need to support multiple
450 formats, but may be annoying if you only want to do something simple like
451 cut and paste text.
452
453 To provide a solution for both cases, wxWidgets has two predefined classes
454 which derive from wxDataObject: wxDataObjectSimple and
455 wxDataObjectComposite. wxDataObjectSimple is the simplest wxDataObject
456 possible and only holds data in a single format (such as HTML or text) and
457 wxDataObjectComposite is the simplest way to implement a wxDataObject that
458 does support multiple formats because it achieves this by simply holding
459 several wxDataObjectSimple objects.
460
461 So, you have several solutions when you need a wxDataObject class (and you
462 need one as soon as you want to transfer data via the clipboard or drag and
463 drop):
464
465 -# Use one of the built-in classes.
466 - You may use wxTextDataObject, wxBitmapDataObject or wxFileDataObject
467 in the simplest cases when you only need to support one format and
468 your data is either text, bitmap or list of files.
469 -# Use wxDataObjectSimple
470 - Deriving from wxDataObjectSimple is the simplest solution for custom
471 data - you will only support one format and so probably won't be able
472 to communicate with other programs, but data transfer will work in
473 your program (or between different copies of it).
474 -# Use wxDataObjectComposite
475 - This is a simple but powerful solution which allows you to support
476 any number of formats (either standard or custom if you combine it
477 with the previous solution).
478 -# Use wxDataObject Directly
479 - This is the solution for maximal flexibility and efficiency, but it
480 is also the most difficult to implement.
481
482 Please note that the easiest way to use drag and drop and the clipboard
483 with multiple formats is by using wxDataObjectComposite, but it is not the
484 most efficient one as each wxDataObjectSimple would contain the whole data
485 in its respective formats. Now imagine that you want to paste 200 pages of
486 text in your proprietary format, as well as Word, RTF, HTML, Unicode and
487 plain text to the clipboard and even today's computers are in trouble. For
488 this case, you will have to derive from wxDataObject directly and make it
489 enumerate its formats and provide the data in the requested format on
490 demand.
491
492 Note that neither the GTK+ data transfer mechanisms for clipboard and drag
493 and drop, nor OLE data transfer, copy any data until another application
494 actually requests the data. This is in contrast to the 'feel' offered to
495 the user of a program who would normally think that the data resides in the
496 clipboard after having pressed 'Copy' - in reality it is only declared to
497 be available.
498
499 There are several predefined data object classes derived from
500 wxDataObjectSimple: wxFileDataObject, wxTextDataObject, wxBitmapDataObject
501 and wxURLDataObject which can be used without change.
502
503 You may also derive your own data object classes from wxCustomDataObject
504 for user-defined types. The format of user-defined data is given as a
505 mime-type string literal, such as "application/word" or "image/png". These
506 strings are used as they are under Unix (so far only GTK+) to identify a
507 format and are translated into their Windows equivalent under Win32 (using
508 the OLE IDataObject for data exchange to and from the clipboard and for
509 drag and drop). Note that the format string translation under Windows is
510 not yet finished.
511
512 Each class derived directly from wxDataObject must override and implement
513 all of its functions which are pure virtual in the base class. The data
514 objects which only render their data or only set it (i.e. work in only one
515 direction), should return 0 from GetFormatCount().
516
517 @beginWxPythonOnly
518 At this time this class is not directly usable from wxPython. Derive a
519 class from wxPyDataObjectSimple() instead.
520 @endWxPythonOnly
521
522 @beginWxPerlOnly
523 This class is not currently usable from wxPerl; you may use
524 Wx::PlDataObjectSimple instead.
525 @endWxPerlOnly
526
527 @library{wxcore}
528 @category{dnd}
529
530 @see @ref overview_dnd, @ref page_samples_dnd, wxFileDataObject,
531 wxTextDataObject, wxBitmapDataObject, wxCustomDataObject,
532 wxDropTarget, wxDropSource, wxTextDropTarget, wxFileDropTarget
533 */
534 class wxDataObject
535 {
536 public:
537 /**
538 Constructor.
539 */
540 wxDataObject();
541
542 /**
543 Destructor.
544 */
545 ~wxDataObject();
546
547 /**
548 Copy all supported formats in the given direction to the array pointed
549 to by @a formats. There is enough space for GetFormatCount(dir) formats
550 in it.
551 */
552 virtual void GetAllFormats(wxDataFormat* formats,
553 Direction dir = Get) const;
554
555 /**
556 The method will write the data of the format @a format in the buffer
557 @a buf and return @true on success, @false on failure.
558 */
559 virtual bool GetDataHere(const wxDataFormat& format, void buf) const;
560
561 /**
562 Returns the data size of the given format @a format.
563 */
564 virtual size_t GetDataSize(const wxDataFormat& format) const;
565
566 /**
567 Returns the number of available formats for rendering or setting the
568 data.
569 */
570 virtual size_t GetFormatCount(Direction dir = Get) const;
571
572 /**
573 Returns the preferred format for either rendering the data (if @a dir
574 is @c Get, its default value) or for setting it. Usually this will be
575 the native format of the wxDataObject.
576 */
577 virtual wxDataFormat GetPreferredFormat(Direction dir = Get) const;
578
579 /**
580 Set the data in the format @a format of the length @a len provided in
581 the buffer @a buf.
582
583 @return @true on success, @false on failure.
584 */
585 virtual bool SetData(const wxDataFormat& format, size_t len,
586 const void buf);
587 };
588
589
590
591 /**
592 @class wxTextDataObject
593
594 wxTextDataObject is a specialization of wxDataObject for text data. It can
595 be used without change to paste data into the wxClipboard or a
596 wxDropSource. A user may wish to derive a new class from this class for
597 providing text on-demand in order to minimize memory consumption when
598 offering data in several formats, such as plain text and RTF because by
599 default the text is stored in a string in this class, but it might as well
600 be generated when requested. For this, GetTextLength() and GetText() will
601 have to be overridden.
602
603 Note that if you already have the text inside a string, you will not
604 achieve any efficiency gain by overriding these functions because copying
605 wxStrings is already a very efficient operation (data is not actually
606 copied because wxStrings are reference counted).
607
608 @beginWxPythonOnly
609 If you wish to create a derived wxTextDataObject class in wxPython you
610 should derive the class from wxPyTextDataObject in order to get
611 Python-aware capabilities for the various virtual methods.
612 @endWxPythonOnly
613
614 @library{wxcore}
615 @category{dnd}
616
617 @see @ref overview_dnd, wxDataObject, wxDataObjectSimple, wxFileDataObject,
618 wxBitmapDataObject
619 */
620 class wxTextDataObject : public wxDataObjectSimple
621 {
622 public:
623 /**
624 Constructor, may be used to initialise the text (otherwise SetText()
625 should be used later).
626 */
627 wxTextDataObject(const wxString& text = wxEmptyString);
628
629 /**
630 Returns the text associated with the data object. You may wish to
631 override this method when offering data on-demand, but this is not
632 required by wxWidgets' internals. Use this method to get data in text
633 form from the wxClipboard.
634 */
635 virtual wxString GetText() const;
636
637 /**
638 Returns the data size. By default, returns the size of the text data
639 set in the constructor or using SetText(). This can be overridden to
640 provide text size data on-demand. It is recommended to return the text
641 length plus 1 for a trailing zero, but this is not strictly required.
642 */
643 virtual size_t GetTextLength() const;
644
645 /**
646 Sets the text associated with the data object. This method is called
647 when the data object receives the data and, by default, copies the text
648 into the member variable. If you want to process the text on the fly
649 you may wish to override this function.
650 */
651 virtual void SetText(const wxString& strText);
652 };
653
654
655
656 /**
657 @class wxFileDataObject
658
659 wxFileDataObject is a specialization of wxDataObject for file names. The
660 program works with it just as if it were a list of absolute file names, but
661 internally it uses the same format as Explorer and other compatible
662 programs under Windows or GNOME/KDE filemanager under Unix which makes it
663 possible to receive files from them using this class.
664
665 @warning Under all non-Windows platforms this class is currently
666 "input-only", i.e. you can receive the files from another
667 application, but copying (or dragging) file(s) from a wxWidgets
668 application is not currently supported. PS: GTK2 should work as
669 well.
670
671 @library{wxcore}
672 @category{dnd}
673
674 @see wxDataObject, wxDataObjectSimple, wxTextDataObject,
675 wxBitmapDataObject, wxDataObject
676 */
677 class wxFileDataObject : public wxDataObjectSimple
678 {
679 public:
680 /**
681 Constructor.
682 */
683 wxFileDataObject();
684
685 /**
686 Adds a file to the file list represented by this data object (Windows
687 only).
688 */
689 virtual void AddFile(const wxString& file);
690
691 /**
692 Returns the array of file names.
693 */
694 const wxArrayString GetFilenames() const;
695 };
696