.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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 >0, 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Tickit::Widget::Entry 3pm"
.TH Tickit::Widget::Entry 3pm "2020-11-04" "perl v5.30.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"
"Tickit::Widget::Entry" \- a widget for entering text
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&   use Tickit;
\&   use Tickit::Widget::Entry;
\&
\&   my $entry = Tickit::Widget::Entry\->new(
\&      on_enter => sub {
\&         my ( $self, $line ) = @_;
\&
\&         # process $line somehow
\&
\&         $self\->set_text( "" );
\&      },
\&   );
\&
\&   Tickit\->new( root => $entry )\->run;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class provides a widget which allows the user to enter a line of text.
.SH "STYLE"
.IX Header "STYLE"
The default style pen is used as the widget pen. The following style pen
prefixes are also used:
.IP "more => \s-1PEN\s0" 4
.IX Item "more => PEN"
The pen used for the \*(L"more\*(R" scroll markers
.PP
The following style keys are used:
.IP "more_left => \s-1STRING\s0" 4
.IX Item "more_left => STRING"
.PD 0
.IP "more_right => \s-1STRING\s0" 4
.IX Item "more_right => STRING"
.PD
The text used to indicate that there is more content scrolled to the left or
right, respectively
.SH "KEYBINDINGS"
.IX Header "KEYBINDINGS"
The following keys are bound by default
.IP "\(bu" 2
Ctrl-K
.Sp
Delete the entire line
.IP "\(bu" 2
Ctrl-U
.Sp
Delete to the start of the line
.IP "\(bu" 2
Ctrl-W or Ctrl-Backspace
.Sp
Delete one word backwards
.IP "\(bu" 2
Backspace
.Sp
Delete one character backwards
.IP "\(bu" 2
Delete
.Sp
Delete one character forwards
.IP "\(bu" 2
Ctrl-Delete
.Sp
Delete one word forwards
.IP "\(bu" 2
End or Ctrl-E
.Sp
Move the cursor to the end of the input line
.IP "\(bu" 2
Enter
.Sp
Accept a line of input by running the \f(CW\*(C`on_enter\*(C'\fR action
.IP "\(bu" 2
Home or Ctrl-A
.Sp
Move the cursor to the beginning of the input line
.IP "\(bu" 2
Insert
.Sp
Toggle between overwrite and insert mode
.IP "\(bu" 2
Left
.Sp
Move the cursor one character left
.IP "\(bu" 2
Ctrl-Left or Alt-B
.Sp
Move the cursor one word left
.IP "\(bu" 2
Right
.Sp
Move the cursor one character right
.IP "\(bu" 2
Ctrl-Right or Alt-F
.Sp
Move the cursor one word right
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.SS "new"
.IX Subsection "new"
.Vb 1
\&   $entry = Tickit::Widget::Entry\->new( %args )
.Ve
.PP
Constructs a new \f(CW\*(C`Tickit::Widget::Entry\*(C'\fR object.
.PP
Takes the following named arguments:
.IP "text => \s-1STR\s0" 8
.IX Item "text => STR"
Optional. Initial text to display in the box
.IP "position => \s-1INT\s0" 8
.IX Item "position => INT"
Optional. Initial position of the cursor within the text.
.IP "on_enter => \s-1CODE\s0" 8
.IX Item "on_enter => CODE"
Optional. Callback function to invoke when the \f(CW\*(C`<Enter>\*(C'\fR key is pressed.
.SH "ACCESSORS"
.IX Header "ACCESSORS"
.SS "on_enter"
.IX Subsection "on_enter"
.Vb 1
\&   $on_enter = $entry\->on_enter
.Ve
.SS "set_on_enter"
.IX Subsection "set_on_enter"
.Vb 1
\&   $entry\->set_on_enter( $on_enter )
.Ve
.PP
Return or set the \s-1CODE\s0 reference to be called when the \f(CW\*(C`key_enter_line\*(C'\fR
action is invoked; usually bound to the \f(CW\*(C`Enter\*(C'\fR key.
.PP
.Vb 1
\& $on_enter\->( $entry, $line )
.Ve
.SS "position"
.IX Subsection "position"
.Vb 1
\&   $offset = $entry\->position
.Ve
.PP
Returns the current entry position, in terms of characters within the text.
.SS "set_position"
.IX Subsection "set_position"
.Vb 1
\&   $entry\->set_position( $position )
.Ve
.PP
Set the text entry position, moving the cursor
.SH "METHODS"
.IX Header "METHODS"
.SS "bind_keys"
.IX Subsection "bind_keys"
.Vb 1
\&   $entry\->bind_keys( $keystr => $value, ... )
.Ve
.PP
Associate methods or \s-1CODE\s0 references with keypresses. On receipt of a the key
the method or \s-1CODE\s0 reference will be invoked, being passed the stringified key
representation and the underlying \f(CW\*(C`Term::TermKey::Key\*(C'\fR structure.
.PP
.Vb 2
\&   $ret = $entry\->method( $keystr, $key )
\&   $ret = $coderef\->( $entry, $keystr, $key )
.Ve
.PP
This method takes a hash of keystring/value pairs. Binding a value of \f(CW\*(C`undef\*(C'\fR
will remove it.
.SH "TEXT MODEL METHODS"
.IX Header "TEXT MODEL METHODS"
These methods operate on the text input buffer directly, updating the stored
text and changing the rendered display to reflect the changes. They can be
used by a program to directly manipulate the text.
.SS "text"
.IX Subsection "text"
.Vb 1
\&   $text = $entry\->text
.Ve
.PP
Returns the currently entered text.
.SS "set_text"
.IX Subsection "set_text"
.Vb 1
\&   $entry\->set_text( $text )
.Ve
.PP
Replace the text in the entry box. This completely redraws the widget's
window. It is largely provided for initialisation; for normal edits (such as
from keybindings), it is preferable to use \f(CW\*(C`text_insert\*(C'\fR, \f(CW\*(C`text_delete\*(C'\fR or
\&\f(CW\*(C`text_splice\*(C'\fR.
.SS "text_insert"
.IX Subsection "text_insert"
.Vb 1
\&   $entry\->text_insert( $text, $pos_ch )
.Ve
.PP
Insert the given text at the given character position.
.SS "text_delete"
.IX Subsection "text_delete"
.Vb 1
\&   $deleted = $entry\->text_delete( $pos_ch, $len_ch )
.Ve
.PP
Delete the given section of text. Returns the deleted text.
.SS "text_splice"
.IX Subsection "text_splice"
.Vb 1
\&   $deleted = $entry\->text_splice( $pos_ch, $len_ch, $text )
.Ve
.PP
Replace the given section of text with the given replacement. Returns the
text deleted from the section.
.SS "find_bow_forward"
.IX Subsection "find_bow_forward"
.Vb 1
\&   $pos = $entry\->find_bow_forward( $initial, $else )
.Ve
.PP
Search forward in the string, returning the character position of the next
beginning of word from the initial position. If none is found, returns
\&\f(CW$else\fR.
.SS "find_eow_forward"
.IX Subsection "find_eow_forward"
.Vb 1
\&   $pos = $entry\->find_eow_forward( $initial )
.Ve
.PP
Search forward in the string, returning the character position of the next
end of word from the initial position. If none is found, returns the length of
the string.
.SS "find_bow_backward"
.IX Subsection "find_bow_backward"
.Vb 1
\&   $pos = $entry\->find_bow_backward( $initial )
.Ve
.PP
Search backward in the string, returning the character position of the
previous beginning of word from the initial position. If none is found,
returns 0.
.SS "find_eow_backward"
.IX Subsection "find_eow_backward"
.Vb 1
\&   $pos = $entry\->find_eow_backward( $initial )
.Ve
.PP
Search backward in the string, returning the character position of the
previous end of word from the initial position. If none is found, returns
\&\f(CW\*(C`undef\*(C'\fR.
.SH "TODO"
.IX Header "TODO"
.IP "\(bu" 4
Plugin ability
.Sp
Try to find a nice way to allow loaded plugins, possibly per-instance if not
just globally or per-class. See how many of these \s-1TODO\s0 items can be done using
plugins.
.IP "\(bu" 4
More readline behaviours
.Sp
History. Isearch. History replay. Transpose. Transcase. Yank ring. Numeric
prefixes.
.IP "\(bu" 4
Visual selection behaviour
.Sp
Shift-movement, or vim-style. Mouse.
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>