From 23d277e683b40c84cf27a538d24e1acc019661a8 Mon Sep 17 00:00:00 2001
From: Vadim Zeitlin <vadim@wxwidgets.org>
Date: Sun, 17 Oct 1999 23:57:10 +0000
Subject: [PATCH] attempt at documenting drag and drop and clipboard classes

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@4038 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
---
 docs/latex/wx/tclipbrd.tex | 78 ++++++++++++++++++++++++++++++++++++++
 docs/latex/wx/topics.tex   |  1 +
 2 files changed, 79 insertions(+)
 create mode 100644 docs/latex/wx/tclipbrd.tex

diff --git a/docs/latex/wx/tclipbrd.tex b/docs/latex/wx/tclipbrd.tex
new file mode 100644
index 0000000000..e44c023308
--- /dev/null
+++ b/docs/latex/wx/tclipbrd.tex
@@ -0,0 +1,78 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        tclipbrd.tex
+%% Purpose:     Data transfer (clipboard and drag and drop) overview
+%% Author:      Vadim Zeitlin
+%% Modified by:
+%% Created:     18.10.99
+%% RCS-ID:      $Id$
+%% Copyright:   (c) Vadim Zeitlin
+%% Licence:     wxWindows licence
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{Clipboard and drag and drop overview}\label{wxclipboardonfigoverview}
+
+Classes: \helpref{wxDataObject}{wxdataobject},
+         \helpref{wxClipboard}{wxclipboard},
+         \helpref{wxDataFormat}{wxdataformat},
+         \helpref{wxDropSource}{wxdropsource},
+         \helpref{wxDropTarget}{wxdroptarget}
+
+This overview discusses data transfer through clipboard or drag and drop. In
+wxWindows, these two ways to transfer data (either between different
+applications or inside one and the same) are very similar which allows to
+implement both of them using almost the same code - or, to say it in other
+words, if you implement drag and drop support for your application, you get
+clipboard support for free and vice versa.
+
+In the heart of both clipboard and drag and drop operations lies the 
+\helpref{wxDataObject}{wxdataobject} class. The objects of this (or, to be
+precise, derived from it) class represent the data which is being carried by
+the mouse during drag and drop operation or copied to or pasted from the
+clipboard. \helpref{wxDataObject}{wxdataobject} is a "smart" piece of data
+because it knows which \helpref{formats}{wxdataformat} it supports (see 
+\helpref{GetFormatCount}{wxdataobjectgetformatcount} and 
+\helpref{GetAllFormats}{wxdataobjectgetallformats}) and knows how to render
+itself in any of them (see \helpref{GetDataHere.}{wxdataobjectgetdatahere}).
+It can also receive its value from the outside in a format it supports if it
+implements \helpref{SetData}{wxdataobjectsetdata} method.
+
+Both clipboard and drag and drop operations have two sides: the source and
+target, the data provider and the data receiver (which may be the same
+application and even the same window when, for example, you drag some text from
+one position to another in a word processor). Let us describe what each of them
+should do.
+
+\subsection{The data provider (source) duties}{wxdataobjectsource}
+
+The data provider is responsible for creating a 
+\helpref{wxDataObject}{wxdataobjectwxdataobject} containing the data to be
+transfered. Then it should either pass it to the clipboard using
+\helpref{AddData}{wxclipboardadddata} or \helpref{SetData}{wxclipboardsetdata}
+functions or to \helpref{wxDropSource}{wxdropsource} and call 
+\helpref{DoDragDrop}{wxdropsourcedodragdrop} function.
+
+The only (but important) difference is that the object for the clipboard
+transfer must always be created on the heap (i.e. using {\tt new}) and it will
+be freed by the clipboard when it is no longer needed (indeed, it is not known
+in advance when, if ever, the data will be pasted from the clipboard). On the
+other hand, the object for drag and drop operation must only exist while 
+\helpref{DoDragDrop}{wxdropsourcedodragdrop} executes and may be safely deleted
+afterwards and so can be created either on heap or on stack (i.e. as a local
+variable).
+
+Another small difference si that in the case of clipboard operation, the
+application usually knows in advance whether it copies or cuts (i.e. copies and
+deletes) data - in fact, this usually depends on which menu item the user
+chose. But for drag and drop it can only know it after 
+\helpref{DoDragDrop}{wxdropsourcedodragdrop} returns (from its return value).
+
+\subsection{The data receiver (target) duties}{wxdataobjecttarget}
+
+To receive (paste in usual terminology) data from the clipboard, you should
+create a \helpref{wxDataObject}{wxdataobject} derived class which supports the
+data formats you need and pass it as argument to 
+\helpref{wxClipboard::GetData}{wxclipboardgetdata}. If it returns {\tt FALSE},
+no data in (any of) the supported format(s) is available. If it returns {\tt
+TRUE}, the data has been successfully transfered to wxDataObject.
+
+{\bf TODO} document drag and drop side when the API is finalised
diff --git a/docs/latex/wx/topics.tex b/docs/latex/wx/topics.tex
index 225df7798f..6d3dbcf106 100644
--- a/docs/latex/wx/topics.tex
+++ b/docs/latex/wx/topics.tex
@@ -10,6 +10,7 @@ This chapter contains a selection of topic overviews.
 \input tlog.tex
 \input tconfig.tex
 \input tunicode.tex
+\input tclipbrd.tex
 \input tbitmap.tex
 \input tdialog.tex
 \input tfont.tex
-- 
2.45.2