From e3ba9f8828b5cb1c61011e386a5e44fd16d2d8a5 Mon Sep 17 00:00:00 2001
From: Robert Roebling <robert@roebling.de>
Date: Fri, 31 May 2002 07:41:46 +0000
Subject: [PATCH]   Documented wxClienData and friends.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@15710 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
---
 docs/latex/wx/body.tex      |   2 +-
 docs/latex/wx/classes.tex   |   2 +
 docs/latex/wx/clientdat.tex | 113 ++++++++++++++++++++++++++++++++++++
 docs/latex/wx/evthand.tex   |  26 ++++++++-
 docs/latex/wx/strcldat.tex  |  39 +++++++++++++
 docs/latex/wx/treedata.tex  |   2 +-
 6 files changed, 181 insertions(+), 3 deletions(-)
 create mode 100644 docs/latex/wx/clientdat.tex
 create mode 100644 docs/latex/wx/strcldat.tex

diff --git a/docs/latex/wx/body.tex b/docs/latex/wx/body.tex
index 5002bcdeca..538757afb5 100644
--- a/docs/latex/wx/body.tex
+++ b/docs/latex/wx/body.tex
@@ -153,7 +153,7 @@ Metrowerks CodeWarrior.
 
 \begin{enumerate}\itemsep=0pt
 \item Almost any C++ compiler, including GNU C++ (EGCS 1.1.1 or above).
-\item Almost any Unix workstation, and one of: GTK+ 1.2, Motif 1.2 or higher, Lesstif.
+\item Almost any Unix workstation, and one of: GTK+ 1.2, GTK+ 2.0, Motif 1.2 or higher, Lesstif.
 \item At least 60 MB of disk space.
 \end{enumerate}
 
diff --git a/docs/latex/wx/classes.tex b/docs/latex/wx/classes.tex
index 4645496112..161186d19f 100644
--- a/docs/latex/wx/classes.tex
+++ b/docs/latex/wx/classes.tex
@@ -30,6 +30,7 @@
 \input choice.tex
 \input clasinfo.tex
 \input clientdc.tex
+\input clientdat.tex
 \input clipbrd.tex
 \input closeevt.tex
 \input cmdlpars.tex
@@ -273,6 +274,7 @@
 \input stream.tex
 \input strtotxt.tex
 \input wxstring.tex
+\input strcldat.tex
 \input strlist.tex
 \input tokenizr.tex
 \input sysclevt.tex
diff --git a/docs/latex/wx/clientdat.tex b/docs/latex/wx/clientdat.tex
new file mode 100644
index 0000000000..74bdbeeefd
--- /dev/null
+++ b/docs/latex/wx/clientdat.tex
@@ -0,0 +1,113 @@
+\section{\class{wxClientData}}\label{wxclientdata}
+
+All classes deriving from \helpref{wxEvtHandler}{wxevthandler}
+(such as all controls and \helpref{wxApp}{wxapp})
+can hold arbitrary data which is here referred to as "client data".
+This is useful e.g. for scripting languages which need to handle
+shadow objects for most of wxWindows' classes and which store
+a handle to such a shadow class as client data in that class.
+This data can either be of type void - in which case the data
+{\it container} does not take care of freeing the data again
+or it is of type wxClientData or its derivates. In that case the
+container (e.g. a control) will free the memory itself later.
+Note that you {\it must not} assign both void data and data
+derived from the wxClientData class to a container.
+
+Some controls can hold various items and these controls can
+additionally hold client data for each item. This is the case for
+\helpref{wxChoice}{wxchoice}, \helpref{wxComboBox}{wxcombobox}
+and \helpref{wxListBox}{wxlistbox}. \helpref{wxTreeCtrl}{wxtreectrl}
+has a specialized class \helpref{wxTreeItemData}{wxtreeitemdata}
+for each item in the tree.
+
+If you want to add client data to your own classes, you may
+use the mix-in class \helpref{wxClientDataContainer}{wxclientdatacontainer}.
+
+\wxheading{Include files}
+
+<wx/clntdata.h>
+
+\wxheading{See also}
+
+\helpref{wxEvtHandler}{wxevthandler}, \helpref{wxTreeItemData}{wxtreeitemdata},
+\helpref{wxStringClientData}{wxstringclientdata}, \helpref{wxClientDataContainer}{wxclientdatacontainer}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+
+\membersection{wxClientData::wxClientData}\label{wxclientdatawxclientdata}
+
+\func{}{wxClientData}{\void}
+
+Constructor.
+
+\membersection{wxClientData::\destruct{wxClientData}}\label{wxclientdatadtor}
+
+\func{}{\destruct{wxClientData}}{\void}
+
+Virtual destructor.
+
+\section{\class{wxClientDataContainer}}\label{wxclientdatacontainer}
+
+This class is a mixin that provides storage and management of "client
+data." This data can either be of type void - in which case the data
+{\it container} does not take care of freeing the data again
+or it is of type wxClientData or its derivates. In that case the
+container will free the memory itself later.
+Note that you {\it must not} assign both void data and data
+derived from the wxClientData class to a container.
+
+NOTE: This functionality is currently duplicated in wxEvtHandler in
+order to avoid having more than one vtable in that class heirachy.
+
+\wxheading{See also}
+
+\helpref{wxEvtHandler}{wxevthandler}, \helpref{wxClientData}{wxclientdata}
+
+\wxheading{Derived from}
+
+No base class
+
+\wxheading{Include files}
+
+<clntdata.h>
+
+\wxheading{Data structures}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+
+\membersection{wxClientDataContainer::wxClientDataContainer}\label{wxclientdatacontainerwxclientdatacontainer}
+
+\func{}{wxClientDataContainer}{\void}
+
+
+\membersection{wxClientDataContainer::\destruct{wxClientDataContainer}}\label{wxclientdatacontainerdtor}
+
+\func{}{\destruct{wxClientDataContainer}}{\void}
+
+
+\membersection{wxClientDataContainer::GetClientData}\label{wxclientdatacontainergetclientdata}
+
+\constfunc{void*}{GetClientData}{\void}
+
+Get the untyped client data.
+
+\membersection{wxClientDataContainer::GetClientObject}\label{wxclientdatacontainergetclientobject}
+
+\constfunc{wxClientData*}{GetClientObject}{\void}
+
+Get a pointer to the client data object.
+
+\membersection{wxClientDataContainer::SetClientData}\label{wxclientdatacontainersetclientdata}
+
+\func{void}{SetClientData}{\param{void* }{data}}
+
+Set the untyped client data.
+
+\membersection{wxClientDataContainer::SetClientObject}\label{wxclientdatacontainersetclientobject}
+
+\func{void}{SetClientObject}{\param{wxClientData* }{data}}
+
+Set the client data object. Any previous object will be deleted.
+
diff --git a/docs/latex/wx/evthand.tex b/docs/latex/wx/evthand.tex
index 3b543f1a72..45ae21f81b 100644
--- a/docs/latex/wx/evthand.tex
+++ b/docs/latex/wx/evthand.tex
@@ -142,6 +142,17 @@ should be made available by deriving a new class with new data members.
 
 \helpref{wxEvtHandler::SetClientData}{wxevthandlersetclientdata}
 
