(very) preliminary DnD docs

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@1136 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

diff --git a/docs/latex/wx/tdnd.tex b/docs/latex/wx/tdnd.tex
new file mode 100644 (file)
index 0000000..67c9b6b
--- /dev/null
+++ b/docs/latex/wx/tdnd.tex
@@ -0,0 +1,74 @@
+\section{Drag-and-drop and clipboard overview}\label{wxdndoverview}
+
+Classes: \helpref{wxDataObject}wxdataobject
+
+% \helpref{wxTextDataObject}wxtextdataobject
+% \helpref{wxDropSource}wxdropsource
+% \helpref{wxDropTarget}{wxdroptarget}
+% \helpref{wxTextDropTarget}{wxtextdroptarget}
+% \helpref{wxFileDropTarget}{wxfiledroptarget}
+
+Samples: see the dnd sample.
+
+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.
+
+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:
+\begin{itemize}\itemsep=0pt
+\item{preparation} First of all, the data object must be created and
+initilized 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.
+\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(data, this);
+
+       // or also:
+       wxDropSource dragSource(this);
+       dragSource.SetData(data);
+\end{verbatim},
+\item{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{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{the end} Finally, the receiver processes the data (e.g. pastes the text
+in it's window). DoDragDrop() returns either wxDragCopy or wxDragMove
+depending on the state of the keys (<Ctrl>, <Shift> and <Alt>) at the moment
+of drop.
+\end{itemize}
+

diff --git a/docs/latex/wx/topics.tex b/docs/latex/wx/topics.tex
index a10357aaa5e84aed3b6fa2f0546ff9f11eab1e98..c566f0cea98be8c86493a976823f6c1dfdc3ffb9 100644 (file)
--- a/docs/latex/wx/topics.tex
+++ b/docs/latex/wx/topics.tex
@@ -35,5 +35,5 @@ This chapter contains a selection of topic overviews.
 \input texpr.tex
 \input tgrid.tex
 \input tstring.tex
+\input tdnd.tex
 \input tusage.tex
-