+%%%%%%%%%%%%%%%%%%%%%%%%%%%% 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
\twocolitem{\windowstyle{wxHSCROLL}}{A horizontal scrollbar will be created. No effect under GTK+.}
\end{twocollist}
-See also \helpref{window styles overview}{windowstyles} and
+See also \helpref{window styles overview}{windowstyles} and
\helpref{wxTextCtrl::wxTextCtrl}{wxtextctrlconstr}.
+\wxheading{wxTextCtrl styles}
+
+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,
\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
+into the control than the limit set by
\helpref{SetMaxLength}{wxtextctrlsetmaxlength}.}
\end{twocollist}%
\func{virtual bool}{CanCopy}{\void}
-Returns TRUE if the selection can be copied to the clipboard.
+Returns {\tt TRUE} if the selection can be copied to the clipboard.
\membersection{wxTextCtrl::CanCut}\label{wxtextctrlcancut}
\func{virtual bool}{CanCut}{\void}
-Returns TRUE if the selection can be cut to the clipboard.
+Returns {\tt TRUE} if the selection can be cut to the clipboard.
\membersection{wxTextCtrl::CanPaste}\label{wxtextctrlcanpaste}
\func{virtual bool}{CanPaste}{\void}
-Returns TRUE if the contents of the clipboard can be pasted into the
+Returns {\tt TRUE} if the contents of the clipboard can be pasted into the
text control. On some platforms (Motif, GTK) this is an approximation
-and returns TRUE if the control is editable, FALSE otherwise.
+and returns {\tt TRUE} if the control is editable, {\tt FALSE} otherwise.
\membersection{wxTextCtrl::CanRedo}\label{wxtextctrlcanredo}
\func{virtual bool}{CanRedo}{\void}
-Returns TRUE if there is a redo facility available and the last operation
+Returns {\tt TRUE} if there is a redo facility available and the last operation
can be redone.
\membersection{wxTextCtrl::CanUndo}\label{wxtextctrlcanundo}
\func{virtual bool}{CanUndo}{\void}
-Returns TRUE if there is an undo facility available and the last operation
+Returns {\tt TRUE} if there is an undo facility available and the last operation
can be undone.
\membersection{wxTextCtrl::Clear}\label{wxtextctrlclear}
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.}
\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}
\constfunc{bool}{IsModified}{\void}
-Returns TRUE if the text has been modified.
+Returns {\tt TRUE} if the text has been modified by user. Note that calling
+\helpref{SetValue}{wxtextctrlsetvalue} doesn't make the control modified.
\membersection{wxTextCtrl::LoadFile}\label{wxtextctrlloadfile}
\wxheading{Return value}
-TRUE if successful, FALSE otherwise.
+{\tt TRUE} if successful, {\tt FALSE} otherwise.
\membersection{wxTextCtrl::OnChar}\label{wxtextctrlonchar}
\wxheading{Return value}
-TRUE on success, FALSE on failure (most likely due to a too large position
+{\tt TRUE} on success, {\tt FALSE} on failure (most likely due to a too large position
parameter).
\wxheading{See also}
\wxheading{Return value}
-TRUE if the operation was successful, FALSE otherwise.
+{\tt TRUE} if the operation was successful, {\tt 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}
\wxheading{Parameters}
-\docparam{editable}{If TRUE, the control is editable. If FALSE, the control is read-only.}
+\docparam{editable}{If {\tt TRUE}, the control is editable. If {\tt FALSE}, the control is read-only.}
\membersection{wxTextCtrl::SetInsertionPoint}\label{wxtextctrlsetinsertionpoint}
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
+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.
\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 and marks the control as not-modified.
+Sets the text value and marks the control as not-modified (which means that
+\helpref{IsModified}{wxtextctrlismodified} would return {\tt FALSE} immediately
+after the call to SetValue).
\wxheading{Parameters}
projects / wxWidgets.git / blobdiff