no changes, just come cleanup and more comments

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

\section{\class{wxCustomDataObject}}\label{wxcustomdataobject}

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{wxDataObject}{wxdataobject}

\wxheading{Include files}

<wx/dataobj.h>

\wxheading{Library}

\helpref{wxCore}{librarieslist}

\wxheading{See also}

\helpref{wxDataObject}{wxdataobject}

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxCustomDataObject::wxCustomDataObject}\label{wxcustomdataobjectwxcustomdataobject}

\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, 
\helpref{SetFormat}{wxdataobjectsimplesetformat} should be used.

\membersection{wxCustomDataObject::\destruct{wxCustomDataObject}}\label{wxcustomdataobjectdtor}

\func{}{\destruct{wxCustomDataObject}}{\void}

The destructor will free the data hold by the object. Notice that although it
calls a virtual \helpref{Free()}{wxcustomdataobjectfree} function, the base
class version will always be called (C++ doesn't allow calling virtual
functions from constructors or destructors), so if you override {\tt Free()}, you
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}

\func{virtual void *}{Alloc}{\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.

\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}{GetSize}{\void}

Returns the data size in bytes.

\membersection{wxCustomDataObject::GetData}\label{wxcustomdataobjectgetdata}

\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.}