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