]> git.saurik.com Git - wxWidgets.git/blame - docs/doxygen/overviews/dataobject.h
Check wxDateTime components validity more rigorously.
[wxWidgets.git] / docs / doxygen / overviews / dataobject.h
CommitLineData
15b6757b 1/////////////////////////////////////////////////////////////////////////////
d54cf7ff 2// Name: dataobject.h
15b6757b
FM
3// Purpose: topic overview
4// Author: wxWidgets team
5// RCS-ID: $Id$
526954c5 6// Licence: wxWindows licence
15b6757b
FM
7/////////////////////////////////////////////////////////////////////////////
8
880efa2a 9/**
36c9828f 10
dc28cdf8 11@page overview_dataobject wxDataObject Overview
36c9828f 12
dc28cdf8 13Classes: wxDataObject, wxClipboard, wxDataFormat, wxDropSource, wxDropTarget
d54cf7ff 14
dc28cdf8 15See also: @ref overview_dnd and @ref page_samples_dnd
d54cf7ff 16
dc28cdf8
FM
17This overview discusses data transfer through clipboard or drag and drop.
18In wxWidgets, these two ways to transfer data (either between different
19applications or inside one and the same) are very similar which allows to
20implement both of them using almost the same code - or, in other
21words, if you implement drag and drop support for your application, you get
22clipboard support for free and vice versa.
d54cf7ff 23
dc28cdf8
FM
24At the heart of both clipboard and drag and drop operations lies the
25wxDataObject class. The objects of this class (or, to
26be precise, classes derived from it) represent the data which is being carried
27by the mouse during drag and drop operation or copied to or pasted from the
28clipboard. wxDataObject is a "smart" piece of data because it knows which
29formats it supports (see GetFormatCount and GetAllFormats) and knows how to
30render itself in any of them (see GetDataHere). It can also receive its value
31from the outside in a format it supports if it implements the SetData method.
32Please see the documentation of this class for more details.
d54cf7ff 33
dc28cdf8
FM
34Both clipboard and drag and drop operations have two sides: the source and
35target, the data provider and the data receiver. These which may be in the same
36application and even the same window when, for example, you drag some text from
37one position to another in a word processor. Let us describe what each of them
38should do.
d54cf7ff 39
dc28cdf8
FM
40@li @ref overview_dataobject_source
41@li @ref overview_dataobject_target
98ba1eee
FM
42
43
dc28cdf8 44<hr>
36c9828f
FM
45
46
dc28cdf8 47@section overview_dataobject_source The data provider (source) duties
d54cf7ff 48
dc28cdf8
FM
49The data provider is responsible for creating a wxDataObject containing the
50data to be transferred. Then it should either pass it to the clipboard using
51wxClipboard::SetData function or to wxDropSource and call wxDropSource::DoDragDrop
52function.
36c9828f 53
dc28cdf8
FM
54The only (but important) difference is that the object for the clipboard
55transfer must always be created on the heap (i.e. using @c new) and it will
56be freed by the clipboard when it is no longer needed (indeed, it is not known
57in advance when, if ever, the data will be pasted from the clipboard). On the
58other hand, the object for drag and drop operation must only exist while
59wxDropSource::DoDragDrop executes and may be safely deleted afterwards and so
60can be created either on heap or on stack (i.e. as a local variable).
d54cf7ff 61
dc28cdf8
FM
62Another small difference is that in the case of clipboard operation, the
63application usually knows in advance whether it copies or cuts (i.e. copies and
64deletes) data - in fact, this usually depends on which menu item the user
65chose. But for drag and drop it can only know it after
66wxDropSource::DoDragDrop returns (from its return value).
36c9828f 67
d54cf7ff 68
dc28cdf8 69@section overview_dataobject_target The data receiver (target) duties
36c9828f 70
dc28cdf8
FM
71To receive (paste in usual terminology) data from the clipboard, you should
72create a wxDataObject derived class which supports the data formats you need
73and pass it as argument to wxClipboard::GetData. If it returns @false,
74no data in (any of) the supported format(s) is available. If it returns @true,
75the data has been successfully transferred to wxDataObject.
d54cf7ff 76
dc28cdf8
FM
77For drag and drop case, the wxDropTarget::OnData virtual function will be called
78when a data object is dropped, from which the data itself may be requested by calling
79wxDropTarget::GetData method which fills the data object.
36c9828f 80
d54cf7ff 81*/
36c9828f 82