X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/864753e906653e6bbec3d283abc69a8a89612b46..7eb4e9cc0f3590fffda78bf02c47b25c41583eba:/docs/latex/wx/custdobj.tex

diff --git a/docs/latex/wx/custdobj.tex b/docs/latex/wx/custdobj.tex
index 52f780639b..2f2a71043e 100644
--- a/docs/latex/wx/custdobj.tex
+++ b/docs/latex/wx/custdobj.tex
@@ -1,15 +1,34 @@
 \section{\class{wxCustomDataObject}}\label{wxcustomdataobject}
 
-wxCustomDataObject is a specialization of 
+wxCustomDataObject is a specialization of
 \helpref{wxDataObjectSimple}{wxdataobjectsimple} for some
 application-specific data in arbitrary (either custom or one of the standard
 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}
@@ -27,7 +46,7 @@ it contain a C++ object (though C struct is fine).
 \func{}{wxCustomDataObject}{\param{const wxDataFormat\& }{format = wxFormatInvalid}}
 
 The constructor accepts a {\it format} argument which specifies the (single)
-format supported by this object. If it isn't set here, 
+format supported by this object. If it isn't set here,
 \helpref{SetFormat}{wxdataobjectsimplesetformat} should be used.
 
 \membersection{wxCustomDataObject::\destruct{wxCustomDataObject}}\label{wxcustomdataobjectdtor}
@@ -41,22 +60,48 @@ 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}
+
+\pythonnote{This method expects a string in wxPython.  You can pass
+nearly any object by pickling it first.}
+
+\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.
+
+\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.
+