From c03648c25140e0286a47e32f93f1d2f1ad3011c3 Mon Sep 17 00:00:00 2001
From: Vadim Zeitlin <vadim@wxwidgets.org>
Date: Wed, 3 Nov 1999 00:29:20 +0000
Subject: [PATCH] more dnd/clipboard docs

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@4328 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
---
 docs/latex/wx/category.tex |   1 +
 docs/latex/wx/classes.tex  |   5 +-
 docs/latex/wx/dataform.tex | 115 +++++++++++++++++++++++++++++++++++++
 docs/latex/wx/dataobj.tex  |  10 ++--
 docs/latex/wx/tclipbrd.tex |   2 +-
 docs/latex/wx/topics.tex   |   2 +-
 docs/latex/wx/tsamples.tex |   2 +-
 docs/latex/wx/wx.hpj       |   6 +-
 8 files changed, 130 insertions(+), 13 deletions(-)
 create mode 100644 docs/latex/wx/dataform.tex

diff --git a/docs/latex/wx/category.tex b/docs/latex/wx/category.tex
index e6e84a62ad..55f8dc34cb 100644
--- a/docs/latex/wx/category.tex
+++ b/docs/latex/wx/category.tex
@@ -359,6 +359,7 @@ The older classes are as follows:
 
 \begin{twocollist}\itemsep=0pt
 \twocolitem{\helpref{wxDataObject}{wxdataobject}}{Data object class}
+\twocolitem{\helpref{wxDataFormat}{wxdataformat}}{Represents a data format}
 \twocolitem{\helpref{wxTextDataObject}{wxtextdataobject}}{Text data object class}
 \twocolitem{\helpref{wxFileDataObject}{wxtextdataobject}}{File data object class}
 \twocolitem{\helpref{wxBitmapDataObject}{wxbitmapdataobject}}{Bitmap data object class}
diff --git a/docs/latex/wx/classes.tex b/docs/latex/wx/classes.tex
index 26d1c333b6..5493fed36b 100644
--- a/docs/latex/wx/classes.tex
+++ b/docs/latex/wx/classes.tex
@@ -39,9 +39,10 @@
 \input crtslock.tex
 \input cursor.tex
 \input database.tex
+\input dataform.tex
 \input dataobj.tex
-%\input dobjcomp.tex
-%\input dobjsmpl.tex
+\input dobjcomp.tex
+\input dobjsmpl.tex
 \input datstrm.tex
 \input date.tex
 \input dc.tex