+\membersection{wxEvtHandler::GetClientObject}\label{wxevthandlergetclientobject}
+
+\constfunc{wxClientData*}{GetClientObject}{\void}
+
+Get a pointer to the user-supplied client data object.
+
+\wxheading{See also}
+
+\helpref{wxEvtHandler::SetClientObject}{wxevthandlersetclientobject},
+\helpref{wxClientData}{wxclientdata}
+
 \membersection{wxEvtHandler::GetEvtHandlerEnabled}\label{wxevthandlergetevthandlerenabled}
 
 \func{bool}{GetEvtHandlerEnabled}{\void}
@@ -282,12 +293,25 @@ Sets user-supplied client data.
 
 Normally, any extra data the programmer wishes to associate with 
 the object should be made available by deriving a new class
-with new data members.
+with new data members. You must not call this method and
+\helpref{SetClientObject}{wxevthandlersetclientobject} on the
+same class - only one of them.
 
 \wxheading{See also}
 
 \helpref{wxEvtHandler::GetClientData}{wxevthandlergetclientdata}
 
+\membersection{wxEvtHandler::SetClientObject}\label{wxevthandlersetclientobject}
+
+\func{void}{SetClientObject}{\param{wxClientData* }{data}}
+
+Set the client data object. Any previous object will be deleted.
+
+\wxheading{See also}
+
+\helpref{wxEvtHandler::GetClientObject}{wxevthandlergetclientobject},
+\helpref{wxClientData}{wxclientdata}
+
 \membersection{wxEvtHandler::SetEvtHandlerEnabled}\label{wxevthandlersetevthandlerenabled}
 
 \func{void}{SetEvtHandlerEnabled}{\param{bool }{enabled}}
diff --git a/docs/latex/wx/strcldat.tex b/docs/latex/wx/strcldat.tex
new file mode 100644
index 0000000000..cd1a74febc
--- /dev/null
+++ b/docs/latex/wx/strcldat.tex
@@ -0,0 +1,39 @@
+\section{\class{wxStringClientData}}\label{wxstringclientdata}
+
+Predefined client data class for holding a string.
+
+\wxheading{Derived from}
+
+\helpref{wxClientData}{wxclientdata}
+
+\wxheading{Include files}
+
+<clntdata.h>
+
+\wxheading{Data structures}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+
+\membersection{wxStringClientData::wxStringClientData}\label{wxstringclientdatawxstringclientdata}
+
+\func{}{wxStringClientData}{\void}
+
+Empty constructor.
+
+\func{}{wxStringClientData}{\param{const wxString\& }{data}}
+
+Create client data with string.
+
+\membersection{wxStringClientData::GetData}\label{wxstringclientdatagetdata}
+
+\constfunc{const wxString\&}{GetData}{\void}
+
+Get string client data.
+
+\membersection{wxStringClientData::SetData}\label{wxstringclientdatasetdata}
+
+\func{void}{SetData}{\param{const wxString\& }{data}}
+
+Set string client data.
+
diff --git a/docs/latex/wx/treedata.tex b/docs/latex/wx/treedata.tex
index a2dfc6e9ca..0de5d6da8b 100644
--- a/docs/latex/wx/treedata.tex
+++ b/docs/latex/wx/treedata.tex
@@ -15,7 +15,7 @@ using {\tt new}.
 
 \wxheading{Derived from}
 
-wxClientData
+\helpref{wxClientData}{wxclientdata}
 
 \wxheading{Include files}
 
-- 
2.50.0

