Some documentation enhancements for wxRichTextCtrl

[wxWidgets.git] / docs / latex / wx / tdnd.tex

diff --git a/docs/latex/wx/tdnd.tex b/docs/latex/wx/tdnd.tex
index 8251c44d9257afef6353c9ac33dbde08b868779f..dbbe6daaf2f82298d0dc0820cf75de897aa51040 100644 (file)
--- 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 and 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 and drop in wxWidgets.

 
 

-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 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.

 
 

-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
+the user elsewhere, you should implement the following steps:

 
 \begin{itemize}\itemsep=0pt
 
 \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}
 
 \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 the 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 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 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}
 
 \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 the 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 (<Ctrl>, <Shift> and <Alt>) at the moment
-of drop.
+\begin{itemize}\itemsep=0pt
+\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 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, 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 <Ctrl>, <Shift>
+and <Alt> at the moment of the drop. There is currently no way for the drop
+target to change this return code.

 \end{itemize}
 
 \end{itemize}