ugh. Nesting the (per class) plugin sentries can require them to

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

diff --git a/docs/latex/wx/droptrgt.tex b/docs/latex/wx/droptrgt.tex
index 30e206c4e7c92b54e954814e0989383da117fdcd..eb9ca1eed657218f3b14b0031057fd358ba3c1f1 100644 (file)
--- a/docs/latex/wx/droptrgt.tex
+++ b/docs/latex/wx/droptrgt.tex
@@ -1,61 +1,82 @@
 \section{\class{wxDropTarget}}\label{wxdroptarget}
 
 \section{\class{wxDropTarget}}\label{wxdroptarget}
 

-\overview{Overview}{wxdndoverview}
+This class represents a target for a drag and drop operation. A \helpref{wxDataObject}{wxdataobject}
+can be associated with it and by default, this object will be filled with the data from the
+drag source, if the data formats supported by the data object match the drag source data 
+format.

 
 

-This class represents a target for a drag and drop operation.
+There are various virtual handler functions defined in this class which may be overridden
+to give visual feedback or react in a more fine-tuned way, e.g. by not accepting data on
+the whole window area, but only a small portion of it. The normal sequence of calls is
+\helpref{OnEnter}{wxdroptargetonenter}, possibly many times \helpref{OnDragOver}{wxdroptargetondragover},
+\helpref{OnDrop}{wxdroptargetondrop} and finally \helpref{OnData}{wxdroptargetondata}.
+
+See \helpref{Drag and drop overview}{wxdndoverview} and \helpref{wxDataObject overview}{wxdataobjectoverview}
+for more information.

 
 \wxheading{Derived from}
 
 
 \wxheading{Derived from}
 

-\helpref{wxObject}{wxobject}
+None

 
 \wxheading{Include files}
 
 <wx/dnd.h>
 
 
 \wxheading{Include files}
 
 <wx/dnd.h>
 

+\wxheading{Types}
+
+\index{wxDragResult}wxDragResult is defined as follows:
+
+\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
+    wxDragCancel    // the operation was cancelled by user (not an error)
+};
+\end{verbatim}
+

 \wxheading{See also}
 
 \wxheading{See also}
 

-\helpref{Drag and drop overview}{wxdndoverview}, \helpref{wxDropSource}{wxdropsource}, 
-\helpref{wxTextDropTarget}{wxtextdroptarget}, \helpref{wxFileDropTarget}{wxfiledroptarget}
+\helpref{wxDropSource}{wxdropsource}, 
+\helpref{wxTextDropTarget}{wxtextdroptarget}, \helpref{wxFileDropTarget}{wxfiledroptarget},
+\helpref{wxDataFormat}{wxdataformat}, \helpref{wxDataObject}{wxdataobject}

 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 \membersection{wxDropTarget::wxDropTarget}\label{wxdroptargetwxdroptarget}
 
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 \membersection{wxDropTarget::wxDropTarget}\label{wxdroptargetwxdroptarget}
 

-\func{}{wxDropTarget}{\void}
+\func{}{wxDropTarget}{\param{wxDataObject*}{ data = NULL}}

 
 

-Constructor.
+Constructor. {\it data} is the data to be associated with the drop target.

 
 \membersection{wxDropTarget::\destruct{wxDropTarget}}\label{wxdroptargetdtor}
 
 \func{}{\destruct{wxDropTarget}}{\void}
 
 
 \membersection{wxDropTarget::\destruct{wxDropTarget}}\label{wxdroptargetdtor}
 
 \func{}{\destruct{wxDropTarget}}{\void}
 

-Destructor.
-
-\membersection{wxDropTarget::GetFormatCount}\label{wxdroptargetgetformatcount}
+Destructor. Deletes the associated data object, if any.

 
 

-\constfunc{virtual size\_t}{GetFormatCount}{\void}
+\membersection{wxDropTarget::GetData}\label{wxdroptargetgetdata}

 
 

-Override this to indicate how many formats you support.
+\func{virtual void}{GetData}{\void}

 
 

