docs/latex/wx/tclipbrd.tex

   1 \section{wxDataObject overview}\label{wxdataobjectoverview}
   2
   3 Classes: \helpref{wxDataObject}{wxdataobject},
   4  \helpref{wxClipboard}{wxclipboard},
   5  \helpref{wxDataFormat}{wxdataformat},
   6  \helpref{wxDropSource}{wxdropsource},
   7  \helpref{wxDropTarget}{wxdroptarget}
   8
   9 See also: \helpref{Drag and drop overview}{wxdndoverview} and \helpref{DnD sample}{samplednd}
  10
  11 This overview discusses data transfer through clipboard or drag and drop. In
  12 wxWidgets, these two ways to transfer data (either between different
  13 applications or inside one and the same) are very similar which allows to
  14 implement both of them using almost the same code - or, in other
  15 words, if you implement drag and drop support for your application, you get
  16 clipboard support for free and vice versa.
  17
  18 At the heart of both clipboard and drag and drop operations lies the
  19 \helpref{wxDataObject}{wxdataobject} class. The objects of this class (or, to
  20 be precise, classes derived from it) represent the data which is being carried
  21 by the mouse during drag and drop operation or copied to or pasted from the
  22 clipboard. wxDataObject is a "smart" piece of data because it knows which
  23 formats it supports (see GetFormatCount and GetAllFormats) and knows how to
  24 render itself in any of them (see GetDataHere). It can also receive its value
  25 from the outside in a format it supports if it implements the SetData method.
  26 Please see the documentation of this class for more details.
  27
  28 Both clipboard and drag and drop operations have two sides: the source and
  29 target, the data provider and the data receiver. These which may be in the same
  30 application and even the same window when, for example, you drag some text from
  31 one position to another in a word processor. Let us describe what each of them
  32 should do.
  33
  34 \subsection{The data provider (source) duties}\label{wxdataobjectsource}
  35
  36 The data provider is responsible for creating a
  37 \helpref{wxDataObject}{wxdataobject} containing the data to be
  38 transferred. Then it should either pass it to the clipboard using
  39 \helpref{SetData}{wxclipboardsetdata} function or to
  40 \helpref{wxDropSource}{wxdropsource} and call
  41 \helpref{DoDragDrop}{wxdropsourcedodragdrop} function.
  42
  43 The only (but important) difference is that the object for the clipboard
  44 transfer must always be created on the heap (i.e. using {\tt new}) and it will
  45 be freed by the clipboard when it is no longer needed (indeed, it is not known
  46 in advance when, if ever, the data will be pasted from the clipboard). On the
  47 other hand, the object for drag and drop operation must only exist while
  48 \helpref{DoDragDrop}{wxdropsourcedodragdrop} executes and may be safely deleted
  49 afterwards and so can be created either on heap or on stack (i.e. as a local
  50 variable).
  51
  52 Another small difference is that in the case of clipboard operation, the
  53 application usually knows in advance whether it copies or cuts (i.e. copies and
  54 deletes) data - in fact, this usually depends on which menu item the user
  55 chose. But for drag and drop it can only know it after
  56 \helpref{DoDragDrop}{wxdropsourcedodragdrop} returns (from its return value).
  57
  58 \subsection{The data receiver (target) duties}\label{wxdataobjecttarget}
  59
  60 To receive (paste in usual terminology) data from the clipboard, you should
  61 create a \helpref{wxDataObject}{wxdataobject} derived class which supports the
  62 data formats you need and pass it as argument to
  63 \helpref{wxClipboard::GetData}{wxclipboardgetdata}. If it returns {\tt false},
  64 no data in (any of) the supported format(s) is available. If it returns {\tt
  65 true}, the data has been successfully transferred to wxDataObject.
  66
  67 For drag and drop case, the \helpref{wxDropTarget::OnData}{wxdroptargetondata}
  68 virtual function will be called when a data object is dropped, from which the
  69 data itself may be requested by calling
  70 \helpref{wxDropTarget::GetData}{wxdroptargetwxdroptarget} method which fills
  71 the data object.
  72