5de76427c8
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@447 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
441 lines
12 KiB
TeX
441 lines
12 KiB
TeX
\section{\class{wxTextCtrl}}\label{wxtextctrl}
|
|
|
|
A text control allows text to be displayed and edited. It may be
|
|
single line or multiline.
|
|
|
|
\wxheading{Derived from}
|
|
|
|
streambuf\\
|
|
\helpref{wxControl}{wxcontrol}\\
|
|
\helpref{wxWindow}{wxwindow}\\
|
|
\helpref{wxEvtHandler}{wxevthandler}\\
|
|
\helpref{wxObject}{wxobject}
|
|
|
|
\wxheading{Window styles}
|
|
|
|
\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\_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 vertical scrollbar will be present.}
|
|
\end{twocollist}
|
|
|
|
See also \helpref{window styles overview}{windowstyles}.
|
|
|
|
\wxheading{Remarks}
|
|
|
|
This class multiply-inherits from {\bf streambuf} where compilers allow, allowing code such
|
|
as the following:
|
|
|
|
{\small%
|
|
\begin{verbatim}
|
|
wxTextCtrl *control = new wxTextCtrl(...);
|
|
|
|
ostream stream(control)
|
|
|
|
stream << 123.456 << " some text\n";
|
|
stream.flush();
|
|
\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.
|
|
|
|
\wxheading{Event handling}
|
|
|
|
To process input from a text control, use these event handler macros to direct input to member
|
|
functions that take a \helpref{wxCommandEvent}{wxcommandevent} argument.
|
|
|
|
\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.}
|
|
\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.}
|
|
\end{twocollist}%
|
|
|
|
%\wxheading{See also}
|
|
%
|
|
%\helpref{wxRichTextCtrl}{wxrichtextctrl}
|
|
%
|
|
\latexignore{\rtfignore{\wxheading{Members}}}
|
|
|
|
\membersection{wxTextCtrl::wxTextCtrl}\label{wxtextctrlconstr}
|
|
|
|
\func{}{wxTextCtrl}{\void}
|
|
|
|
Default constructor.
|
|
|
|
\func{}{wxTextCtrl}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id},\rtfsp
|
|
\param{const wxString\& }{value = ``"}, \param{const wxPosition\& }{pos}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
|
|
\param{long}{ style = 0}, \param{const wxValidator\& }{validator}, \param{const wxString\& }{name = ``text"}}
|
|
|
|
Constructor, creating and showing a text control.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{parent}{Parent window. Should not be NULL.}
|
|
|
|
\docparam{id}{Control identifier. A value of -1 denotes a default value.}
|
|
|
|
\docparam{value}{Default text value.}
|
|
|
|
\docparam{pos}{Text control position.}
|
|
|
|
\docparam{size}{Text control size.}
|
|
|
|
\docparam{style}{Window style. See \helpref{wxTextCtrl}{wxtextctrl}.}
|
|
|
|
\docparam{validator}{Window validator.}
|
|
|
|
\docparam{name}{Window name.}
|
|
|
|
\wxheading{Remarks}
|
|
|
|
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}
|
|
|
|
\helpref{wxTextCtrl::Create}{wxtextctrlcreate}, \helpref{wxValidator}{wxvalidator}
|
|
|
|
\membersection{wxTextCtrl::\destruct{wxTextCtrl}}
|
|
|
|
\func{}{\destruct{wxTextCtrl}}{\void}
|
|
|
|
Destructor, destroying the text control.
|
|
|
|
\membersection{wxTextCtrl::Clear}\label{wxtextctrlclear}
|
|
|
|
\func{virtual void}{Clear}{\void}
|
|
|
|
Clears the text in the control.
|
|
|
|
\membersection{wxTextCtrl::Copy}\label{wxtextctrlcopy}
|
|
|
|
\func{virtual void}{Copy}{\void}
|
|
|
|
Copies the selected text to the clipboard under Motif and MS Windows.
|
|
|
|
\membersection{wxTextCtrl::Create}\label{wxtextctrlcreate}
|
|
|
|
\func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id},\rtfsp
|
|
\param{const wxString\& }{value = ``"}, \param{const wxPosition\& }{pos}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
|
|
\param{long}{ style = 0}, \param{const wxValidator\& }{validator}, \param{const wxString\& }{name = ``text"}}
|
|
|
|
Creates the text control for two-step construction. Derived classes
|
|
should call or replace this function. See \helpref{wxTextCtrl::wxTextCtrl}{wxtextctrlconstr}\rtfsp
|
|
for further details.
|
|
|
|
\membersection{wxTextCtrl::Cut}\label{wxtextctrlcut}
|
|
|
|
\func{virtual void}{Cut}{\void}
|
|
|
|
Copies the selected text to the clipboard and removes the selection.
|
|
|
|
\membersection{wxTextCtrl::DiscardEdits}
|
|
|
|
\func{void}{DiscardEdits}{\void}
|
|
|
|
Resets the internal `modified' flag as if the current edits had been saved.
|
|
|
|
\membersection{wxTextCtrl::GetInsertionPoint}\label{wxtextctrlgetinsertionpoint}
|
|
|
|
\constfunc{virtual long}{GetInsertionPoint}{\void}
|
|
|
|
Returns the insertion point.
|
|
|
|
\membersection{wxTextCtrl::GetLastPosition}\label{wxtextctrlgetlastposition}
|
|
|
|
\constfunc{virtual long}{GetLastPosition}{\void}
|
|
|
|
Returns the last position in the text control.
|
|
|
|
\membersection{wxTextCtrl::GetLineLength}\label{wxtextctrlgetlinelength}
|
|
|
|
\constfunc{int}{GetLineLength}{\param{long}{ lineNo}}
|
|
|
|
Gets the length of the specified line.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{lineNo}{Line number (starting from zero).}
|
|
|
|
\wxheading{Return value}
|
|
|
|
The length of the line, or -1 if {\it lineNo} was invalid.
|
|
|
|
\membersection{wxTextCtrl::GetLineText}\label{wxtextctrlgetlinetext}
|
|
|
|
\constfunc{wxString}{GetLineText}{\param{long}{ lineNo}}
|
|
|
|
Returns the contents of a given line in the text control.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{lineNo}{The line number, starting from zero.}
|
|
|
|
\wxheading{Return value}
|
|
|
|
The contents of the line.
|
|
|
|
\membersection{wxTextCtrl::GetNumberOfLines}\label{wxtextctrlgetnumberoflines}
|
|
|
|
\constfunc{int}{GetNumberOfLines}{\void}
|
|
|
|
Returns the number of lines in the text control buffer.
|
|
|
|
\membersection{wxTextCtrl::GetValue}\label{wxtextctrlgetvalue}
|
|
|
|
\constfunc{wxString}{GetValue}{\void}
|
|
|
|
Gets the contents of the control.
|
|
|
|
\membersection{wxTextCtrl::IsModified}\label{wxtextctrlismodified}
|
|
|
|
\constfunc{bool}{IsModified}{\void}
|
|
|
|
Returns TRUE if the text has been modified.
|
|
|
|
\membersection{wxTextCtrl::LoadFile}\label{wxtextctrlloadfile}
|
|
|
|
\func{bool}{LoadFile}{\param{const wxString\& }{ filename}}
|
|
|
|
Loads and displays the named file, if it exists.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{filename}{The filename of the file to load.}
|
|
|
|
\wxheading{Return value}
|
|
|
|
TRUE if successful, FALSE otherwise.
|
|
|
|
\membersection{wxTextCtrl::OnChar}\label{wxtextctrlonchar}
|
|
|
|
\func{void}{OnChar}{\param{wxKeyEvent\& }{event}}
|
|
|
|
Default handler for character input.
|
|
|
|
\wxheading{Remarks}
|
|
|
|
It is possible to intercept character
|
|
input by overriding this member. Call this function
|
|
to let the default behaviour take place; not calling
|
|
it results in the character being ignored. You can
|
|
replace the {\it keyCode} member of {\it event} to
|
|
translate keystrokes.
|
|
|
|
Note that Windows and Motif have different ways
|
|
of implementing the default behaviour. In Windows,
|
|
calling wxTextCtrl::OnChar immediately
|
|
processes the character. In Motif,
|
|
calling this function simply sets a flag
|
|
to let default processing happen. This might affect
|
|
the way in which you write your OnChar function
|
|
on different platforms.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxKeyEvent}{wxkeyevent}
|
|
|
|
\membersection{wxTextCtrl::OnDropFiles}\label{wxtextctrlondropfiles}
|
|
|
|
\func{void}{OnDropFiles}{\param{wxDropFilesEvent\& }{event}}
|
|
|
|
This event handler function implements default drag and drop behaviour, which
|
|
is to load the first dropped file into the control.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{event}{The drop files event.}
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxDropFilesEvent}{wxdropfilesevent}
|
|
|
|
\membersection{wxTextCtrl::Paste}\label{wxtextctrlpaste}
|
|
|
|
\func{virtual void}{Paste}{\void}
|
|
|
|
Pastes text from the clipboard to the text item.
|
|
|
|
\membersection{wxTextCtrl::PositionToXY}\label{wxtextctrlpositiontoxy}
|
|
|
|
\constfunc{long}{PositionToXY}{\param{long }{pos}, \param{long *}{x}, \param{long *}{y}}
|
|
|
|
Converts given character and line position to a position.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{pos}{Position.}
|
|
|
|
\docparam{x}{Receives character position.}
|
|
|
|
\docparam{y}{Receives line position.}
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxTextCtrl::XYToPosition}{wxtextctrlxytoposition}
|
|
|
|
\membersection{wxTextCtrl::Remove}\label{wxtextctrlremove}
|
|
|
|
\func{virtual void}{Remove}{\param{long}{ from}, \param{long}{ to}}
|
|
|
|
Removes the text between the two positions.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{from}{The first position.}
|
|
|
|
\docparam{to}{The last position.}
|
|
|
|
\membersection{wxTextCtrl::Replace}\label{wxtextctrlreplace}
|
|
|
|
\func{virtual void}{Replace}{\param{long}{ from}, \param{long}{ to}, \param{const wxString\& }{value}}
|
|
|
|
Replaces the text between two positions with the given text.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{from}{The first position.}
|
|
|
|
\docparam{to}{The last position.}
|
|
|
|
\docparam{value}{The value to replace the existing text with.}
|
|
|
|
\membersection{wxTextCtrl::SaveFile}\label{wxtextctrlsavefile}
|
|
|
|
\func{bool}{SaveFile}{\param{const wxString\& }{ filename}}
|
|
|
|
Saves the contents of the control in a text file.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{filename}{The name of file in which to save the text.}
|
|
|
|
\wxheading{Return value}
|
|
|
|
TRUE if the operation was successful, FALSE otherwise.
|
|
|
|
\membersection{wxTextCtrl::SetEditable}\label{wxtextctrlseteditable}
|
|
|
|
\func{virtual void}{SetEditable}{\param{const bool}{ editable}}
|
|
|
|
Makes the text item editable or read-only.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{editable}{If TRUE, the control is editable. If FALSE, the control is read-only.}
|
|
|
|
\membersection{wxTextCtrl::SetInsertionPoint}\label{wxtextctrlsetinsertionpoint}
|
|
|
|
\func{virtual void}{SetInsertionPoint}{\param{long}{ pos}}
|
|
|
|
Sets the insertion point. Windows only. ??
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{pos}{Position to set.}
|
|
|
|
\membersection{wxTextCtrl::SetInsertionPointEnd}\label{wxtextctrlsetinsertionpointend}
|
|
|
|
\func{virtual void}{SetInsertionPointEnd}{\void}
|
|
|
|
Sets the insertion point at the end of the text control.
|
|
|
|
\membersection{wxTextCtrl::SetSelection}\label{wxtextctrlsetselection}
|
|
|
|
\func{virtual void}{SetSelection}{\param{long}{ from}, \param{long}{ to}}
|
|
|
|
Selects the text between the two positions.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{from}{The first position.}
|
|
|
|
\docparam{to}{The last position.}
|
|
|
|
\membersection{wxTextCtrl::SetValue}\label{wxtextctrlsetvalue}
|
|
|
|
\func{virtual void}{SetValue}{\param{const wxString\& }{ value}}
|
|
|
|
Sets the text value.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{value}{The new value to set. It may contain newline characters if the text control is multi-line.}
|
|
|
|
\membersection{wxTextCtrl::ShowPosition}\label{wxtextctrlshowposition}
|
|
|
|
\func{void}{ShowPosition}{\param{long}{ pos}}
|
|
|
|
Makes the line containing the given position visible.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{pos}{The position that should be visible.}
|
|
|
|
\membersection{wxTextCtrl::WriteText}\label{wxtextctrlwritetext}
|
|
|
|
\func{void}{WriteText}{\param{const wxString\& }{ text}}
|
|
|
|
Writes the text into the text control at the current position.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{text}{Text to write to the text control.}
|
|
|
|
\wxheading{Remarks}
|
|
|
|
Newlines in the text string
|
|
are the only control characters allowed, and they will cause appropriate
|
|
line breaks. See \helpref{wxTextCtrl::\cinsert}{wxtextctrlinsert} for more convenient ways of writing to the
|
|
window.
|
|
|
|
\membersection{wxTextCtrl::XYToPosition}\label{wxtextctrlxytoposition}
|
|
|
|
\func{long}{XYToPosition}{\param{long}{ x}, \param{long}{ y}}
|
|
|
|
Converts the given character and line position to a position.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{x}{The character position.}
|
|
|
|
\docparam{y}{The line position.}
|
|
|
|
\wxheading{Return value}
|
|
|
|
The position value.
|
|
|
|
\membersection{wxTextCtrl::operator \cinsert}\label{wxtextctrlinsert}
|
|
|
|
\func{wxTextCtrl\&}{operator \cinsert}{\param{const wxString\& }{s}}
|
|
|
|
\func{wxTextCtrl\&}{operator \cinsert}{\param{int}{ i}}
|
|
|
|
\func{wxTextCtrl\&}{operator \cinsert}{\param{long}{ i}}
|
|
|
|
\func{wxTextCtrl\&}{operator \cinsert}{\param{float}{ f}}
|
|
|
|
\func{wxTextCtrl\&}{operator \cinsert}{\param{double}{ d}}
|
|
|
|
\func{wxTextCtrl\&}{operator \cinsert}{\param{char}{ c}}
|
|
|
|
Operator definitions for writing to a text control, for example:
|
|
|
|
\begin{verbatim}
|
|
wxTextCtrl *wnd = new wxTextCtrl(my_frame);
|
|
|
|
(*wnd) << "Welcome to text control number " << 1 << ".\n";
|
|
\end{verbatim}
|
|
|
|
|