-\membersection{wxDropTarget::GetFormat}\label{wxdroptargetgetformat}
-
-\constfunc{virtual wxDataFormat}{GetFormat}{\param{size\_t }{n}}
-
-Override this to indicate what kind of data you support.
+This method may only be called from within \helpref{OnData}{wxdroptargetondata}.
+By default, this method copies the data from the drop source to the 
+\helpref{wxDataObject}{wxdataobject} associated with this drop target,
+calling its \helpref{wxDataObject::SetData}{wxdataobjectsetdata} method.

 
 \membersection{wxDropTarget::OnData}\label{wxdroptargetondata}
 
 \func{virtual wxDragResult}{OnData}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxDragResult}{ def}}
 
 
 \membersection{wxDropTarget::OnData}\label{wxdroptargetondata}
 
 \func{virtual wxDragResult}{OnData}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxDragResult}{ def}}
 

-Called after OnDrop() returns TRUE: you will usually just call
-GetData() from here and, probably, also refresh something to update the
-new data and, finally, return the code indicating how did the operation
-complete (returning default value in case of success and wxDragError on
-failure is usually ok).
+Called after \helpref{OnDrop}{wxdroptargetondrop} returns TRUE. By default this
+will usually \helpref{GetData}{wxdroptargetgetdata} and will return the suggested
+default value {\it def}.

 
 \membersection{wxDropTarget::OnDrop}\label{wxdroptargetondrop}
 
 
 \membersection{wxDropTarget::OnDrop}\label{wxdroptargetondrop}
 

-\func{virtual bool}{OnDrop}{\param{long }{x}, \param{long }{y}, \param{const void* }{data}, \param{size\_t }{size}}
+\func{virtual bool}{OnDrop}{\param{wxCoord }{x}, \param{wxCoord }{y}}

 
 Called when the user drops a data object on the target. Return FALSE to veto the operation.
 
 
 Called when the user drops a data object on the target. Return FALSE to veto the operation.
 


@@ -65,19 +86,48 @@ Called when the user drops a data object on the target. Return FALSE to veto the
 
 \docparam{y}{The y coordinate of the mouse.}
 
 
 \docparam{y}{The y coordinate of the mouse.}
 

-\docparam{data}{The data being dropped.}
-
-\docparam{size}{The size of the data being dropped.}
-

 \wxheading{Return value}
 
 Return TRUE to accept the data, FALSE to veto the operation.
 
 \membersection{wxDropTarget::OnEnter}\label{wxdroptargetonenter}
 
 \wxheading{Return value}
 
 Return TRUE to accept the data, FALSE to veto the operation.
 
 \membersection{wxDropTarget::OnEnter}\label{wxdroptargetonenter}
 

-\func{virtual void}{OnEnter}{\void}
+\func{virtual wxDragResult}{OnEnter}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxDragResult}{ def}}

 
 

-Called when the mouse enters the drop target.
+Called when the mouse enters the drop target. By default, this calls \helpref{OnDragOver}{wxdroptargetondragover}.
+
+\wxheading{Parameters}
+
+\docparam{x}{The x coordinate of the mouse.}
+
+\docparam{y}{The y coordinate of the mouse.}
+
+\docparam{def}{Suggested default for return value. Determined by SHIFT or CONTROL key states.}
+
+\wxheading{Return value}
+
+Returns the desired operation or {\tt wxDragNone}. This is used for optical feedback
+from the side of the drop source, typically in form of changing the icon.
+
+\membersection{wxDropTarget::OnDragOver}\label{wxdroptargetondragover}
+
+\func{virtual wxDragResult}{OnDragOver}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxDragResult}{ def}}
+
+Called when the mouse is being dragged over the drop target. By default, 
+this calls functions return the suggested return value {\it def}.
+
+\wxheading{Parameters}
+
+\docparam{x}{The x coordinate of the mouse.}
+
+\docparam{y}{The y coordinate of the mouse.}
+
+\docparam{def}{Suggested value for return value. Determined by SHIFT or CONTROL key states.}
+
+\wxheading{Return value}
+
+Returns the desired operation or {\tt wxDragNone}. This is used for optical feedback
+from the side of the drop source, typically in form of changing the icon.

 
 \membersection{wxDropTarget::OnLeave}\label{wxdroptargetonleave}
 
 
 \membersection{wxDropTarget::OnLeave}\label{wxdroptargetonleave}
 


@@ -85,3 +135,10 @@ Called when the mouse enters the drop target.
 
 Called when the mouse leaves the drop target.
 
 
 Called when the mouse leaves the drop target.
 

+\membersection{wxDropTarget::SetDataObject}\label{wxdroptargetsetdataobject}
+
+\func{void}{SetDataObject}{\param{wxDataObject*}{ data}}
+
+Sets the data \helpref{wxDataObject}{wxdataobject} associated with the 
+drop target and deletes any previously associated data object.
+