X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/a1665b22b07c572a240f9d83783044e3e4f9cb0e..a826c31586bc245a584c449c817bca3877e7e16c:/docs/latex/wx/text.tex

diff --git a/docs/latex/wx/text.tex b/docs/latex/wx/text.tex
index d2e831e459..09e9b045fa 100644
--- a/docs/latex/wx/text.tex
+++ b/docs/latex/wx/text.tex
@@ -30,15 +30,25 @@ you can still use Ctrl-Enter to pass to the next control from the keyboard.}
 \twocolitem{\windowstyle{wxTE\_MULTILINE}}{The text control allows multiple lines.}
 \twocolitem{\windowstyle{wxTE\_PASSWORD}}{The text will be echoed as asterisks.}
 \twocolitem{\windowstyle{wxTE\_READONLY}}{The text will not be user-editable.}
-\twocolitem{\windowstyle{wxHSCROLL}}{A horizontal scrollbar will be created.}
+\twocolitem{\windowstyle{wxTE\_RICH}}{Use rich text control under Win32, this
+allows to have more than 64Kb of text in the control even under Win9x. This
+style is ignored under other platforms.}
+\twocolitem{\windowstyle{wxTE\_AUTO\_URL}}{Highlight the URLs and generate the
+wxTextUrlEvents when mouse events occur over them. This style is supported
+under Win32 only and requires wxTE\_RICH.}
+\twocolitem{\windowstyle{wxTE\_NOHIDESEL}}{By default, the Windows text control
+doesn't show the selection when it doesn't have focus - use this style to force
+it to always show it. It doesn't do anything under other platforms.}
+\twocolitem{\windowstyle{wxHSCROLL}}{A horizontal scrollbar will be created. No effect under GTK+.}
 \end{twocollist}
 
 See also \helpref{window styles overview}{windowstyles} and
 \helpref{wxTextCtrl::wxTextCtrl}{wxtextctrlconstr}.
 
-\wxheading{Remarks}
+\wxheading{wxTextCtrl and C++ streams}
 
-This class multiply-inherits from {\bf streambuf} where compilers allow, allowing code such as the following:
+This class multiply-inherits from {\bf streambuf} where compilers allow,
+allowing code such as the following:
 
 {\small%
 \begin{verbatim}
@@ -51,9 +61,63 @@ This class multiply-inherits from {\bf streambuf} where compilers allow, allowin
 \end{verbatim}
 }%
 
-If your compiler does not support derivation from {\bf streambuf} and gives a compile error, define the symbol {\bf NO\_TEXT\_WINDOW\_STREAM} in the
+If your compiler does not support derivation from {\bf streambuf} and gives a
+compile error, define the symbol {\bf NO\_TEXT\_WINDOW\_STREAM} in the
 wxTextCtrl header file.
 
+Note that independently of this setting you can always use wxTextCtrl itself
+in a stream-like manner:
+
+{\small%
+\begin{verbatim}
+  wxTextCtrl *control = new wxTextCtrl(...);
+
+  *control << 123.456 << " some text\n";
+\end{verbatim}
+}%
+
+always works. However the possibility to create an ostream associated with
+wxTextCtrl may be useful if you need to redirect the output of a function
+taking an ostream as parameter to a text control.
+
+Another commonly requested need is to redirect {\bf std::cout} to the text
+control. This could be done in the following way:
+
+{\small%
+\begin{verbatim}
+  #include <iostream>
+
+  wxTextCtrl *control = new wxTextCtrl(...);
+
+  std::streambuf *sbOld = std::cout.rdbuf();
+  std::cout.rdbuf(*control);
+
+  // use cout as usual, the output appears in the text control
+  ...
+
+  std::cout.rdbuf(sbOld);
+\end{verbatim}
+}%
+
+But wxWindows provides a convenient class to make it even simpler so instead
+you may just do
+
+{\small%
+\begin{verbatim}
+  #include <iostream>
+
+  wxTextCtrl *control = new wxTextCtrl(...);
+
+  wxStreamToTextRedirector redirect(control);
+
+  // all output to cout goes into the text control until the exit from current
+  // scope
+\end{verbatim}
+}%
+
+See \helpref{wxStreamToTextRedirector}{wxstreamtotextredirector} for more
+details.
+
 \wxheading{Event handling}
 
 The following commands are processed by default event handlers in wxTextCtrl: wxID\_CUT, wxID\_COPY,
@@ -71,12 +135,13 @@ when the text controls contents changes - whether this is due to user input or
 comes from the program itself (for example, if SetValue() is called)}
 \twocolitem{{\bf EVT\_TEXT\_ENTER(id, func)}}{Respond to a wxEVT\_COMMAND\_TEXT\_ENTER event,
 generated when enter is pressed in a single-line text control.}
+\twocolitem{{\bf EVT\_TEXT\_URL(id, func)}}{A mouse event occured over an URL
+in the text control (Win32 only)}
+\twocolitem{{\bf EVT\_TEXT\_MAXLEN(id, func)}}{User tried to enter more text
+into the control than the limit set by
+\helpref{SetMaxLength}{wxtextctrlsetmaxlength}.}
 \end{twocollist}%
 