diff --git a/docs/latex/wx/dataform.tex b/docs/latex/wx/dataform.tex
new file mode 100644
index 0000000000..9256dcefe0
--- /dev/null
+++ b/docs/latex/wx/dataform.tex
@@ -0,0 +1,115 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        dataform.tex
+%% Purpose:     wxDataFormat documentation
+%% Author:      Vadim Zeitlin
+%% Modified by:
+%% Created:     03.11.99
+%% RCS-ID:      $Id$
+%% Copyright:   (c) Vadim Zeitlin
+%% Licence:     wxWindows licence
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxDataFormat}}\label{wxdataformat}
+
+A wxDataFormat is an encapsulation of a platform-specific format handle which
+is used by the system for the clipboard and drag and drop operations. The
+applications are usually only interested in, for example, pasting data from the
+clipboard only if the data is in a format the program understands and a data
+format is something which uniquely identifies this format.
+
+On the system level, a data format is usually just a number ({\tt CLIPFORMAT}
+under Windows or {\tt Atom} under X11, for example) and the standard formats
+are, indeed, just numbers which can be implicitly converted to wxDataFormat.
+The standard formats are:
+
+\begin{twocollist}\itemsep=1cm
+\twocolitem{wxDF\_INVALID}{An invalid format - used as default argument for
+functions taking a wxDataFormat argument sometimes}
+\twocolitem{wxDF\_TEXT}{Text format (wxString)}
+\twocolitem{wxDF\_BITMAP}{A bitmap (wxBitmap)}
+\twocolitem{wxDF\_METAFILE}{A metafile (wxMetafile, Windows only)}
+\twocolitem{wxDF\_FILENAME}{A list of filenames}
+\end{twocollist}
+
+As mentioned above, these standard formats may be passed to any function taking
+wxDataFormat argument because wxDataFormat has an implicit conversion from
+them (or, to be precise from the type {\tt wxDataFormat::NativeFormat} which is
+the type used by the underlying platform for data formats).
+
+Aside the standard formats, the application may also use custom formats which
+are identified by their names (strings) and not numeric identifiers. Although
+internally custom format must be created (or {\it registered}) first, you
+shouldn't care about it because it is done automatically the first time the
+wxDataFormat object corresponding to a given format name is created. The only
+implication of this is that you should avoid having global wxDataFormat objects
+with non-default constructor because their constructors are executed before the
+program has time to perform all necessary initialisations and so an attempt to
+do clipboard format registration at this time will usually lead to a crash!
+
+\wxheading{Virtual functions to override}
+
+None, this class doesn't have any.
+
+\wxheading{Derived from}
+
+None
+
+\wxheading{See also}
+
+\helpref{Clipboard and drag and drop overview}{wxdndoverview}, 
+\helpref{DnD sample}{samplednd}, 
+\helpref{wxDataObject}{wxdataobject}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxDataFormat::wxDataFormat}\label{wxdataformatwxdataformatdef}
+
+\func{}{wxDataFormat}{\param{NativeFormat}{ format = wxDF\_INVALID}}
+
+Constructs a data format object for one of the standard data formats or an
+empty data object (use \helpref{SetType}{wxdataformatsettype} or 
+\helpref{SetId}{wxdataformatsetid} later in this case)
+
+\membersection{wxDataFormat::wxDataFormat}\label{wxdataformatwxdataformat}
+
+\func{}{wxDataFormat}{\param{const wxChar }{*format}}
+
+Constructs a data format object for a custom format identified by its name 
+{\it format}.
+
+\membersection{wxDataFormat::operator $==$}\label{wxdataformatoperatoreq}
+
+\constfunc{bool}{operator $==$}{\param{const wxDataFormat\&}{ format}}
+
+Returns TRUE if the formats are equal.
+
+\membersection{wxDataFormat::operator $!=$}\label{wxdataformatoperatorneq}
+
+\constfunc{bool}{operator $!=$}{\param{const wxDataFormat\&}{ format}}
+
+Returns TRUE if the formats are different.
+
+\membersection{wxDataFormat::GetId}\label{wxdataformatgetid}
+
+\constfunc{wxString}{GetId}{\void}
+
+Returns the name of a custom format (this function will fail for a standard
+format).
+
+\membersection{wxDataFormat::GetType}\label{wxdataformatgettype}
+
+\constfunc{NativeFormat}{GetType}{\void}
+
+Returns the platform-specific number identifying the format.
+
+\membersection{wxDataFormat::SetId}\label{wxdataformatsetid}
+
+\func{void}{SetId}{\param{const wxChar }{*format}}
+
+Sets the format to be the custom format identified by the given name.
+
+\membersection{wxDataFormat::SetType}\label{wxdataformatsettype}
+
+\func{void}{SetType}{\param{NativeFormat}{ format}}
+
+Sets the format to the given value which should be one of wxDF\_XXX constants.
diff --git a/docs/latex/wx/dataobj.tex b/docs/latex/wx/dataobj.tex
index 2538703aaf..da19100055 100644
--- a/docs/latex/wx/dataobj.tex
+++ b/docs/latex/wx/dataobj.tex
@@ -53,18 +53,18 @@ because it achievs this by simply holding several wxDataObjectSimple objects.
 So, you have several solutions when you need a wxDataObject class (and you need
 one as soon as you want to transfer data via the clipboard or drag and drop):
 
