.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Curses::UI::TextEditor 3"
.TH Curses::UI::TextEditor 3 "2011-09-01" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Curses::UI::TextEditor \- Create and manipulate texteditor widgets
.SH "CLASS HIERARCHY"
.IX Header "CLASS HIERARCHY"
.Vb 4
\& Curses::UI::Widget
\& Curses::UI::Searchable
\&    |
\&    +\-\-\-\-Curses::UI::TextEditor
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    use Curses::UI;
\&    my $cui = new Curses::UI;
\&    my $win = $cui\->add(\*(Aqwindow_id\*(Aq, \*(AqWindow\*(Aq);
\&
\&    my $editor = $win\->add(
\&        \*(Aqmyeditor\*(Aq, \*(AqTextEditor\*(Aq,
\&        \-vscrollbar => 1,
\&        \-wrapping   => 1,
\&    );
\&
\&    $editor\->focus();
\&    my $text = $editor\->get();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Curses::UI::TextEditor is a widget that can be used to create 
a couple of different kinds of texteditors. These are:
.IP "\(bu" 4
\&\fBmulti-line texteditor\fR
.Sp
This is a multi-line text editor with features like word-wrapping,
maximum textlength and undo.
.IP "\(bu" 4
\&\fBsingle-line texteditor\fR
.Sp
The texteditor can be created as a single-line editor. 
Most of the features of the default texteditor will remain.
Only the multi-line specific options will not be
available (like moving up and down in the text).
.IP "\(bu" 4
\&\fBread only texteditor\fR
.Sp
The texteditor can also be used in read only mode.
In this mode, the texteditor will function as a text
viewer. The user can walk through the text and 
search trough it.
.PP
See exampes/demo\-Curses::UI::TextEditor in the distribution
for a short demo of these.
.SH "STANDARD OPTIONS"
.IX Header "STANDARD OPTIONS"
\&\fB\-parent\fR, \fB\-x\fR, \fB\-y\fR, \fB\-width\fR, \fB\-height\fR, 
\&\fB\-pad\fR, \fB\-padleft\fR, \fB\-padright\fR, \fB\-padtop\fR, \fB\-padbottom\fR,
\&\fB\-ipad\fR, \fB\-ipadleft\fR, \fB\-ipadright\fR, \fB\-ipadtop\fR, \fB\-ipadbottom\fR,
\&\fB\-title\fR, \fB\-titlefullwidth\fR, \fB\-titlereverse\fR, \fB\-onfocus\fR,
\&\fB\-onblur\fR
.PP
For an explanation of these standard options, see 
Curses::UI::Widget.
.SH "WIDGET-SPECIFIC OPTIONS"
.IX Header "WIDGET-SPECIFIC OPTIONS"
.IP "\(bu" 4
\&\fB\-text\fR < \s-1TEXT \s0>
.Sp
This sets the initial text for the widget to \s-1TEXT.\s0
.IP "\(bu" 4
\&\fB\-pos\fR < \s-1CURSOR_POSITION \s0>
.Sp
This sets the initial cursor position for the widget
to \s-1CURSOR_POSITION. \s0\fB\-pos\fR represents the character index within
\&\fB\-text\fR. By default this option is set to 0.
.IP "\(bu" 4
\&\fB\-readonly\fR < \s-1BOOLEAN \s0>
.Sp
The texteditor widget will be created as a read only 
texteditor (which is also called a textviewer) if 
\&\s-1BOOLEAN\s0 is true. By default \s-1BOOLEAN\s0 is false.
.IP "\(bu" 4
\&\fB\-singleline\fR < \s-1BOOLEAN \s0>
.Sp
The texteditor widget will be created as a single line
texteditor (which is also called a textentry) if 
\&\s-1BOOLEAN\s0 is true. By default \s-1BOOLEAN\s0 is false.
.IP "\(bu" 4
\&\fB\-wrapping\fR < \s-1BOOLEAN \s0>
.Sp
If \s-1BOOLEAN\s0 is true, the texteditor will have text wrapping
enabled. By default \s-1BOOLEAN\s0 is false.
.IP "\(bu" 4
\&\fB\-showlines\fR < \s-1BOOLEAN \s0>
.Sp
If \s-1BOOLEAN\s0 is set to a true value, each editable line
in the editor will show a line to type on. By default
\&\s-1BOOLEAN\s0 is set to false.
.IP "\(bu" 4
\&\fB\-maxlength\fR < \s-1VALUE \s0>
.Sp
This sets the maximum allowed length of the text to 
\&\s-1VALUE.\s0 By default \s-1VALUE\s0 is set to 0, 
which means that the text may be infinitely long.
.IP "\(bu" 4
\&\fB\-maxlines\fR < \s-1VALUE \s0>
.Sp
This sets the maximum allowed number of lines for the text 
to \s-1SCALAR.\s0 By default \s-1VALUE\s0 is set to 0, which means that 
the text may contain an infinite number of lines.
.IP "\(bu" 4
\&\fB\-password\fR < \s-1CHARACTER \s0>
.Sp
Instead of showing the real text in the widget, every
character of the text will (on the screen) be replaced
by \s-1CHARACTER.\s0 So creating a standard password field
can be done by setting:
.Sp
.Vb 1
\&    \-password => \*(Aq*\*(Aq
.Ve
.IP "\(bu" 4
\&\fB\-regexp\fR < \s-1REGEXP \s0>
.Sp
If characters are added to the texteditor, the new text
will be matched against \s-1REGEXP.\s0 If the text does not match,
the change will be denied. This can for example be used to
force digit-only input on the texteditor:
.Sp
.Vb 1
\&    \-regexp => \*(Aq/^\ed*$/\*(Aq
.Ve
.IP "\(bu" 4
\&\fB\-undolevels\fR < \s-1VALUE \s0>
.Sp
This option determines how many undolevels should be kept
in memory for the texteditor widget. By default 10 levels
are kept. If this value is set to 0, the number of levels
is infinite.
.IP "\(bu" 4
\&\fB\-showoverflow\fR < \s-1BOOLEAN \s0>
.Sp
If \s-1BOOLEAN\s0 is true, the text in the texteditor will be
padded by an overflow character ($) if there is text
outside the screen (like 'pico' does). By default 
\&\s-1BOOLEAN\s0 is true.
.IP "\(bu" 4
\&\fB\-showhardreturns\fR < \s-1BOOLEAN \s0>
.Sp
If \s-1BOOLEAN\s0 is true, hard returns will be made visible
by a diamond character. By default \s-1BOOLEAN\s0 is false.
.IP "\(bu" 4
\&\fB\-homeonblur\fR < \s-1BOOLEAN \s0>
.Sp
If \s-1BOOLEAN\s0 is set to a true value, the cursor will move
to the start of the text if the widget loses focus.
.IP "\(bu" 4
\&\fB\-toupper\fR < \s-1BOOLEAN \s0>
.Sp
If \s-1BOOLEAN\s0 is true, all entered text will be converted
to uppercase. By default \s-1BOOLEAN\s0 is false.
.IP "\(bu" 4
\&\fB\-tolower\fR < \s-1BOOLEAN \s0>
.Sp
If \s-1BOOLEAN\s0 is true, all entered text will be converted
to lowercase. By default \s-1BOOLEAN\s0 is false.
.IP "\(bu" 4
\&\fB\-onchange\fR < \s-1CODEREF \s0>
.Sp
This sets the onChange event handler for the texteditor widget.
If the text is changed by typing, the code in \s-1CODEREF\s0 will 
be executed.  It will get the widget reference as its argument.
.IP "\(bu" 4
\&\fB\-reverse\fR < \s-1BOOLEAN \s0>
.Sp
Makes the text drawn in reverse font.
.SH "METHODS"
.IX Header "METHODS"
.IP "\(bu" 4
\&\fBnew\fR ( \s-1OPTIONS \s0)
.IP "\(bu" 4
\&\fBlayout\fR ( )
.IP "\(bu" 4
\&\fBdraw\fR ( \s-1BOOLEAN \s0)
.IP "\(bu" 4
\&\fBfocus\fR ( )
.IP "\(bu" 4
\&\fBonFocus\fR ( \s-1CODEREF \s0)
.IP "\(bu" 4
\&\fBonBlur\fR ( \s-1CODEREF \s0)
.Sp
These are standard methods. See Curses::UI::Widget 
for an explanation of these.
.IP "\(bu" 4
\&\fBtext\fR ( [\s-1TEXT\s0] )
.Sp
If \s-1TEXT\s0 is defined, this will set the text of the widget to \s-1TEXT.\s0
To see the change, the widget needs to be redrawn by the \fBdraw\fR method.
If \s-1TEXT\s0 is not defined, this method will return the current contents
of the texteditor.
.IP "\(bu" 4
\&\fBget\fR ( )
.Sp
This method will call \fBtext\fR without any arguments, so it
will return the contents of the texteditor.
.IP "\(bu" 4
\&\fBonChange\fR ( \s-1CODEREF \s0)
.Sp
This method can be used to set the \fB\-onchange\fR event handler
(see above) after initialization of the texteditor.
.IP "\(bu" 4
\&\fBset_password_char\fR ( \f(CW$char\fR )
.Sp
This method can be used to change the password property.  The password 
character will be set to \f(CW$char\fR, or turned off in \f(CW$char\fR is undef.
.IP "\(bu" 4
\&\fBtoggle_showhardreturns\fR
.Sp
Toggles the \-showhardreturns option.
.IP "\(bu" 4
\&\fBtoggle_showoverflow\fR
.Sp
Toggles the \-showoverflow option.
.IP "\(bu" 4
\&\fBtoggle_wrapping\fR
.Sp
Toggles the \-wrapping option.
.SH "DEFAULT BINDINGS"
.IX Header "DEFAULT BINDINGS"
There are different sets of bindings for each mode in which
this widget can be used.
.SS "All modes (editor, single line and read only)"
.IX Subsection "All modes (editor, single line and read only)"
.IP "\(bu" 4
<\fBtab\fR>
.Sp
Call the 'returreturnn' routine. This will have the widget 
loose its focus.
.IP "\(bu" 4
<\fBcursor-left\fR>, <\fB\s-1CTRL+B\s0\fR>
.Sp
Call the 'cursor\-left' routine: move the
cursor one position to the left.
.IP "\(bu" 4
<\fBcursor-right\fR>, <\fB\s-1CTRL+F\s0\fR>
.Sp
Call the 'cursor\-right' routine: move the
cursor one position to the right.
.IP "\(bu" 4
<\fBcursor-down\fR>, <\fB\s-1CTRL+N\s0\fR>
.Sp
Call the 'cursor\-down' routine: move the
cursor one line down.
.IP "\(bu" 4
<\fBcursor-up\fR>, <\fB\s-1CTRL+P\s0\fR>
.Sp
Call the 'cursor\-up' routine: move the
cursor one line up.
.IP "\(bu" 4
<\fBpage-up\fR>
.Sp
Call the 'cursor\-pageup' routine: move the
cursor to the previous page.
.IP "\(bu" 4
<\fBpage-down\fR>
.Sp
Call the 'cursor\-pagedown' routine: move
the cursor to the next page.
.IP "\(bu" 4
<\fBhome\fR>
.Sp
Call the 'cursor\-home' routine: go to the
start of the text.
.IP "\(bu" 4
<\fBend\fR>
.Sp
Call the 'cursor\-end' routine: go to the
end of the text.
.IP "\(bu" 4
<\fB\s-1CTRL+A\s0\fR>
.Sp
Call the 'cursor\-scrlinestart' routine: move the
cursor to the start of the current line.
.IP "\(bu" 4
<\fB\s-1CTRL+E\s0\fR>
.Sp
Call the 'cursor\-scrlineend' routine: move the
cursor to the end of the current line.
.IP "\(bu" 4
<\fB\s-1CTRL+W\s0\fR>
.Sp
Call the 'toggle\-wrapping' routine: toggle the
\&\-wrapping option of the texteditor.
.IP "\(bu" 4
<\fB\s-1CTRL+R\s0\fR>
.Sp
Call the 'toggle\-showhardreturns' routine: toggle the
\&\-showhardreturns option of the texteditor.
.IP "\(bu" 4
<\fB\s-1CTRL+T\s0\fR>
.Sp
Call the 'toggle\-showoverflow' routine: toggle the
\&\-showoverflow option of the texteditor.
.SS "All edit modes (all but read only mode)"
.IX Subsection "All edit modes (all but read only mode)"
.IP "\(bu" 4
<\fB\s-1CTRL+Y\s0\fR>, <\fB\s-1CTRL+X\s0\fR>
.Sp
Call the 'delete\-line' routine: Delete the current
line.
.IP "\(bu" 4
<\fB\s-1CTRL+K\s0\fR>
.Sp
Call the 'delete\-till\-eol' routine: delete the text
from the current cursor position up to the end of
the current line.
.IP "\(bu" 4
<\fB\s-1CTRL+U\s0\fR>
.Sp
Call the 'clear\-line' routine: clear the 
current line and move the cursor to the
start of this line.
.IP "\(bu" 4
<\fB\s-1CTRL+D\s0\fR>
.Sp
Call the 'delete\-character' routine: delete the 
character that currently is under the cursor.
.IP "\(bu" 4
<\fBbackspace\fR>
.Sp
Call the 'backspace' routine: delete the character
this is before the current cursor position.
.IP "\(bu" 4
<\fB\s-1CTRL+Z\s0\fR>
.Sp
Call the 'undo' routine: undo the last change to
the text, up to \fB\-undolevels\fR levels.
.IP "\(bu" 4
<\fB\s-1CTRL+V\s0\fR>
.Sp
Call the 'paste' routine: this will paste the 
last deleted text at the current cursor position.
.IP "\(bu" 4
<\fBany other key\fR>
.Sp
Call the 'add\-string' routine: the character
will be inserted in the text at the current
cursor position.
.SS "Only for the read only mode"
.IX Subsection "Only for the read only mode"
.IP "\(bu" 4
<\fBh\fR>
.Sp
Call the 'cursor\-left' routine: move the
cursor one position to the left.
.IP "\(bu" 4
<\fBl\fR>
.Sp
Call the 'cursor\-right' routine: move the
cursor one position to the right.
.IP "\(bu" 4
b<<k>>
.Sp
Call the 'cursor\-up' routine: move the
cursor one line up.
.IP "\(bu" 4
b<<j>>
.Sp
Call the 'cursor\-down' routine: move the
cursor one line down.
.IP "\(bu" 4
<\fBspace\fR>, <\fB]\fR>
.Sp
Call the 'cursor\-pagedown' routine: move
the cursor to the next page.
.IP "\(bu" 4
<\fB\-\fR>, <\fB[\fR>
.Sp
Call the 'cursor\-pageup' routine: move the
cursor to the previous page.
.IP "\(bu" 4
<\fB/\fR>
.Sp
Call the 'search\-forward' routine. This will make a 'less'\-like
search system appear in the textviewer. A searchstring can be
entered. After that the user can search for the next occurance
using the 'n' key or the previous occurance using the 'N' key.
.IP "\(bu" 4
<\fB?\fR>
.Sp
Call the 'search\-backward' routine. This will do the same as
the 'search\-forward' routine, only it will search in the
opposite direction.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Curses::UI, 
Curses::UI::TextViewer
Curses::UI::TextEntry
Curses::UI::Widget, 
Curses::UI::Common
.SH "AUTHOR"
.IX Header "AUTHOR"
Copyright (c) 2001\-2002 Maurice Makaay. All rights reserved.
.PP
Maintained by Marcus Thiesen (marcus@cpan.thiesenweb.de)
.PP
This package is free software and is provided \*(L"as is\*(R" without express
or implied warranty. It may be used, redistributed and/or modified
under the same terms as perl itself.