docs/latex/wx/tclipbrd.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        tclipbrd.tex
   3 %% Purpose:     Data transfer (clipboard and drag and drop) overview
   4 %% Author:      Vadim Zeitlin
   5 %% Modified by:
   6 %% Created:     18.10.99
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) Vadim Zeitlin
   9 %% Licence:     wxWindows licence
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{Clipboard and drag and drop overview}\label{wxclipboardonfigoverview}
  13
  14 Classes: \helpref{wxDataObject}{wxdataobject},
  15  \helpref{wxClipboard}{wxclipboard},
  16  \helpref{wxDataFormat}{wxdataformat},
  17  \helpref{wxDropSource}{wxdropsource},
  18  \helpref{wxDropTarget}{wxdroptarget}
  19
  20 This overview discusses data transfer through clipboard or drag and drop. In
  21 wxWindows, these two ways to transfer data (either between different
  22 applications or inside one and the same) are very similar which allows to
  23 implement both of them using almost the same code - or in other
  24 words, if you implement drag and drop support for your application, you get
  25 clipboard support for free and vice versa.
  26
  27 In the heart of both clipboard and drag and drop operations lies the
  28 \helpref{wxDataObject}{wxdataobject} class. The objects of this class (or, to be
  29 precise, classes derived from it) represent the data which is being carried by
  30 the mouse during drag and drop operation or copied to or pasted from the
  31 clipboard. wxDataObject is a "smart" piece of data
  32 because it knows which formats it supports (see
  33 GetFormatCount and GetAllFormats) and knows how to render
  34 itself in any of them (see GetDataHere).
  35 It can also receive its value from the outside in a format it supports if it
  36 implements the SetData method.
  37
  38 Both clipboard and drag and drop operations have two sides: the source and
  39 target, the data provider and the data receiver. These which may be in the same
  40 application and even the same window when, for example, you drag some text from
  41 one position to another in a word processor. Let us describe what each of them
  42 should do.
  43
  44 \subsection{The data provider (source) duties}{wxdataobjectsource}
  45
  46 The data provider is responsible for creating a
  47 \helpref{wxDataObject}{wxdataobjectwxdataobject} containing the data to be
  48 transfered. Then it should either pass it to the clipboard using
  49 \helpref{AddData}{wxclipboardadddata} or \helpref{SetData}{wxclipboardsetdata}
  50 functions or to \helpref{wxDropSource}{wxdropsource} and call
  51 \helpref{DoDragDrop}{wxdropsourcedodragdrop} function.
  52
  53 The only (but important) difference is that the object for the clipboard
  54 transfer must always be created on the heap (i.e. using {\tt new}) and it will
  55 be freed by the clipboard when it is no longer needed (indeed, it is not known
  56 in advance when, if ever, the data will be pasted from the clipboard). On the
  57 other hand, the object for drag and drop operation must only exist while
  58 \helpref{DoDragDrop}{wxdropsourcedodragdrop} executes and may be safely deleted
  59 afterwards and so can be created either on heap or on stack (i.e. as a local
  60 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 \helpref{DoDragDrop}{wxdropsourcedodragdrop} returns (from its return value).
  67
  68 \subsection{The data receiver (target) duties}{wxdataobjecttarget}
  69
  70 To receive (paste in usual terminology) data from the clipboard, you should
  71 create a \helpref{wxDataObject}{wxdataobject} derived class which supports the
  72 data formats you need and pass it as argument to
  73 \helpref{wxClipboard::GetData}{wxclipboardgetdata}. If it returns {\tt FALSE},
  74 no data in (any of) the supported format(s) is available. If it returns {\tt
  75 TRUE}, the data has been successfully transfered to wxDataObject.
  76
  77 {\bf TODO} document drag and drop side when the API is finalised
  78
  79 % !!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  80 % Vadim, please remember the new line at the end of each file. Please
  81 % also remember to compile the .hlp file to check for bad references etc.,
  82 % before checking in. I have removed references that were unresolved. - JACS