docs/doxygen/overviews/dataobject.h

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