[wxWidgets.git] / docs / latex / wx / text.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 wxPoint\& }{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 wxPoint\& }{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}