docs/latex/wx/tdnd.tex

   1 \section{Drag-and-drop and clipboard overview}\label{wxdndoverview}
   2
   3 Classes: \helpref{wxDataObject}wxdataobject
   4
   5 % \helpref{wxTextDataObject}wxtextdataobject
   6 % \helpref{wxDropSource}wxdropsource
   7 % \helpref{wxDropTarget}{wxdroptarget}
   8 % \helpref{wxTextDropTarget}{wxtextdroptarget}
   9 % \helpref{wxFileDropTarget}{wxfiledroptarget}
  10
  11 Samples: see the dnd sample.
  12
  13 This overview describes wxWindows support for drag and drop and clipboard
  14 operations. Both of these topics are discussed here because, in fact, they're
  15 quite related. Drag and drop and clipboard are just too ways of passing the
  16 data around and so the code required to implement both types of the operations
  17 is almost the same.
  18
  19 In any case, you work with some data which is represented by the
  20 \helpref{wxDataObject}{wxdataobject} class. It is capable to contain any kind
  21 data in one of any of predefined formats (see enum
  22 \helpref{StdFormatand}{stdformat}) and is smart enough to describe the format
  23 of data it contains. There is also a specialization of this class which stores
  24 only text - the only difference between
  25 \helpref{wxTextDataObject}{wxtextdataobject} and wxDataObject is that the
  26 first one is easily constructed from wxString.
  27
  28 Also, for both kinds of operations, there is a sender which provides data and
  29 a receiver who gets it. The sender is responsible for constructing the
  30 wxDataObject and the receiver can query it and process the data it contains
  31 in any way he likes.
  32
  33 In the case of a drag and drop operation, the sender is called a {\it drop
  34 source} while the receiver is a {\it dtop target}. There are several steps in
  35 the dragging process:
  36 \begin{itemize}\itemsep=0pt
  37 \item{preparation} First of all, the data object must be created and
  38 initilized with the data you wish to drag. For example:
  39 \begin{verbatim}
  40         wxTextDataObject data("This string will be dragged.");
  41 \end{verbatim}. Of course, the data object may contain arbitrary data of any
  42 type.
  43 \item{drag start} This happens when you call
  44 \helpref{DoDragDrop}{wxdropsourcedodragdrop} function. For this you must first
  45 construct a wxDropSource object and associate the data object from the
  46 previous step with it like this:
  47 \begin{verbatim}
  48         wxDropSource dragSource(data, this);
  49
  50         // or also:
  51         wxDropSource dragSource(this);
  52         dragSource.SetData(data);
  53 \end{verbatim},
  54 \item{dragging} The call to DoDragDrop() blocks until the user release the
  55 mouse button (unless you override
  56 \helpref{GiveFeedback}{wxdropsourcegivefeedback} function to do something
  57 special). When the mouse moves in a window of a wxWindows program, the
  58 corresponding wxDropTarget methods are called (the data can be also dragged to
  59 any other program under Windows or to any program supporting the same protocol
  60 under X Windows).
  61 \item{drop} When the user releases the mouse over a window, wxWindows verifies
  62 if the wxDropTarget object associated (with
  63 \helpref{SetDropTarget}{setdroptarget}) with this window accepts the data. For
  64 this, \helpref{GetFormatCount}{wxdroptargetgetformatcount} and
  65 \helpref{GetFormat}{wxdroptargetgetformat} are used and if the format is
  66 supported (i.e. is one of returned by GetFormat()), then
  67 \helpref{OnDrop}{wxdroptargetondrop} is called. Otherwise, wxDragNone is
  68 returned by DoDragDrop() and nothing happens.
  69 \item{the end} Finally, the receiver processes the data (e.g. pastes the text
  70 in it's window). DoDragDrop() returns either wxDragCopy or wxDragMove
  71 depending on the state of the keys (<Ctrl>, <Shift> and <Alt>) at the moment
  72 of drop.
  73 \end{itemize}
  74