define _HPUX_SOURCE under HP-UX, otherwise many things are not defined in standard...

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

diff --git a/docs/latex/wx/txtdatob.tex b/docs/latex/wx/txtdatob.tex
index 937489fb3a2064e7fc30609a60174eefd7b4dc7e..0e45a97d6699b8875532cdf9a53c89277e569252 100644 (file)
--- a/docs/latex/wx/txtdatob.tex
+++ b/docs/latex/wx/txtdatob.tex
@@ -1,42 +1,81 @@
 \section{\class{wxTextDataObject}}\label{wxtextdataobject}
 
- wxTextDataObject is a specialization of wxDataObject for text data.
+wxTextDataObject is a specialization of wxDataObject for text data. It can be
+used without change to paste data into the \helpref{wxClipboard}{wxclipboard} 
+or a \helpref{wxDropSource}{wxdropsource}. A user may wish to derive a new
+class from this class for providing text on-demand in order to minimize memory
+consumption when offering data in several formats, such as plain text and RTF
+because by default the text is stored in a string in this class, but it might
+as well be generated when requested. For this, 
+\helpref{GetTextLength}{wxtextdataobjectgettextlength} and 
+\helpref{GetText}{wxtextdataobjectgettext} will have to be overridden.
+
+Note that if you already have the text inside a string, you will not achieve
+any efficiency gain by overriding these functions because copying wxStrings is
+already a very efficient operation (data is not actually copied because
+wxStrings are reference counted).
+
+\pythonnote{If you wish to create a derived wxTextDataObject class in
+wxPython you should derive the class from wxPyTextDataObject
+in order to get Python-aware capabilities for the various virtual
+methods.}
+
+\wxheading{Virtual functions to override}
+
+This class may be used as is, but all of the data transfer functions may be
+overridden to increase efficiency.
 
 \wxheading{Derived from}
 
+\helpref{wxDataObjectSimple}{wxdataobjectsimple}\\
 \helpref{wxDataObject}{wxdataobject}
 
+\wxheading{Include files}
+
+<wx/dataobj.h>
+
 \wxheading{See also}
 
-\helpref{wxDataObject}{wxdataobject}
+\helpref{Clipboard and drag and drop overview}{wxdndoverview}, 
+\helpref{wxDataObject}{wxdataobject}, 
+\helpref{wxDataObjectSimple}{wxdataobjectsimple}, 
+\helpref{wxFileDataObject}{wxfiledataobject}, 
+\helpref{wxBitmapDataObject}{wxbitmapdataobject}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 \membersection{wxTextDataObject::wxTextDataObject}\label{wxtextdataobjectwxtextdataobject}
 
-\func{}{wxTextDataObject}{\void}
+\func{}{wxTextDataObject}{\param{const wxString\& }{text = wxEmptyString}}
 
-Default constructor.
+Constructor, may be used to initialise the text (otherwise 
+\helpref{SetText}{wxtextdataobjectsettext} should be used later).
 
-\func{}{wxTextDataObject}{\param{const wxString\& }{strText}}
+\membersection{wxTextDataObject::GetTextLength}\label{wxtextdataobjectgettextlength}
 
-Constructor, passing text.
+\constfunc{virtual size\_t}{GetTextLength}{\void}
 
-\membersection{wxTextDataObject::GetFormat}\label{wxtextdataobjectgetformat}
+Returns the data size. By default, returns the size of the text data
+set in the constructor or using \helpref{SetText}{wxtextdataobjectsettext}.
+This can be overridden to provide text size data on-demand. It is recommended
+to return the text length plus 1 for a trailing zero, but this is not
+strictly required.
 
-\constfunc{virtual wxDataFormat}{GetFormat}{\void}
+\membersection{wxTextDataObject::GetText}\label{wxtextdataobjectgettext}
+
+\constfunc{virtual wxString}{GetText}{\void}
 
-Returns wxDF\_TEXT.
+Returns the text associated with the data object. You may wish to override
+this method when offering data on-demand, but this is not required by
+wxWidgets' internals. Use this method to get data in text form from
+the \helpref{wxClipboard}{wxclipboard}.
 
 \membersection{wxTextDataObject::SetText}\label{wxtextdataobjectsettext}
 
 \func{virtual void}{SetText}{\param{const wxString\& }{strText}}
 
-Sets the text associated with the data object.
-
-\membersection{wxTextDataObject::GetText}\label{wxtextdataobjectgettext}
-
-\constfunc{virtual wxString}{GetText}{\void}
-
-Returns the text associated with the data object.
+Sets the text associated with the data object. This method is called
+when the data object receives the data and, by default, copies the text into
+the member variable. If you want to process the text on the fly you may wish to
+override this function.