-\begin{twocollist}\itemsep=0pt
-\twocolitem{0. Use one of built-in classes}{You may use wxTextDataObject,
+\begin{twocollist}\itemsep=1cm
+\twocolitem{{\bf 0. Use one of built-in classes}}{You may use wxTextDataObject,
 wxBitmapDataObject or wxFileDataObject in the simplest cases when you only need
 to support one format and your data is either text, bitmap or list of files.}
-\twocolitem{1. Derive your class from wxDataObjectSimple}{This is the simplest
+\twocolitem{{\bf 1. Use wxDataObjectSimple}}{Deriving from wxDataObjectSimple is the simplest
 solution for custom data - you will only support one format and so probably
 won't be able to communicate with other programs, but data transfer will work
 in your program (or between different copies of it).}
-\twocolitem{2. Use wxDataObjectComposite}{This is a simple but powerful
+\twocolitem{{\bf 2. Use wxDataObjectComposite}}{This is a simple but powerful
 solution which allows you to support any number of formats (either
 standard or custom if you combine it with the previous solution).}
-\twocolitem{3. Derive from wxDataObject directly}{This is the solution for
+\twocolitem{{\bf 3. Use wxDataObject directly}}{This is the solution for
 maximal flexibility and efficiency, but it also is the most difficult to
 implement.}
 \end{twocollist}
diff --git a/docs/latex/wx/tclipbrd.tex b/docs/latex/wx/tclipbrd.tex
index dc78c445d5..fc91daa9c9 100644
--- a/docs/latex/wx/tclipbrd.tex
+++ b/docs/latex/wx/tclipbrd.tex
@@ -9,7 +9,7 @@
 %% Licence:     wxWindows licence
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-\section{Clipboard and drag and drop overview}\label{wxclipboardonfigoverview}
+\section{Clipboard and drag and drop overview}\label{wxdndoverview}\label{wxclipboardonfigoverview}
 
 Classes: \helpref{wxDataObject}{wxdataobject},
  \helpref{wxClipboard}{wxclipboard},
diff --git a/docs/latex/wx/topics.tex b/docs/latex/wx/topics.tex
index 6f0f483b54..7daf692886 100644
--- a/docs/latex/wx/topics.tex
+++ b/docs/latex/wx/topics.tex
@@ -4,7 +4,7 @@
 
 This chapter contains a selection of topic overviews.
 
-%\input tsamples.tex
+\input tsamples.tex
 \input tapp.tex
 \input tstring.tex
 \input tcontain.tex
diff --git a/docs/latex/wx/tsamples.tex b/docs/latex/wx/tsamples.tex
index 065961d5cb..619ef54183 100644
--- a/docs/latex/wx/tsamples.tex
+++ b/docs/latex/wx/tsamples.tex
@@ -19,7 +19,7 @@ make it easier to find the relevant one if a simple grep through all sources
 didn't help. They also provide some notes about using the samples and what
 features of wxWindows are they supposed to test.
 
-\subsection{DnD sample}{samplednd}
+\subsection{DnD sample}\label{samplednd}
 
 This sample shows both clipboard and drag and drop in action. It is quite non
 trivial and may be safely used as a basis for implementing the clipboard and
diff --git a/docs/latex/wx/wx.hpj b/docs/latex/wx/wx.hpj
index 5bf567ae88..b8f8205dae 100644
--- a/docs/latex/wx/wx.hpj
+++ b/docs/latex/wx/wx.hpj
@@ -1,14 +1,14 @@
 [OPTIONS]
-BMROOT=d:\wx2\wxWind~1\docs/latex/wx ; Assume that bitmaps are where the source is
+BMROOT=L:\wxWindows\docs\latex\wx ; Assume that bitmaps are where the source is
 TITLE=wxWindows Manual
 CONTENTS=Contents
 COMPRESS=HIGH
 
 [FILES]
-wx.rtf
+Wx.rtf
 
 [CONFIG]
-CreateButton("Up", "&Up", "JumpId(`wx.hlp', `Contents')")
+CreateButton("Up", "&Up", "JumpId(`Wx.hlp', `Contents')")
 BrowseButtons()
 
 [MAP]
-- 
2.50.0

