docs/doxygen/overviews/dataobject.h

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