Documented new constructor and overloaded Create methods.

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

diff --git a/docs/latex/wx/txtdatob.tex b/docs/latex/wx/txtdatob.tex
index a30b181533837236c316eec44777525c90be6eb7..2e39ee3cbdb867b23d8f464bcfb28b1a10c2a8e4 100644 (file)
--- a/docs/latex/wx/txtdatob.tex
+++ b/docs/latex/wx/txtdatob.tex
@@ -1,39 +1,59 @@
 \section{\class{wxTextDataObject}}\label{wxtextdataobject}
 
 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.
-
-In order to offer text data on-demand \helpref{GetSize}{wxtextdataobjectgetsize} 
-and \helpref{WriteData}{wxtextdataobjectwritedata} will have to be overridden.
+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. Call \helpref{SetText}{wxtextdataobjectsettext} later
-or override \helpref{WriteData}{wxtextdataobjectwritedata} and 
-\helpref{GetSize}{wxtextdataobjectgetsize} for providing data on-demand.
+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.
-
-\membersection{wxTextDataObject::GetSize}\label{wxtextdataobjectgetsize}
-
-\constfunc{virtual size\_t}{GetSize}{\void}
+\constfunc{virtual size\_t}{GetTextLength}{\void}
 
 Returns the data size. By default, returns the size of the text data
 set in the constructor or using \helpref{SetText}{wxtextdataobjectsettext}.
@@ -55,25 +75,7 @@ the \helpref{wxClipboard}{wxclipboard}.
 \func{virtual void}{SetText}{\param{const wxString\& }{strText}}
 
 Sets the text associated with the data object. This method is called
-internally when retrieving data from the \helpref{wxClipboard}{wxclipboard}
-and may be used to paste data to the clipboard directly (instead of
-on-demand).
-
-\membersection{wxTextDataObject::WriteData}\label{wxtextdataobjectwritedata}
-
-\constfunc{virtual void}{WriteData}{\param{void}{*dest} }
-
-Write the data owned by this class to {\it dest}. By default, this
-calls \helpref{WriteString}{wxtextdataobjectwritestring} with the string
-set in the constructor or using \helpref{SetText}{wxtextdataobjectsettext}.
-This can be overridden to provide text data on-demand; in this case 
-\helpref{WriteString}{wxtextdataobjectwritestring} must be called from
-within the overriding WriteData() method.
-
-\membersection{wxTextDataObject::WriteString}\label{wxtextdataobjectwritestring}
-
-\constfunc{void}{WriteString}{\param{const wxString\& }{str}\param{void}{*dest} }
-
-Writes the the string {\it str} to {\it dest}. This method must be called
-from \helpref{WriteData}{wxtextdataobjectwritedata}.
+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.