X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/23d277e683b40c84cf27a538d24e1acc019661a8..4fcbc84d657413b157ac3ef89bf8fbccbcf899ba:/docs/latex/wx/tclipbrd.tex diff --git a/docs/latex/wx/tclipbrd.tex b/docs/latex/wx/tclipbrd.tex index e44c023308..e76f050078 100644 --- a/docs/latex/wx/tclipbrd.tex +++ b/docs/latex/wx/tclipbrd.tex @@ -1,54 +1,43 @@ -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -%% 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 @@ -60,19 +49,24 @@ other hand, the object for drag and drop operation must only exist while 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