mention that Wait() relocks the mutex before returning (patch 1482390)

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

diff --git a/docs/latex/wx/dropsrc.tex b/docs/latex/wx/dropsrc.tex
index dd426c53d8439f8bc998baee5ca819e4dca672d0..f0c4e90ff8f185af66c397a231b063cb483e1043 100644 (file)
--- a/docs/latex/wx/dropsrc.tex
+++ b/docs/latex/wx/dropsrc.tex
@@ -2,7 +2,7 @@
 
 This class represents a source for a drag and drop operation.
 
-See \helpref{Drag'n'Drop overview}{wxdndoverview} and \helpref{wxDataObject overview}{wxdataobjectoverview} 
+See \helpref{Drag and drop overview}{wxdndoverview} and \helpref{wxDataObject overview}{wxdataobjectoverview} 
 for more information.
 
 \wxheading{Derived from}
@@ -17,13 +17,14 @@ None
 
 \index{wxDragResult}wxDragResult is defined as follows:
 
-begin{verbatim}
+\begin{verbatim}
 enum wxDragResult
 {
     wxDragError,    // error prevented the d&d operation from completing
     wxDragNone,     // drag target didn't accept the data
     wxDragCopy,     // the data was successfully copied
-    wxDragMove,     // the data was successfully moved
+    wxDragMove,     // the data was successfully moved (MSW only)
+    wxDragLink,     // operation is a drag-link
     wxDragCancel    // the operation was cancelled by user (not an error)
 };
 \end{verbatim}
@@ -37,12 +38,31 @@ enum wxDragResult
 
 \membersection{wxDropSource::wxDropSource}\label{wxdropsourcewxdropsource}
 
-\func{}{wxDropSource}{\param{wxWindow*}{ win = NULL}}
+\func{}{wxDropSource}{\param{wxWindow*}{ win = NULL},\param{const wxIconOrCursor\& }{iconCopy = wxNullIconOrCursor}, \param{const wxIconOrCursor\& }{iconMove = wxNullIconOrCursor}, \param{const wxIconOrCursor\& }{iconNone = wxNullIconOrCursor}}
 
-Default/wxGTK-specific constructor. If you use the default constructor you must
-call \helpref{SetData}{wxdropsourcesetdata} later.
+\func{}{wxDropSource}{\param{wxDataObject\&}{ data}, \param{wxWindow*}{ win = NULL},\param{const wxIconOrCursor\& }{iconCopy = wxNullIconOrCursor}, \param{const wxIconOrCursor\& }{iconMove = wxNullIconOrCursor}, \param{const wxIconOrCursor\& }{iconNone = wxNullIconOrCursor}}
 
-Note that {\it win} is required by the GTK port and therefore should always be set.
+The constructors for wxDataObject.
+
+If you use the constructor without {\it data} parameter you must call 
+\helpref{SetData}{wxdropsourcesetdata} later.
+
+Note that the exact type of {\it iconCopy} and subsequent parameters differs
+between wxMSW and wxGTK: these are cursors under Windows but icons for GTK.
+You should use the macro \helpref{wxDROP\_ICON}{wxdropicon} in portable
+programs instead of directly using either of these types.
+
+\wxheading{Parameters}
+
+\docparam{win}{The window which initiates the drag and drop operation.}
+
+\docparam{iconCopy}{The icon or cursor used for feedback for copy operation.}
+
+\docparam{iconMove}{The icon or cursor used for feedback for move operation.}
+
+\docparam{iconNone}{The icon or cursor used for feedback when operation can't be done.}
+
+{\it win} is the window which initiates the drag and drop operation.
 
 \membersection{wxDropSource::\destruct{wxDropSource}}\label{wxdropsourcedtor}
 
@@ -57,15 +77,33 @@ drop source. This will not delete any previously associated data.
 
 \membersection{wxDropSource::DoDragDrop}\label{wxdropsourcedodragdrop}
 
-\func{virtual wxDragResult}{DoDragDrop}{\param{bool }{allowMove = FALSE}}
+\func{virtual wxDragResult}{DoDragDrop}{\param{int }{flags = {\tt wxDrag\_CopyOnly}}}
+
+Do it (call this in response to a mouse button press, for example). This starts
+the drag-and-drop operation which will terminate when the user releases the
+mouse.
+
+\wxheading{Parameters}
+
+\docparam{flags}{If {\tt wxDrag\_AllowMove} is included in the flags, data may
+be moved and not only copied (default). If {\tt wxDrag\_DefaultMove} is
+specified (which includes the previous flag), this is even the default
+operation}.
+
+\wxheading{Return value}
+
+Returns the operation requested by the user, may be {\tt wxDragCopy}, {\tt
+wxDragMove}, {\tt wxDragLink}, {\tt wxDragCancel} or {\tt wxDragNone} if an error occurred.
+
+\membersection{wxDropSource::GetDataObject}\label{wxdropsourcegetdataobject}
 
-Do it (call this in response to a mouse button press, for example).
+\func{wxDataObject *}{GetDataObject}{\void}
 
-If {\bf allowMove} is FALSE, data can only be copied.
+Returns the wxDataObject object that has been assigned previously.
 
 \membersection{wxDropSource::GiveFeedback}\label{wxdropsourcegivefeedback}
 
-\func{virtual bool}{GiveFeedback}{\param{wxDragResult }{effect}, \param{bool }{scrolling}}
+\func{virtual bool}{GiveFeedback}{\param{wxDragResult }{effect}}
 
 Overridable: you may give some custom UI feedback during the drag and drop operation
 in this function. It is called on each mouse move, so your implementation must not be too
@@ -73,12 +111,24 @@ slow.
 
 \wxheading{Parameters}
 
-\docparam{effect}{The effect to implement. One of wxDragCopy, wxDragMove and wxDragNone. }
+\docparam{effect}{The effect to implement. One of {\tt wxDragCopy}, {\tt wxDragMove}, {\tt wxDragLink} and {\tt wxDragNone}. }
 
-\docparam{scrolling}{TRUE if the window is scrolling. MSW only. }
+\docparam{scrolling}{true if the window is scrolling. MSW only. }
 
 \wxheading{Return value}
 
-Return FALSE if you want default feedback, or TRUE if you implement your own
+Return false if you want default feedback, or true if you implement your own
 feedback. The return values is ignored under GTK.
 
+\membersection{wxDropSource::SetCursor}\label{wxdropsourcesetcursor}
+
+\func{void}{SetCursor}{\param{wxDragResult }{res}, \param{const wxCursor\& }{cursor}}
+
+Set the icon to use for a certain drag result.
+
+\wxheading{Parameters}
+
+\docparam{res}{The drag result to set the icon for. }
+
+\docparam{cursor}{The ion to show when this drag result occurs. }
+