-%\wxheading{See also}
-%
-%\helpref{wxRichTextCtrl}{wxrichtextctrl}
-%
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 \membersection{wxTextCtrl::wxTextCtrl}\label{wxtextctrlconstr}
@@ -118,9 +183,10 @@ controls don't have a horizontal scrollbar, the text is automatically scrolled
 so that the \helpref{insertion point}{wxtextctrlgetinsertionpoint} is always
 visible.
 
-Under Windows, if the {\bf wxTE\_MULTILINE} style is used, the window is implemented
-as a Windows rich text control with unlimited capacity. Otherwise, normal edit control limits
-apply.
+% VZ: this is no longer true
+%Under Windows, if the {\bf wxTE\_MULTILINE} style is used, the window is implemented
+%as a Windows rich text control with unlimited capacity. Otherwise, normal edit control limits
+%apply.
 
 \wxheading{See also}
 
@@ -302,6 +368,13 @@ working with controls that contain large amounts of text.
 Gets the current selection span. If the returned values are equal, there was
 no selection.
 
+Please note that the indices returned may be used with the other wxTextctrl
+methods but don't necessarily represent the correct indices into the string
+returned by \helpref{GetValue()}{wxtextctrlgetvalue} for multiline controls
+under Windows (at least,) you should use
+\helpref{GetStringSelection()}{wxtextctrlgetstringselection} to get the selected
+text.
+
 \wxheading{Parameters}
 
 \docparam{from}{The returned first position.}
@@ -311,11 +384,23 @@ no selection.
 \pythonnote{The wxPython version of this method returns a tuple
 consisting of the from and to values.}
 
+\perlnote{In wxPerl this method takes no parameter and returns a
+2-element list {\tt ( from, to )}.}
+
+\membersection{wxTextCtrl::GetStringSelection}\label{wxtextctrlgetstringselection}
+
+\func{virtual wxString}{GetStringSelection}{\void}
+
+Gets the text currently selected in the control. If there is no selection, the
+returned string is empty.
+
 \membersection{wxTextCtrl::GetValue}\label{wxtextctrlgetvalue}
 
 \constfunc{wxString}{GetValue}{\void}
 
-Gets the contents of the control.
+Gets the contents of the control. Notice that for a multiline text control,
+the lines will be separated by (Unix-style) $\backslash$n characters, even under
+Windows where they are separated by a $\backslash$r$\backslash$n sequence in the native control.
 
 \membersection{wxTextCtrl::IsModified}\label{wxtextctrlismodified}
 
@@ -378,7 +463,7 @@ is to load the first dropped file into the control.
 
 \wxheading{Remarks}
 
-This is not yet implemented for the GTK.
+This is not implemented on non-Windows platforms.
 
 \wxheading{See also}
 
@@ -417,6 +502,9 @@ parameter).
 y values, so (x,y) = PositionToXY() is equivalent to the call described
 above.}
 
+\perlnote{In wxPerl this method only takes the {\tt pos} parameter, and
+returns a 2-element list {\tt ( x, y )}.}
+
 \membersection{wxTextCtrl::Redo}\label{wxtextctrlredo}
 
 \func{virtual void}{Redo}{\void}
@@ -470,8 +558,7 @@ TRUE if the operation was successful, FALSE otherwise.
 
 \func{virtual void}{SetEditable}{\param{const bool}{ editable}}
 
-Makes the text item editable or read-only, overriding the {\bf wxTE\_READONLY}
-flag.
+Makes the text item editable or read-only, overriding the {\bf wxTE\_READONLY} flag.
 
 \wxheading{Parameters}
 
@@ -494,6 +581,30 @@ Sets the insertion point at the given position.
 Sets the insertion point at the end of the text control. This is equivalent
 to \helpref{SetInsertionPoint}{wxtextctrlsetinsertionpoint}(\helpref{GetLastPosition}{wxtextctrlgetlastposition}()).
 
+\membersection{wxTextCtrl::SetMaxLength}\label{wxtextctrlsetmaxlength}
+
+\func{virtual void}{SetMaxLength}{\param{unsigned long }{len}}
+
+This function sets the maximum number of characters the user can enter into the
+control. In other words, it allows to limit the text value length to {\it len}
+not counting the terminating {\tt NUL} character.
+
+If {\it len} is $0$, the previously set max length limi, if any, is discarded
+and the user may enter as much text as the underlying native text control
+widget supports (typically at least 32Kb).
+
+If the user tries to enter more characters into the text control when it
+already is filled up to the maximal length, a
+{\tt wxEVT\_COMMAND\_TEXT\_MAXLEN} event is sent to notify the program about it
+(giving it the possibility to show an explanatory message, for example) and the
+extra input is discarded.
+
+Note that this function may only be used with single line text controls.
+
+\wxheading{Compatibility}
+
+Only implemented in wxMSW/wxGTK starting with wxWindows 2.3.2.
+
 \membersection{wxTextCtrl::SetSelection}\label{wxtextctrlsetselection}
 
 \func{virtual void}{SetSelection}{\param{long}{ from}, \param{long}{ to}}
@@ -510,7 +621,7 @@ Selects the text starting at the first position up to (but not including) the ch
 
 \func{virtual void}{SetValue}{\param{const wxString\& }{ value}}
 
-Sets the text value.
+Sets the text value and marks the control as not-modified.
 
 \wxheading{Parameters}