X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/f9b1708cf57d57bc91f4e870a4646efd1f174c3d..6c4fc6a8e3bea19621a328e66b3857ab01a5c15a:/docs/latex/wx/tdnd.tex diff --git a/docs/latex/wx/tdnd.tex b/docs/latex/wx/tdnd.tex index ecdb4cf770..dbbe6daaf2 100644 --- a/docs/latex/wx/tdnd.tex +++ b/docs/latex/wx/tdnd.tex @@ -1,4 +1,4 @@ -\section{Drag-and-drop and clipboard overview}\label{wxdndoverview} +\section{Drag and drop overview}\label{wxdndoverview} Classes: \helpref{wxDataObject}{wxdataobject}, \helpref{wxTextDataObject}{wxtextdataobject}, @@ -7,96 +7,78 @@ Classes: \helpref{wxDataObject}{wxdataobject}, \helpref{wxTextDropTarget}{wxtextdroptarget}, \helpref{wxFileDropTarget}{wxfiledroptarget} -It has to be noted that the API for drag and drop in wxWindows is not -yet finished which is mostly due to the fact that DnD support under -GTK 1.0 is very rudimentary and entirely different from the XDnD -protocoll used by GTK 1.2. This also entails that not all of the documentation -concerning DnD might be correct and some of the code might get broken -in the future. The next release of wxWindows will be based on GTK 1.2 -and will hopefully include a much improved DnD support. The general -design on the wxDropSource side will be the same but especially the -wxDropTarget is almost certain to change. - Note that wxUSE\_DRAG\_AND\_DROP must be defined in setup.h in order -to use Drag'n'Drop in wxWindows. +to use drag and drop in wxWidgets. -This overview describes wxWindows support for drag and drop and clipboard -operations. Both of these topics are discussed here because, in fact, they're -quite related. Drag and drop and clipboard are just two ways of passing the -data around and so the code required to implement both types of the operations -is almost the same. +See also: \helpref{wxDataObject overview}{wxdataobjectoverview} and \helpref{DnD sample}{samplednd} -Both operations involve passing some data from one program to another, -although the data can be received in the same program as the source. In the case -of clipboard transfer, the data is first placed on the clipboard and then -pasted into the destination program, while for a drag-and-drop operation the -data object is not stored anywhere but is created when the user starts -dragging and is destroyed as soon as he ends it, whether the operation was -ended successfully or cancelled. +It may be noted that data transfer to and from the clipboard is quite +similar to data transfer with drag and drop and the code to implement +these two types is almost the same. In particular, both data transfer +mechanisms store data in some kind of \helpref{wxDataObject}{wxdataobject} +and identify its format(s) using the \helpref{wxDataFormat}{wxdataformat} +class. To be a {\it drag source}, i.e. to provide the data which may be dragged by -user elsewhere, you should implement the following steps: +the user elsewhere, you should implement the following steps: \begin{itemize}\itemsep=0pt -\item {\bf Preparation:} First of all, the data object must be created and +\item {\bf Preparation:} First of all, a data object must be created and initialized with the data you wish to drag. For example: \begin{verbatim} - wxDataObject *my_data = new wxTextDataObject data("This string will be dragged."); + wxTextDataObject my_data("This text will be dragged."); \end{verbatim} - -\item{\bf Drag start:} To start dragging process (typically in response to a -mouse click) you must call \helpref{DoDragDrop}{wxdropsourcedodragdrop} function -of wxDropSource object which should be constructed like this: +\item{\bf Drag start:} To start the dragging process (typically in response to a +mouse click) you must call \helpref{wxDropSource::DoDragDrop}{wxdropsourcedodragdrop} +like this: \begin{verbatim} wxDropSource dragSource( this ); dragSource.SetData( my_data ); + wxDragResult result = dragSource.DoDragDrop( TRUE ); \end{verbatim} - -\item {\bf Dragging:} The call to DoDragDrop() blocks until the user release the -mouse button (unless you override \helpref{GiveFeedback}{wxdropsourcegivefeedback} function +\item {\bf Dragging:} The call to DoDragDrop() blocks the program until the user releases the +mouse button (unless you override the \helpref{GiveFeedback}{wxdropsourcegivefeedback} function to do something special). When the mouse moves in a window of a program which understands the -same drag-and-drop protocol (any program under Windows or any program supporting GTK 1.0 -DnD protocol under X Windows), the corresponding \helpref{wxDropTarget}{wxdroptarget} methods +same drag-and-drop protocol (any program under Windows or any program supporting the +XDnD protocol under X Windows), the corresponding \helpref{wxDropTarget}{wxdroptarget} methods are called - see below. - \item {\bf Processing the result:} DoDragDrop() returns an {\it effect code} which -is one of the values of \helpref{wxDragResult}{wxdropsource} enum. Codes -of wxDragError, wxDragNone and wxDragCancel have the obvious meaning and mean -that there is nothing to do on the sending end (except of possibly logging the -error in the first case). wxDragCopy means that the data has been successfully -copied and doesn't require any specific actions neither. But wxDragMove is -special because it means that the data must be deleted from where it was -copied. If it doesn't make sense (dragging selected text from a read-only -file) you should pass FALSE as parameter to DoDragDrop() in the previous step. +is one of the values of {\tt wxDragResult} enum (explained \helpref{here}{wxdroptarget}): + +\begin{verbatim} + switch (result) + { + case wxDragCopy: /* copy the data */ break; + case wxDragMove: /* move the data */ break; + default: /* do nothing */ break; + } +\end{verbatim}% \end{itemize} -To be a {\it drop target}, i.e. to receive the data dropped by user you should +To be a {\it drop target}, i.e. to receive the data dropped by the user you should follow the instructions below: \begin{itemize}\itemsep=0pt -\item {\bf Initialization:} For a window to be drop target, it needs to have +\item {\bf Initialization:} For a window to be a drop target, it needs to have an associated \helpref{wxDropTarget}{wxdroptarget} object. Normally, you will call \helpref{wxWindow::SetDropTarget}{wxwindowsetdroptarget} during window -creation associating you drop target with it. You must derive a class from +creation associating your drop target with it. You must derive a class from wxDropTarget and override its pure virtual methods. Alternatively, you may derive from \helpref{wxTextDropTarget}{wxtextdroptarget} or \helpref{wxFileDropTarget}{wxfiledroptarget} and override their OnDropText() or OnDropFiles() method. - -\item {\bf Drop:} When the user releases the mouse over a window, wxWindows -queries the associated wxDropTarget object if it accepts the data. For -this, \helpref{GetFormatCount}{wxdroptargetgetformatcount} and \helpref{GetFormat}{wxdroptargetgetformat} are -used and if the format is -supported (i.e. is one of returned by GetFormat()), -then \helpref{OnDrop}{wxdroptargetondrop} is called. -Otherwise, wxDragNone is returned by DoDragDrop() and -nothing happens. - +\item {\bf Drop:} When the user releases the mouse over a window, wxWidgets +asks the associated wxDropTarget object if it accepts the data. For this, +a \helpref{wxDataObject}{wxdataobject} must be associated with the drop target +and this data object will be responsible for the format negotiation between +the drag source and the drop target. If all goes well, then \helpref{OnData}{wxdroptargetondata} +will get called and the wxDataObject belonging to the drop target can get +filled with data. \item {\bf The end:} After processing the data, DoDragDrop() returns either -wxDragCopy or wxDragMove depending on the state of the keys (, -and ) at the moment of drop. There is currently no way for the drop +wxDragCopy or wxDragMove depending on the state of the keys , +and at the moment of the drop. There is currently no way for the drop target to change this return code. \end{itemize}