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

@@ -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}

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

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.

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}

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},

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

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

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]