-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% Name: tclipbrd.tex
-%% Purpose: Data transfer (clipboard and drag and drop) overview
-%% Author: Vadim Zeitlin
-%% Modified by:
-%% Created: 18.10.99
-%% RCS-ID: $Id$
-%% Copyright: (c) Vadim Zeitlin
-%% Licence: wxWindows licence
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\section{Clipboard and drag and drop overview}\label{wxclipboardonfigoverview}
+\section{wxDataObject overview}\label{wxdataobjectoverview}
Classes: \helpref{wxDataObject}{wxdataobject},
- \helpref{wxClipboard}{wxclipboard},
- \helpref{wxDataFormat}{wxdataformat},
- \helpref{wxDropSource}{wxdropsource},
- \helpref{wxDropTarget}{wxdroptarget}
+ \helpref{wxClipboard}{wxclipboard},
+ \helpref{wxDataFormat}{wxdataformat},
+ \helpref{wxDropSource}{wxdropsource},
+ \helpref{wxDropTarget}{wxdroptarget}
+
+See also: \helpref{Drag and drop overview}{wxdndoverview} and \helpref{DnD sample}{samplednd}
This overview discusses data transfer through clipboard or drag and drop. In
-wxWindows, these two ways to transfer data (either between different
+wxWidgets, these two ways to transfer data (either between different
applications or inside one and the same) are very similar which allows to
-implement both of them using almost the same code - or, to say it in other
+implement both of them using almost the same code - or, in other
words, if you implement drag and drop support for your application, you get
clipboard support for free and vice versa.
-In the heart of both clipboard and drag and drop operations lies the
-\helpref{wxDataObject}{wxdataobject} class. The objects of this (or, to be
-precise, derived from it) class represent the data which is being carried by
-the mouse during drag and drop operation or copied to or pasted from the
-clipboard. \helpref{wxDataObject}{wxdataobject} is a "smart" piece of data
-because it knows which \helpref{formats}{wxdataformat} it supports (see
-\helpref{GetFormatCount}{wxdataobjectgetformatcount} and
-\helpref{GetAllFormats}{wxdataobjectgetallformats}) and knows how to render
-itself in any of them (see \helpref{GetDataHere.}{wxdataobjectgetdatahere}).
-It can also receive its value from the outside in a format it supports if it
-implements \helpref{SetData}{wxdataobjectsetdata} method.
+At the heart of both clipboard and drag and drop operations lies the
+\helpref{wxDataObject}{wxdataobject} class. The objects of this class (or, to
+be precise, classes derived from it) represent the data which is being carried
+by the mouse during drag and drop operation or copied to or pasted from the
+clipboard. wxDataObject is a "smart" piece of data because it knows which
+formats it supports (see GetFormatCount and GetAllFormats) and knows how to
+render itself in any of them (see GetDataHere). It can also receive its value
+from the outside in a format it supports if it implements the SetData method.
+Please see the documentation of this class for more details.
Both clipboard and drag and drop operations have two sides: the source and
-target, the data provider and the data receiver (which may be the same
+target, the data provider and the data receiver. These which may be in the same
application and even the same window when, for example, you drag some text from
-one position to another in a word processor). Let us describe what each of them
+one position to another in a word processor. Let us describe what each of them
should do.
-\subsection{The data provider (source) duties}{wxdataobjectsource}
+\subsection{The data provider (source) duties}\label{wxdataobjectsource}
The data provider is responsible for creating a
-\helpref{wxDataObject}{wxdataobjectwxdataobject} containing the data to be
-transfered. Then it should either pass it to the clipboard using
-\helpref{AddData}{wxclipboardadddata} or \helpref{SetData}{wxclipboardsetdata}
-functions or to \helpref{wxDropSource}{wxdropsource} and call
+\helpref{wxDataObject}{wxdataobject} containing the data to be
+transferred. Then it should either pass it to the clipboard using
+\helpref{SetData}{wxclipboardsetdata} function or to
+\helpref{wxDropSource}{wxdropsource} and call
\helpref{DoDragDrop}{wxdropsourcedodragdrop} function.
The only (but important) difference is that the object for the clipboard
afterwards and so can be created either on heap or on stack (i.e. as a local
variable).
-Another small difference si that in the case of clipboard operation, the
+Another small difference is that in the case of clipboard operation, the
application usually knows in advance whether it copies or cuts (i.e. copies and
deletes) data - in fact, this usually depends on which menu item the user
chose. But for drag and drop it can only know it after
\helpref{DoDragDrop}{wxdropsourcedodragdrop} returns (from its return value).
-\subsection{The data receiver (target) duties}{wxdataobjecttarget}
+\subsection{The data receiver (target) duties}\label{wxdataobjecttarget}
To receive (paste in usual terminology) data from the clipboard, you should
create a \helpref{wxDataObject}{wxdataobject} derived class which supports the
data formats you need and pass it as argument to
-\helpref{wxClipboard::GetData}{wxclipboardgetdata}. If it returns {\tt FALSE},
+\helpref{wxClipboard::GetData}{wxclipboardgetdata}. If it returns {\tt false},
no data in (any of) the supported format(s) is available. If it returns {\tt
-TRUE}, the data has been successfully transfered to wxDataObject.
+true}, the data has been successfully transferred to wxDataObject.
+
+For drag and drop case, the \helpref{wxDropTarget::OnData}{wxdroptargetondata}
+virtual function will be called when a data object is dropped, from which the
+data itself may be requested by calling
+\helpref{wxDropTarget::GetData}{wxdroptargetwxdroptarget} method which fills
+the data object.
-{\bf TODO} document drag and drop side when the API is finalised
projects / wxWidgets.git / blobdiff