docs/latex/wx/droptrgt.tex

   1 \section{\class{wxDropTarget}}\label{wxdroptarget}
   2
   3 This class represents a target for a drag and drop operation. A \helpref{wxDataObject}{wxdataobject}
   4 can be associated with it and by default, this object will be filled with the data from the
   5 drag source, if the data formats supported by the data object match the drag source data
   6 format.
   7
   8 There are various virtual handler functions defined in this class which may be overridden
   9 to give visual feedback or react in a more fine-tuned way, e.g. by not accepting data on
  10 the whole window area, but only a small portion of it. The normal sequence of calls is
  11 \helpref{OnEnter}{wxdroptargetonenter}, possibly many times \helpref{OnDragOver}{wxdroptargetondragover},
  12 \helpref{OnDrop}{wxdroptargetondrop} and finally \helpref{OnData}{wxdroptargetondata}.
  13
  14 See \helpref{Drag and drop overview}{wxdndoverview} and \helpref{wxDataObject overview}{wxdataobjectoverview}
  15 for more information.
  16
  17 \wxheading{Derived from}
  18
  19 None
  20
  21 \wxheading{Include files}
  22
  23 <wx/dnd.h>
  24
  25 \wxheading{Types}
  26
  27 \index{wxDragResult}wxDragResult is defined as follows:
  28
  29 \begin{verbatim}
  30 enum wxDragResult
  31 {
  32     wxDragError,    // error prevented the d&d operation from completing
  33     wxDragNone,     // drag target didn't accept the data
  34     wxDragCopy,     // the data was successfully copied
  35     wxDragMove,     // the data was successfully moved (MSW only)
  36     wxDragLink,     // operation is a drag-link
  37     wxDragCancel    // the operation was cancelled by user (not an error)
  38 };
  39 \end{verbatim}
  40
  41 \wxheading{See also}
  42
  43 \helpref{wxDropSource}{wxdropsource},
  44 \helpref{wxTextDropTarget}{wxtextdroptarget}, \helpref{wxFileDropTarget}{wxfiledroptarget},
  45 \helpref{wxDataFormat}{wxdataformat}, \helpref{wxDataObject}{wxdataobject}
  46
  47 \latexignore{\rtfignore{\wxheading{Members}}}
  48
  49 \membersection{wxDropTarget::wxDropTarget}\label{wxdroptargetwxdroptarget}
  50
  51 \func{}{wxDropTarget}{\param{wxDataObject*}{ data = NULL}}
  52
  53 Constructor. {\it data} is the data to be associated with the drop target.
  54
  55 \membersection{wxDropTarget::\destruct{wxDropTarget}}\label{wxdroptargetdtor}
  56
  57 \func{}{\destruct{wxDropTarget}}{\void}
  58
  59 Destructor. Deletes the associated data object, if any.
  60
  61 \membersection{wxDropTarget::GetData}\label{wxdroptargetgetdata}
  62
  63 \func{virtual void}{GetData}{\void}
  64
  65 This method may only be called from within \helpref{OnData}{wxdroptargetondata}.
  66 By default, this method copies the data from the drop source to the
  67 \helpref{wxDataObject}{wxdataobject} associated with this drop target,
  68 calling its \helpref{wxDataObject::SetData}{wxdataobjectsetdata} method.
  69
  70 \membersection{wxDropTarget::OnData}\label{wxdroptargetondata}
  71
  72 \func{virtual wxDragResult}{OnData}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxDragResult}{ def}}
  73
  74 Called after \helpref{OnDrop}{wxdroptargetondrop} returns true. By default this
  75 will usually \helpref{GetData}{wxdroptargetgetdata} and will return the suggested
  76 default value {\it def}.
  77
  78 \membersection{wxDropTarget::OnDrop}\label{wxdroptargetondrop}
  79
  80 \func{virtual bool}{OnDrop}{\param{wxCoord }{x}, \param{wxCoord }{y}}
  81
  82 Called when the user drops a data object on the target. Return false to veto the operation.
  83
  84 \wxheading{Parameters}
  85
  86 \docparam{x}{The x coordinate of the mouse.}
  87
  88 \docparam{y}{The y coordinate of the mouse.}
  89
  90 \wxheading{Return value}
  91
  92 Return true to accept the data, false to veto the operation.
  93
  94 \membersection{wxDropTarget::OnEnter}\label{wxdroptargetonenter}
  95
  96 \func{virtual wxDragResult}{OnEnter}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxDragResult}{ def}}
  97
  98 Called when the mouse enters the drop target. By default, this calls \helpref{OnDragOver}{wxdroptargetondragover}.
  99
 100 \wxheading{Parameters}
 101
 102 \docparam{x}{The x coordinate of the mouse.}
 103
 104 \docparam{y}{The y coordinate of the mouse.}
 105
 106 \docparam{def}{Suggested default for return value. Determined by SHIFT or CONTROL key states.}
 107
 108 \wxheading{Return value}
 109
 110 Returns the desired operation or {\tt wxDragNone}. This is used for optical feedback
 111 from the side of the drop source, typically in form of changing the icon.
 112
 113 \membersection{wxDropTarget::OnDragOver}\label{wxdroptargetondragover}
 114
 115 \func{virtual wxDragResult}{OnDragOver}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxDragResult}{ def}}
 116
 117 Called when the mouse is being dragged over the drop target. By default,
 118 this calls functions return the suggested return value {\it def}.
 119
 120 \wxheading{Parameters}
 121
 122 \docparam{x}{The x coordinate of the mouse.}
 123
 124 \docparam{y}{The y coordinate of the mouse.}
 125
 126 \docparam{def}{Suggested value for return value. Determined by SHIFT or CONTROL key states.}
 127
 128 \wxheading{Return value}
 129
 130 Returns the desired operation or {\tt wxDragNone}. This is used for optical feedback
 131 from the side of the drop source, typically in form of changing the icon.
 132
 133 \membersection{wxDropTarget::OnLeave}\label{wxdroptargetonleave}
 134
 135 \func{virtual void}{OnLeave}{\void}
 136
 137 Called when the mouse leaves the drop target.
 138
 139 \membersection{wxDropTarget::SetDataObject}\label{wxdroptargetsetdataobject}
 140
 141 \func{void}{SetDataObject}{\param{wxDataObject*}{ data}}
 142
 143 Sets the data \helpref{wxDataObject}{wxdataobject} associated with the
 144 drop target and deletes any previously associated data object.
 145