X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/a1665b22b07c572a240f9d83783044e3e4f9cb0e..44b62d54c61e4a0989fcc0f24eecfe0bd883d72b:/docs/latex/wx/text.tex diff --git a/docs/latex/wx/text.tex b/docs/latex/wx/text.tex index d2e831e459..d7bbb815c5 100644 --- a/docs/latex/wx/text.tex +++ b/docs/latex/wx/text.tex @@ -1,3 +1,75 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%% 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} + + + +\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 @@ -30,15 +102,57 @@ 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} @@ -51,9 +165,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 + + 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 + + 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 +239,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 +287,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} @@ -155,34 +325,34 @@ the programmer should use \helpref{GetInsertionPoint}{wxtextctrlgetinsertionpoin \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} @@ -219,6 +389,16 @@ Copies the selected text to the clipboard and removes the selection. 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} @@ -302,6 +482,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,17 +498,30 @@ 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} \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} @@ -335,7 +535,7 @@ Loads and displays the named file, if it exists. \wxheading{Return value} -TRUE if successful, FALSE otherwise. +{\tt TRUE} if successful, {\tt FALSE} otherwise. \membersection{wxTextCtrl::OnChar}\label{wxtextctrlonchar} @@ -378,7 +578,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} @@ -406,7 +606,7 @@ Converts given position to a zero-based column, line number pair. \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} @@ -417,6 +617,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} @@ -464,18 +667,47 @@ Saves the contents of the control in a text file. \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} \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} -\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} @@ -494,6 +726,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}} @@ -506,11 +762,34 @@ Selects the text starting at the first position up to (but not including) the ch \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 (which means that +\helpref{IsModified}{wxtextctrlismodified} would return {\tt FALSE} immediately +after the call to SetValue). \wxheading{Parameters}