cross-reference types in the generated docs (patch 1038083)

[wxWidgets.git] / docs / latex / wx / custdobj.tex

diff --git a/docs/latex/wx/custdobj.tex b/docs/latex/wx/custdobj.tex
index 52f780639bcbba557fd0befc9d5a4d95dc68437a..2a7b7391c0066fea5bd627f9aa8b658de384dab8 100644 (file)
--- a/docs/latex/wx/custdobj.tex
+++ b/docs/latex/wx/custdobj.tex
@@ -7,9 +7,28 @@ ones). The only restriction is that it is supposed that this data can be
 copied bitwise (i.e. with {\tt memcpy()}), so it would be a bad idea to make
 it contain a C++ object (though C struct is fine).
 
+By default, wxCustomDataObject stores the data inside in a buffer. To put the
+data into the buffer you may use either 
+\helpref{SetData}{wxcustomdataobjectsetdata} or 
+\helpref{TakeData}{wxcustomdataobjecttakedata} depending on whether you want
+the object to make a copy of data or not.
+
+If you already store the data in another place, it may be more convenient and
+efficient to provide the data on-demand which is possible too if you override
+the virtual functions mentioned below.
+
+\wxheading{Virtual functions to override}
+
+This class may be used as is, but if you don't want store the data inside the
+object but provide it on demand instead, you should override 
+\helpref{GetSize}{wxcustomdataobjectgetsize}, 
+\helpref{GetData}{wxcustomdataobjectgetdata} and 
+\helpref{SetData}{wxcustomdataobjectsetdata} (or may be only the first two or
+only the last one if you only allow reading/writing the data)
+
 \wxheading{Derived from}
 
-\helpref{wxDataObjectSimple}{wxdataobjectsimple}
+\helpref{wxDataObjectSimple}{wxdataobjectsimple}\\
 \helpref{wxDataObject}{wxdataobject}
 
 \wxheading{Include files}
@@ -41,22 +60,51 @@ functions from constructors or destructors), so if you override {\tt Free()}, yo
 should override the destructor in your class as well (which would probably
 just call the derived class' version of {\tt Free()}).
 
+\membersection{wxCustomDataObject::Alloc}\label{wxcustomdataobjectalloc}
 
-\membersection{wxCustomDataObject::SetData}\label{wxcustomdataobjectsetdata}
+\func{virtual void *}{Alloc}{\param{size\_t }{size}}
 
-\func{virtual void}{SetData}{\param{const char }{*data}, \param{size\_t }{size}}
+This function is called to allocate {\it size} bytes of memory from SetData().
+The default version just uses the operator new.
 
-Set the data. The data object will make an internal copy.
+\membersection{wxCustomDataObject::Free}\label{wxcustomdataobjectfree}
+
+\func{virtual void}{Free}{\void}
+
+This function is called when the data is freed, you may override it to anything
+you want (or may be nothing at all). The default version calls operator
+delete$[]$ on the data.
 
 \membersection{wxCustomDataObject::GetSize}\label{wxcustomdataobjectgetsize}
 
-\constfunc{virtual size\_t}{GetDataSize}{\void}
+\constfunc{virtual size\_t}{GetSize}{\void}
 
-Returns the data size.
+Returns the data size in bytes.
 
 \membersection{wxCustomDataObject::GetData}\label{wxcustomdataobjectgetdata}
 
-\func{virtual char*}{GetData}{\void}
+\constfunc{virtual void *}{GetData}{\void}
 
 Returns a pointer to the data.
 
+\membersection{wxCustomDataObject::SetData}\label{wxcustomdataobjectsetdata}
+
+\func{virtual void}{SetData}{
+ \param{size\_t }{size}, \param{const void }{*data}}
+
+Set the data. The data object will make an internal copy.
+
+\pythonnote{This method expects a string in wxPython.  You can pass
+nearly any object by pickling it first.}
+
+\membersection{wxCustomDataObject::TakeData}\label{wxcustomdataobjecttakedata}
+
+\func{virtual void}{TakeData}{
+ \param{size\_t }{size}, \param{const void }{*data}}
+
+Like \helpref{SetData}{wxcustomdataobjectsetdata}, but doesn't copy the data -
+instead the object takes ownership of the pointer.
+
+\pythonnote{This method expects a string in wxPython.  You can pass
+nearly any object by pickling it first.}
+