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{Library}
  26
  27 \helpref{wxCore}{librarieslist}
  28
  29 \wxheading{Types}
  30
  31 \index{wxDragResult}wxDragResult is defined as follows:
  32
  33 \begin{verbatim}
  34 enum wxDragResult
  35 {
  36     wxDragError,    // error prevented the d&d operation from completing
  37     wxDragNone,     // drag target didn't accept the data
  38     wxDragCopy,     // the data was successfully copied
  39     wxDragMove,     // the data was successfully moved (MSW only)
  40     wxDragLink,     // operation is a drag-link
  41     wxDragCancel    // the operation was cancelled by user (not an error)
  42 };
  43 \end{verbatim}
  44
  45 \wxheading{See also}
  46
  47 \helpref{wxDropSource}{wxdropsource},
  48 \helpref{wxTextDropTarget}{wxtextdroptarget}, \helpref{wxFileDropTarget}{wxfiledroptarget},
  49 \helpref{wxDataFormat}{wxdataformat}, \helpref{wxDataObject}{wxdataobject}
  50
  51 \latexignore{\rtfignore{\wxheading{Members}}}
  52
  53 \membersection{wxDropTarget::wxDropTarget}\label{wxdroptargetwxdroptarget}
  54
  55 \func{}{wxDropTarget}{\param{wxDataObject*}{ data = NULL}}
  56
  57 Constructor. {\it data} is the data to be associated with the drop target.
  58
  59 \membersection{wxDropTarget::\destruct{wxDropTarget}}\label{wxdroptargetdtor}
  60
  61 \func{}{\destruct{wxDropTarget}}{\void}
  62
  63 Destructor. Deletes the associated data object, if any.
  64
  65 \membersection{wxDropTarget::GetData}\label{wxdroptargetgetdata}
  66
  67 \func{virtual void}{GetData}{\void}
  68
  69 This method may only be called from within \helpref{OnData}{wxdroptargetondata}.
  70 By default, this method copies the data from the drop source to the
  71 \helpref{wxDataObject}{wxdataobject} associated with this drop target,
  72 calling its \helpref{wxDataObject::SetData}{wxdataobjectsetdata} method.
  73
  74 \membersection{wxDropTarget::OnData}\label{wxdroptargetondata}
  75
  76 \func{virtual wxDragResult}{OnData}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxDragResult}{ def}}
  77
  78 Called after \helpref{OnDrop}{wxdroptargetondrop} returns true. By default this
  79 will usually \helpref{GetData}{wxdroptargetgetdata} and will return the suggested
  80 default value {\it def}.
  81
  82 \membersection{wxDropTarget::OnDrop}\label{wxdroptargetondrop}
  83
  84 \func{virtual bool}{OnDrop}{\param{wxCoord }{x}, \param{wxCoord }{y}}
  85
  86 Called when the user drops a data object on the target. Return false to veto the operation.
  87
  88 \wxheading{Parameters}
  89
  90 \docparam{x}{The x coordinate of the mouse.}
  91
  92 \docparam{y}{The y coordinate of the mouse.}
  93
  94 \wxheading{Return value}
  95
  96 Return true to accept the data, false to veto the operation.
  97
  98 \membersection{wxDropTarget::OnEnter}\label{wxdroptargetonenter}
  99
 100 \func{virtual wxDragResult}{OnEnter}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxDragResult}{ def}}
 101
 102 Called when the mouse enters the drop target. By default, this calls \helpref{OnDragOver}{wxdroptargetondragover}.
 103
 104 \wxheading{Parameters}
 105
 106 \docparam{x}{The x coordinate of the mouse.}
 107
 108 \docparam{y}{The y coordinate of the mouse.}
 109
 110 \docparam{def}{Suggested default for return value. Determined by SHIFT or CONTROL key states.}
 111
 112 \wxheading{Return value}
 113
 114 Returns the desired operation or {\tt wxDragNone}. This is used for optical feedback
 115 from the side of the drop source, typically in form of changing the icon.
 116
 117 \membersection{wxDropTarget::OnDragOver}\label{wxdroptargetondragover}
 118
 119 \func{virtual wxDragResult}{OnDragOver}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxDragResult}{ def}}
 120
 121 Called when the mouse is being dragged over the drop target. By default,
 122 this calls functions return the suggested return value {\it def}.
 123
 124 \wxheading{Parameters}
 125
 126 \docparam{x}{The x coordinate of the mouse.}
 127
 128 \docparam{y}{The y coordinate of the mouse.}
 129
 130 \docparam{def}{Suggested value for return value. Determined by SHIFT or CONTROL key states.}
 131
 132 \wxheading{Return value}
 133
 134 Returns the desired operation or {\tt wxDragNone}. This is used for optical feedback
 135 from the side of the drop source, typically in form of changing the icon.
 136
 137 \membersection{wxDropTarget::OnLeave}\label{wxdroptargetonleave}
 138
 139 \func{virtual void}{OnLeave}{\void}
 140
 141 Called when the mouse leaves the drop target.
 142
 143 \membersection{wxDropTarget::SetDataObject}\label{wxdroptargetsetdataobject}
 144
 145 \func{void}{SetDataObject}{\param{wxDataObject*}{ data}}
 146
 147 Sets the data \helpref{wxDataObject}{wxdataobject} associated with the
 148 drop target and deletes any previously associated data object.
 149