added wxTopLevelWindow::RequestUserAttention(); documented it and implemented it...

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

diff --git a/docs/latex/wx/tdnd.tex b/docs/latex/wx/tdnd.tex
index 15a11035e87269e1bc92dcaeb827527260bd5af3..dbbe6daaf2f82298d0dc0820cf75de897aa51040 100644 (file)
--- 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}, 
 
 Classes: \helpref{wxDataObject}{wxdataobject}, 
 \helpref{wxTextDataObject}{wxtextdataobject}, 


@@ -7,91 +7,78 @@ Classes: \helpref{wxDataObject}{wxdataobject},
 \helpref{wxTextDropTarget}{wxtextdroptarget}, 
 \helpref{wxFileDropTarget}{wxfiledroptarget}
 
 \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
-protocol 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
 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
 
 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
 
 \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}
 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}
 \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 );
 
 \begin{verbatim}
        wxDropSource dragSource( this );
        dragSource.SetData( my_data );

+       wxDragResult result = dragSource.DoDragDrop( TRUE );

 \end{verbatim}
 \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
 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
 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}
 
 \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
 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
 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.
 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
 \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 drop. There is currently no way for the drop
+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}
 
 target to change this return code.
 \end{itemize}