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