+%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxTextAttr %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxTextAttr}}\label{wxtextattr}
+
+wxTextAttr represents the attributes, or style, for a range of text in a\rtfsp
+\helpref{wxTextCtrl}{wxtextctrl}.
+
+\wxheading{Derived from}
+
+No base class
+
+\wxheading{Include files}
+
+<wx/textctrl.h>
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxTextAttr::wxTextAttr}\label{wxtextattrctor}
+
+\func{}{wxTextAttr}{\void}
+
+\func{}{wxTextAttr}{\param{const wxColour\& }{colText}, \param{const wxColour\& }{colBack = wxNullColour}, \param{const wxFont\& }{font = wxNullFont}}
+
+The constructors initialize one or more of the text foreground and background
+colours and font. The values not initialized in the constructor can be set
+later, otherwise \helpref{wxTextCtrl::SetStyle}{wxtextctrlsetstyle} will use
+the default values for them.
+
+\membersection{wxTextAttr::GetBackgroundColour}
+
+\constfunc{const wxColour\&}{GetBackgroundColour}{\void}
+
+Return the background colour specified by this attribute.
+
+\membersection{wxTextAttr::GetFont}
+
+\constfunc{const wxFont\&}{GetFont}{\void}
+
+Return the text font specified by this attribute.
+
+\membersection{wxTextAttr::GetTextColour}
+
+\constfunc{const wxColour\&}{GetTextColour}{\void}
+
+Return the text colour specified by this attribute.
+
+\membersection{wxTextAttr::HasBackgroundColour}
+
+\constfunc{bool}{HasBackgroundColour}{\void}
+
+Returns {\tt TRUE} if this style specifies the background colour to use.
+
+\membersection{wxTextAttr::HasFont}
+
+\constfunc{bool}{HasFont}{\void}
+
+Returns {\tt TRUE} if this style specifies the font to use.
+
+\membersection{wxTextAttr::HasTextColour}
+
+\constfunc{bool}{HasTextColour}{\void}
+
+Returns {\tt TRUE} if this style specifies the foreground colour to use.
+
+\membersection{wxTextAttr::IsDefault}
+
+\constfunc{bool}{IsDefault}{\void}
+
+Returns {\tt TRUE} if this style specifies any non-default attributes.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxTextCtrl %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
\section{\class{wxTextCtrl}}\label{wxtextctrl}
A text control allows text to be displayed and edited. It may be
\twocolwidtha{5cm}
\begin{twocollist}\itemsep=0pt
-\twocolitem{\windowstyle{wxTE\_PROCESS\_ENTER}}{The callback function will
-receive the message wxEVENT\_TYPE\_TEXT\_ENTER\_COMMAND. Note
-that this will break tab traversal for this panel item under
-Windows.}
+\twocolitem{\windowstyle{wxTE\_PROCESS\_ENTER}}{The control will generate
+the message wxEVENT\_TYPE\_TEXT\_ENTER\_COMMAND (otherwise pressing <Enter> is
+either processed internally by the control or used for navigation between
+dialog controls).}
+\twocolitem{\windowstyle{wxTE\_PROCESS\_TAB}}{The control will receieve
+EVT\_CHAR messages for TAB pressed - normally, TAB is used for passing to the
+next control in a dialog instead. For the control created with this style,
+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 styles}
-This class multiply-inherits from {\bf streambuf} where compilers allow, allowing code such as the following:
+Multi-line text controls support the styles, i.e. provide a possibility to set
+colours and font for individual characters in it (note that under Windows {\tt
+wxTE\_RICH} style is required for style support). To use the styles you can
+either call \helpref{SetDefaultStyle}{wxtextctrlsetdefaultstyle} before
+inserting the text or call \helpref{SetStyle}{wxtextctrlsetstyle} later to
+change the style of the text already in the control (the first solution is
+much more efficient).
+
+In either case, if the style doesn't specify some of the attributes (for
+example you only want to set the text colour but without changing the font nor
+the text background), the values of the default style will be used for them.
+If there is no default style, the attributes of the text control itself are
+used.
+
+So the following code correctly describes what it does: the second call
+to \helpref{SetDefaultStyle}{wxtextctrlsetdefaultstyle} doesn't change the
+text foreground colour (which stays red) while the last one doesn't change the
+background colour (which stays grey):
+
+{\small%
+\begin{verbatim}
+ text->SetDefaultStyle(wxTextAttr(*wxRED));
+ text->AppendText("Red text\n");
+ text->SetDefaultStyle(wxTextAttr(wxNullColour, *wxLIGHT_GREY));
+ text->AppendText("Red on grey text\n");
+ text->SetDefaultStyle(wxTextAttr(*wxBLUE);
+ text->AppendText("Blue on grey text\n");
+\end{verbatim}
+}%
+
+\wxheading{wxTextCtrl and C++ streams}
+
+This class multiply-inherits from {\bf streambuf} where compilers allow,
+allowing code such as the following:
{\small%
\begin{verbatim}
\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,
\twocolwidtha{7cm}%
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf EVT\_TEXT(id, func)}}{Respond to a wxEVT\_COMMAND\_TEXT\_UPDATED event,
-generated when the text changes.}
+generated when the text changes. Notice that this event will always be sent
+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}
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}
Resets the internal `modified' flag as if the current edits had been saved.
+\membersection{wxTextCtrl::GetDefaultStyle}\label{wxtextctrlgetdefaultstyle}
+
+\constfunc{const wxTextAttr\& }{GetDefaultStyle}{\void}
+
+Returns the style currently used for the new text.
+
+\wxheading{See also}
+
+\helpref{SetDefaultStyle}{wxtextctrlsetdefaultstyle}
+
\membersection{wxTextCtrl::GetInsertionPoint}\label{wxtextctrlgetinsertionpoint}
\constfunc{virtual long}{GetInsertionPoint}{\void}
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.}
\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}
\wxheading{Remarks}
-This is not yet implemented for the GTK.
+This is not implemented on non-Windows platforms.
\wxheading{See also}
\membersection{wxTextCtrl::PositionToXY}\label{wxtextctrlpositiontoxy}
-\constfunc{long}{PositionToXY}{\param{long }{pos}, \param{long *}{x}, \param{long *}{y}}
+\constfunc{bool}{PositionToXY}{\param{long }{pos}, \param{long *}{x}, \param{long *}{y}}
Converts given position to a zero-based column, line number pair.
\wxheading{Return value}
-Non-zero on success, zero on failure (most likely due to a too large position
+TRUE on success, FALSE on failure (most likely due to a too large position
parameter).
\wxheading{See also}
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}
TRUE if the operation was successful, FALSE otherwise.
+\membersection{wxTextCtrl::SetDefaultStyle}\label{wxtextctrlsetdefaultstyle}
+
+\func{bool}{SetDefaultStyle}{\param{const wxTextAttr\& }{style}}
+
+Changes the default style to use for the new text which is going to be added
+to the control using \helpref{WriteText}{wxtextctrlwritetext} or\rtfsp
+\helpref{AppendText}{wxtextctrlappendtext}.
+
+If either of the font, foreground, or background colour is not set in\rtfsp
+{\it style}, the values of the previous default style are used for them. If
+the previous default style didn't set them neither, the global font or colours
+of the text control itself are used as fall back.
+
+However if the {\it style} parameter is the default wxTextAttr, then the
+default style is just reset (instead of being combined with the new style which
+wouldn't change it at all).
+
+\wxheading{Parameters}
+
+\docparam{style}{The style for the new text.}
+
+\wxheading{Return value}
+
+{\tt TRUE} on success, {\tt FALSE} if an error occured - may also mean that
+the styles are not supported under this platform.
+
+\wxheading{See also}
+
+\helpref{GetDefaultStyle}{wxtextctrlgetdefaultstyle}
+
\membersection{wxTextCtrl::SetEditable}\label{wxtextctrlseteditable}
\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}
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}}
\docparam{to}{The last position.}
+\membersection{wxTextCtrl::SetStyle}\label{wxtextctrlsetstyle}
+
+\func{bool}{SetStyle}{\param{long }{start}, \param{long }{end}, \param{const wxTextAttr\& }{style}}
+
+Changes the style of the selection. If either of the font, foreground, or
+background colour is not set in {\it style}, the values of\rtfsp
+\helpref{GetDefaultStyle()}{wxtextctrlgetdefaultstyle} are used.
+
+\wxheading{Parameters}
+
+\docparam{start}{The start of selection to change.}
+
+\docparam{end}{The end of selection to change.}
+
+\docparam{style}{The new style for the selection.}
+
+\wxheading{Return value}
+
+{\tt TRUE} on success, {\tt FALSE} if an error occured - may also mean that
+the styles are not supported under this platform.
+
\membersection{wxTextCtrl::SetValue}\label{wxtextctrlsetvalue}
\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}
projects / wxWidgets.git / blobdiff