X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/b1327f57abd9c92ad9ba0eee2bf780747e42a245..3d3428c4e6c415cb31824f9d6087d8de8e51cabc:/docs/latex/wx/tdnd.tex?ds=sidebyside diff --git a/docs/latex/wx/tdnd.tex b/docs/latex/wx/tdnd.tex index 8251c44d92..0e1837d51b 100644 --- a/docs/latex/wx/tdnd.tex +++ b/docs/latex/wx/tdnd.tex @@ -1,72 +1,84 @@ -\section{Drag-and-drop and clipboard overview}\label{wxdndoverview} +\section{Drag'n'Drop overview}\label{wxdndoverview} -Classes: \helpref{wxDataObject}{wxdataobject} +Classes: \helpref{wxDataObject}{wxdataobject}, +\helpref{wxTextDataObject}{wxtextdataobject}, +\helpref{wxDropSource}{wxdropsource}, +\helpref{wxDropTarget}{wxdroptarget}, +\helpref{wxTextDropTarget}{wxtextdroptarget}, +\helpref{wxFileDropTarget}{wxfiledroptarget} -% \helpref{wxTextDataObject}{wxtextdataobject} -% \helpref{wxDropSource}{wxdropsource} -% \helpref{wxDropTarget}{wxdroptarget} -% \helpref{wxTextDropTarget}{wxtextdroptarget} -% \helpref{wxFileDropTarget}{wxfiledroptarget} +Note that wxUSE\_DRAG\_AND\_DROP must be defined in setup.h in order +to use Drag'n'Drop in wxWindows. -Samples: see the dnd sample. +See also: \helpref{wxDataObject overview}{wxdataobjectoverview} and \helpref{DnD sample}{samplednd} -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 too ways of passing the -data around and so the code required to implement both types of the operations -is almost the same. +It may be noted that data transfer to and from the clipboard is quite +similar to data transfer with Drag'n'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. -In any case, you work with some data which is represented by -the \helpref{wxDataObject}{wxdataobject} class. It is capable to contain any kind -data in one of any of predefined formats (see enum \helpref{StdFormatand}{stdformat}) and is smart enough to describe the format -of data it contains. There is also a specialization of this class which stores -only text - the only difference between \helpref{wxTextDataObject}{wxtextdataobject} and wxDataObject is that the -first one is easily constructed from wxString. - -Also, for both kinds of operations, there is a sender which provides data and -a receiver who gets it. The sender is responsible for constructing the -wxDataObject and the receiver can query it and process the data it contains -in any way he likes. - -In the case of a drag and drop operation, the sender is called a {\it drop -source} while the receiver is a {\it dtop target}. There are several steps in -the dragging process: +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: \begin{itemize}\itemsep=0pt -\item {\bf preparation} First of all, the data object must be created and -initilized with the data you wish to drag. For example: +\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} - wxTextDataObject data("This string will be dragged."); -\end{verbatim}. Of course, the data object may contain arbitrary data of any -type. + 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{wxDropSource::DoDragDrop}{wxdropsourcedodragdrop} +like this: -\item{drag start} This happens when you call \helpref{DoDragDrop}{wxdropsourcedodragdrop} function. For this you must first -construct a wxDropSource object and associate the data object from the -previous step with it 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 the program until the user release the +mouse button (unless you override \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 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 {\tt wxDragResult} enum (explained \helpref{here}{wxdroptarget}): \begin{verbatim} - wxDropSource dragSource(data, this); + switch (result) + { + case wxDragCopy: /* copy the data */ break; + case wxDragMove: /* move the data */ break; + default: /* do nothing */ break; + } +\end{verbatim} +\end{itemize} - // or also: - wxDropSource dragSource(this); - dragSource.SetData(data); -\end{verbatim}, +To be a {\it drop target}, i.e. to receive the data dropped by user you should +follow the instructions below: -\item {\bf dragging} The call to DoDragDrop() blocks until the user release the -mouse button (unless you override \helpref{GiveFeedback}{wxdropsourcegivefeedback} function to do something -special). When the mouse moves in a window of a wxWindows program, the -corresponding wxDropTarget methods are called (the data can be also dragged to -any other program under Windows or to any program supporting the same protocol -under X Windows). -\item {\bf drop} When the user releases the mouse over a window, wxWindows verifies -if the wxDropTarget object associated (with \helpref{SetDropTarget}{setdroptarget}) with this window 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 the end} Finally, the receiver processes the data (e.g. pastes the text -in its window). DoDragDrop() returns either wxDragCopy or wxDragMove -depending on the state of the keys (, and ) at the moment -of drop. +\begin{itemize}\itemsep=0pt +\item {\bf Initialization:} For a window to be 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 +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, +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 +target to change this return code. \end{itemize}