X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/9c8849722a71ee7139e035bca5fdb2ae7b0af570..a9249b2eb2a40d8c71f828669045c4ddaa8dc5ff:/docs/latex/wx/text.tex diff --git a/docs/latex/wx/text.tex b/docs/latex/wx/text.tex index a9bf9028d5..befde50163 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} + +<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 @@ -30,16 +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{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} @@ -52,11 +165,62 @@ the following: \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 wxTextCtrl header file. +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(...); -Note that any use of C++ iostreams (including this one) deprecated and might get completely removed -in the future. + *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} @@ -75,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} @@ -122,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} @@ -223,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} @@ -306,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.} @@ -315,11 +498,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} @@ -382,7 +577,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} @@ -421,6 +616,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,12 +668,41 @@ Saves the contents of the control in a text file. 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} @@ -498,6 +725,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,11 +761,32 @@ 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. \wxheading{Parameters}