.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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 "Term::TermKey 3pm"
.TH Term::TermKey 3pm "2020-11-09" "perl v5.32.0" "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"
"Term::TermKey" \- perl wrapper around "libtermkey"
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Term::TermKey;
\&
\& my $tk = Term::TermKey\->new( \e*STDIN );
\&
\& print "Press any key\en";
\&
\& $tk\->waitkey( my $key );
\&
\& print "You pressed: " . $tk\->format_key( $key, 0 );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.RS 4
\&\fBNote\fR that \f(CW\*(C`libtermkey\*(C'\fR itself is deprecated in favour of its eventual
merge into \f(CW\*(C`libtickit\*(C'\fR. As a result, uses of this module should also be
considered deprecated. Consider rewriting code to use Tickit instead;
either by creating a Tickit::Term to receive key input events, or perform a
more wholescale rewrite into using \f(CW\*(C`Tickit\*(C'\fR generally for all screen
interaction purposes.
.RE
.PP
This module provides a light perl wrapper around the \f(CW\*(C`libtermkey\*(C'\fR library.
This library attempts to provide an abstract way to read keypress events in
terminal-based programs by providing structures that describe keys, rather
than simply returning raw bytes as read from the \s-1TTY\s0 device.
.PP
This version of \f(CW\*(C`Term::TermKey\*(C'\fR requires \f(CW\*(C`libtermkey\*(C'\fR version at least 0.16.
.SS "Multi-byte keys, ambiguous keys, and waittime"
.IX Subsection "Multi-byte keys, ambiguous keys, and waittime"
Some keypresses generate multiple bytes from the terminal. There is also the
ambiguity between multi-byte \s-1CSI\s0 or \s-1SS3\s0 sequences, and the Escape key itself.
The waittime timer is used to distinguish them.
.PP
When some bytes arrive that could be the start of possibly multiple different
keypress events, the library will attempt to wait for more bytes to arrive
that would finish it. If no more bytes arrive after this time, then the bytes
will be reported as events as they stand, even if this results in interpreting
a partially-complete Escape sequence as a literal Escape key followed by some
normal letters or other symbols.
.PP
Similarly, if the start of an incomplete \s-1UTF\-8\s0 sequence arrives when the
library is in \s-1UTF\-8\s0 mode, this will be reported as the \s-1UTF\-8\s0 replacement
character (U+FFFD) if it is incomplete after this time.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.SS "new"
.IX Subsection "new"
.Vb 1
\&   $tk = Term::TermKey\->new( $fh, $flags )
.Ve
.PP
Construct a new \f(CW\*(C`Term::TermKey\*(C'\fR object that wraps the given term handle.
\&\f(CW$fh\fR should be either an \s-1IO\s0 handle reference, an integer referring to a
plain \s-1POSIX\s0 file descriptor, of \f(CW\*(C`undef\*(C'\fR. \f(CW$flags\fR is optional, but if given
should contain the flags to pass to \f(CW\*(C`libtermkey\*(C'\fR's constructor. Assumes a
default of 0 if not supplied. See the \f(CW\*(C`FLAG_*\*(C'\fR constants.
.SS "new_abstract"
.IX Subsection "new_abstract"
.Vb 1
\&   $tk = Term::TermKey\->new_abstract( $termtype, $flags )
.Ve
.PP
Construct a new abstract \f(CW\*(C`Term::TermKey\*(C'\fR object not associated with a
filehandle. Input may be fed to it using the \f(CW\*(C`push_bytes()\*(C'\fR method
rather than \f(CW\*(C`waitkey()\*(C'\fR or \f(CW\*(C`advisereadable()\*(C'\fR. The name of the termtype
should be given in the \f(CW$termtype\fR string.
.SH "METHODS"
.IX Header "METHODS"
.SS "start"
.IX Subsection "start"
.SS "stop"
.IX Subsection "stop"
.Vb 1
\&   $success = $tk\->start
\&
\&   $success = $tk\->stop
.Ve
.PP
Start or stop \s-1IO\s0 interactions from the instance. Starting will send the
terminal initialisation sequence and set up \f(CWtermios(5)\fR settings, stopping
will send the terminal shutdown sequence and restore \f(CWtermios(5)\fR back to the
initial values. After construction, a \f(CW\*(C`Term::TermKey\*(C'\fR instance is already
started, but these methods may be used to suspend and resume, for example, on
receipt of a \f(CW\*(C`SIGTSTP\*(C'\fR signal requesting that the application background
itself.
.PP
Returns false if it fails; \f(CW$!\fR will contain an error code.
.SS "is_started"
.IX Subsection "is_started"
.Vb 1
\&   $started = $tk\->is_started
.Ve
.PP
Returns true if the instance has been started, or false if it is stopped.
.SS "get_flags"
.IX Subsection "get_flags"
.SS "set_flags"
.IX Subsection "set_flags"
.Vb 1
\&   $flags = $tk\->get_flags
\&
\&   $tk\->set_flags( $newflags )
.Ve
.PP
Accessor and mutator for the flags. One of the \f(CW\*(C`FLAG_UTF8\*(C'\fR or \f(CW\*(C`FLAG_RAW\*(C'\fR
flags will be set, even if neither was present in the constructor, as in this
case the library will attempt to detect if the current locale is \s-1UTF\-8\s0 aware
or not.
.SS "get_canonflags"
.IX Subsection "get_canonflags"
.SS "set_canonflags"
.IX Subsection "set_canonflags"
.Vb 1
\&   $canonflags = $tk\->get_canonflags
\&
\&   $tk\->set_canonflags( $newcanonflags )
.Ve
.PP
Accessor and mutator for the canonicalisation flags.
.SS "get_waittime"
.IX Subsection "get_waittime"
.SS "set_waittime"
.IX Subsection "set_waittime"
.Vb 1
\&   $msec = $tk\->get_waittime
\&
\&   $tk\->set_waittime( $msec )
.Ve
.PP
Accessor and mutator for the maximum wait time in miliseconds. The underlying
\&\f(CW\*(C`libtermkey\*(C'\fR library will have specified a default value when the object was
constructed.
.SS "get_buffer_remaining"
.IX Subsection "get_buffer_remaining"
.Vb 1
\&   $bytes = $tk\->get_buffer_remaining
.Ve
.PP
Accessor returning the number of bytes of buffer space remaining in the
buffer; the space in which \f(CW\*(C`push_bytes\*(C'\fR can write.
.SS "get_buffer_size"
.IX Subsection "get_buffer_size"
.SS "set_buffer_size"
.IX Subsection "set_buffer_size"
.Vb 1
\&   $bytes = $tk\->get_buffer_size
\&
\&   $tk\->set_buffer_size( $size )
.Ve
.PP
Accessor and mutator to for the total buffer size to store pending bytes. If
the underlying \f(CWtermkey_set_buffer_size(3)\fR call fails, the
\&\f(CW\*(C`set_buffer_size\*(C'\fR method will throw an exception.
.SS "getkey"
.IX Subsection "getkey"
.Vb 1
\&   $res = $tk\->getkey( $key )
.Ve
.PP
Attempt to retrieve a single keypress event from the buffer, and put it in
\&\f(CW$key\fR. If successful, will return \f(CW\*(C`RES_KEY\*(C'\fR to indicate that the \f(CW$key\fR
structure now contains a new keypress event. If \f(CW$key\fR is an undefined lvalue
(such as a new scalar variable) it will be initialised to contain a new key
structure.
.PP
If nothing is in the buffer it will return \f(CW\*(C`RES_NONE\*(C'\fR. If the buffer contains
a partial keypress event which does not yet contain all the bytes required, it
will return \f(CW\*(C`RES_AGAIN\*(C'\fR (see above section about multibyte events). If no
events are ready and the input stream is now closed, will return \f(CW\*(C`RES_EOF\*(C'\fR.
.PP
This method will not block, nor will it perform any \s-1IO\s0 on the underlying file
descriptor. For a normal blocking read, see \f(CW\*(C`waitkey()\*(C'\fR.
.SS "getkey_force"
.IX Subsection "getkey_force"
.Vb 1
\&   $res = $tk\->getkey_force( $key )
.Ve
.PP
Similar to \f(CW\*(C`getkey()\*(C'\fR, but will not return \f(CW\*(C`RES_AGAIN\*(C'\fR if a partial match
was found. Instead, it will force an interpretation of the bytes, even if this
means interpreting the start of an \f(CW\*(C`<Esc>\*(C'\fR\-prefixed multibyte sequence as
a literal \f(CW\*(C`Escape\*(C'\fR key followed by normal letters. If \f(CW$key\fR is an undefined
lvalue (such as a new scalar variable) it will be initialised to contain a new
key structure.
.PP
This method will not block, nor will it perform any \s-1IO\s0 on the underlying file
descriptor. For a normal blocking read, see \f(CW\*(C`waitkey()\*(C'\fR.
.SS "waitkey"
.IX Subsection "waitkey"
.Vb 1
\&   $res = $tk\->waitkey( $key )
.Ve
.PP
Attempt to retrieve a single keypress event from the buffer, or block until
one is available. If successful, will return \f(CW\*(C`RES_KEY\*(C'\fR to indicate that the
\&\f(CW$key\fR structure now contains a new keypress event. If an \s-1IO\s0 error occurs it
will return \f(CW\*(C`RES_ERROR\*(C'\fR, and if the input stream is now closed it will return
\&\f(CW\*(C`RES_EOF\*(C'\fR.
.PP
If \f(CW$key\fR is an undefined lvalue (such as a new scalar variable) it will be
initialised to contain a new key structure.
.SS "advisereadable"
.IX Subsection "advisereadable"
.Vb 1
\&   $res = $tk\->advisereadable
.Ve
.PP
Inform the underlying library that new input may be available on the
underlying file descriptor and so it should call \f(CW\*(C`read()\*(C'\fR to obtain it.
Will return \f(CW\*(C`RES_AGAIN\*(C'\fR if it read at least one more byte, \f(CW\*(C`RES_NONE\*(C'\fR if no
more input was found, or \f(CW\*(C`RES_ERROR\*(C'\fR if an \s-1IO\s0 error occurs.
.PP
Normally this method would only be used in programs that want to use
\&\f(CW\*(C`Term::TermKey\*(C'\fR asynchronously; see the \s-1EXAMPLES\s0 section. This method
gracefully handles an \f(CW\*(C`EAGAIN\*(C'\fR error from the underlying \f(CW\*(C`read()\*(C'\fR syscall.
.SS "push_bytes"
.IX Subsection "push_bytes"
.Vb 1
\&   $len = $tk\->push_bytes( $bytes )
.Ve
.PP
Feed more bytes into the input buffer. This is primarily useful for feeding
input into filehandle-less instances, constructed by passing \f(CW\*(C`undef\*(C'\fR or \f(CW\*(C`\-1\*(C'\fR
as the filehandle to the constructor. After calling this method, these bytes
will be available to read as keypresses by the \f(CW\*(C`getkey\*(C'\fR method.
.SS "get_keyname"
.IX Subsection "get_keyname"
.Vb 1
\&   $str = $tk\->get_keyname( $sym )
.Ve
.PP
Returns the name of a key sym, such as returned by
\&\f(CW\*(C`Term::TermKey::Key\->sym()\*(C'\fR.
.SS "keyname2sym"
.IX Subsection "keyname2sym"
.Vb 1
\&   $sym = $tk\->keyname2sym( $keyname )
.Ve
.PP
Look up the sym for a named key. The result of this method call can be
compared directly against the value returned by
\&\f(CW\*(C`Term::TermKey::Key\->sym()\*(C'\fR. Because this method has to perform a linear
search of key names, it is best called rarely, perhaps during program
initialisation, and the result stored for easier comparisons during runtime.
.SS "interpret_unknown_csi"
.IX Subsection "interpret_unknown_csi"
.Vb 1
\&   ( $cmd, @args ) = $tk\->interpret_unknown_csi( $key )
.Ve
.PP
If \f(CW$key\fR contains an unknown \s-1CSI\s0 event then its command and arguments are
returned in a list. \f(CW$cmd\fR will be a string of 1 to 3 characters long,
containing the initial and intermediate characters if present, followed by the
main command character. \f(CW@args\fR will contain the numerical arguments, where
missing arguments are replaced by \-1. If \f(CW$key\fR does not contain an unknown
\&\s-1CSI\s0 event then an empty list is returned.
.PP
Note that this method needs to be called immediately after \f(CW\*(C`getkey\*(C'\fR or
\&\f(CW\*(C`waitkey\*(C'\fR, or at least, before calling either of those methods again. The
actual \s-1CSI\s0 sequence is retained in the \fIlibtermkey\fR buffer, and only
retrieved by this method call. Calling \f(CW\*(C`getkey\*(C'\fR or \f(CW\*(C`waitkey\*(C'\fR again may
overwrite that buffer.
.SS "format_key"
.IX Subsection "format_key"
.Vb 1
\&   $str = $tk\->format_key( $key, $format )
.Ve
.PP
Return a string representation of the keypress event in \f(CW$key\fR, following the
flags given. See the descriptions of the flags, below, for more detail.
.PP
This may be useful for matching keypress events against keybindings stored in
a hash. See \s-1EXAMPLES\s0 section for more detail.
.SS "parse_key"
.IX Subsection "parse_key"
.Vb 1
\&   $key = $tk\->parse_key( $str, $format )
.Ve
.PP
Return a keypress event by parsing the string representation in \f(CW$str\fR,
following the flags given. This method is an inverse of \f(CW\*(C`format_key\*(C'\fR.
.PP
This may be useful for parsing entries from a configuration file or similar.
.SS "parse_key_at_pos"
.IX Subsection "parse_key_at_pos"
.Vb 1
\&   $key = $tk\->parse_key_at_pos( $str, $format )
.Ve
.PP
Return a keypress event by parsing the string representation in a region of
\&\f(CW$str\fR, following the flags given.
.PP
Where \f(CW\*(C`parse_key\*(C'\fR will start at the beginning of the string and requires the
entire input to be consumed, this method will start at the current \f(CW\*(C`pos()\*(C'\fR
position in \f(CW$str\fR (or at the beginning of the string if none is yet set),
and after a successful parse, will update it to the end of the matched
section. This position does not have to be at the end of the string. \f(CW$str\fR
must therefore be a real scalar variable, and not a string literal.
.PP
This may be useful for incremental parsing of configuration or other data, out
of a larger string.
.SS "keycmp"
.IX Subsection "keycmp"
.Vb 1
\&   $cmp = $tk\->keycmp( $key1, $key2 )
.Ve
.PP
Compares the two given keypress events, returning a number less than, equal
to, or greater than zero, depending on the ordering. Keys are ordered first by
type (unicode, keysym, function, mouse), then by value within that type, then
finally by modifier bits.
.PP
This may be useful in \f(CW\*(C`sort\*(C'\fR expressions:
.PP
.Vb 1
\& my @sorted_keys = sort { $tk\->keycmp( $a, $b ) } @keys;
.Ve
.SH "KEY OBJECTS"
.IX Header "KEY OBJECTS"
The \f(CW\*(C`Term::TermKey::Key\*(C'\fR subclass is used to store a single keypress event.
Objects in this class cannot be changed by perl code. \f(CW\*(C`getkey()\*(C'\fR,
\&\f(CW\*(C`getkey_force()\*(C'\fR or \f(CW\*(C`waitkey()\*(C'\fR will overwrite the contents of the structure
with a new value.
.PP
Keys cannot be constructed, but \f(CW\*(C`getkey()\*(C'\fR, \f(CW\*(C`getkey_force()\*(C'\fR or \f(CW\*(C`waitkey()\*(C'\fR
will place a new key structure in the \f(CW$key\fR variable if it is undefined when
they are called. \f(CW\*(C`parse_key()\*(C'\fR and \f(CW\*(C`parse_key_at_pos()\*(C'\fR will return new
keys.
.SS "type"
.IX Subsection "type"
.Vb 1
\&   $key\->type
.Ve
.PP
The type of event. One of \f(CW\*(C`TYPE_UNICODE\*(C'\fR, \f(CW\*(C`TYPE_FUNCTION\*(C'\fR, \f(CW\*(C`TYPE_KEYSYM\*(C'\fR,
\&\f(CW\*(C`TYPE_MOUSE\*(C'\fR, \f(CW\*(C`TYPE_POSITION\*(C'\fR, \f(CW\*(C`TYPE_MODEREPORT\*(C'\fR, \f(CW\*(C`TYPE_UNKNOWN_CSI\*(C'\fR.
.SS "type_is_..."
.IX Subsection "type_is_..."
.Vb 1
\&   $key\->type_is_unicode
\&
\&   $key\->type_is_function
\&
\&   $key\->type_is_keysym
\&
\&   $key\->type_is_mouse
\&
\&   $key\->type_is_position
\&
\&   $key\->type_is_modereport
\&
\&   $key\->type_is_unknown_csi
.Ve
.PP
Shortcuts which return a boolean.
.SS "codepoint"
.IX Subsection "codepoint"
.Vb 1
\&   $key\->codepoint
.Ve
.PP
The Unicode codepoint number for \f(CW\*(C`TYPE_UNICODE\*(C'\fR, or 0 otherwise.
.SS "number"
.IX Subsection "number"
.Vb 1
\&   $key\->number
.Ve
.PP
The function key number for \f(CW\*(C`TYPE_FUNCTION\*(C'\fR, or 0 otherwise.
.SS "sym"
.IX Subsection "sym"
.Vb 1
\&   $key\->sym
.Ve
.PP
The key symbol number for \f(CW\*(C`TYPE_KEYSYM\*(C'\fR, or 0 otherwise. This can be passed
to \f(CW\*(C`Term::TermKey\->get_keyname()\*(C'\fR, or compared to a result earlier
obtained from \f(CW\*(C`Term::TermKey\->keyname2sym()\*(C'\fR.
.SS "modifiers"
.IX Subsection "modifiers"
.Vb 1
\&   $key\->modifiers
.Ve
.PP
The modifier bitmask. Can be compared against the \f(CW\*(C`KEYMOD_*\*(C'\fR constants.
.SS "modifier_..."
.IX Subsection "modifier_..."
.Vb 1
\&   $key\->modifier_shift
\&
\&   $key\->modifier_alt
\&
\&   $key\->modifier_ctrl
.Ve
.PP
Shortcuts which return a boolean if the appropriate modifier is present.
.SS "utf8"
.IX Subsection "utf8"
.Vb 1
\&   $key\->utf8
.Ve
.PP
A string representation of the given Unicode codepoint. If the underlying
\&\f(CW\*(C`termkey\*(C'\fR library is in \s-1UTF\-8\s0 mode then this will be a \s-1UTF\-8\s0 string. If it is
in raw mode, then this will be a single raw byte.
.SS "mouseev"
.IX Subsection "mouseev"
.SS "button"
.IX Subsection "button"
.Vb 1
\&   $key\->mouseev
\&
\&   $key\->button
.Ve
.PP
The details of a mouse event for \f(CW\*(C`TYPE_MOUSE\*(C'\fR, or \f(CW\*(C`undef\*(C'\fR for other types of
event.
.SS "line"
.IX Subsection "line"
.SS "col"
.IX Subsection "col"
.Vb 1
\&   $key\->line
\&
\&   $key\->col
.Ve
.PP
The details of a mouse or position event, or \f(CW\*(C`undef\*(C'\fR for other types of
event.
.SS "termkey"
.IX Subsection "termkey"
.Vb 1
\&   $key\->termkey
.Ve
.PP
Return the underlying \f(CW\*(C`Term::TermKey\*(C'\fR object this key was retrieved from.
.SS "format"
.IX Subsection "format"
.Vb 1
\&   $str = $key\->format( $format )
.Ve
.PP
Returns a string representation of the keypress event, identically to calling
\&\f(CW\*(C`format_key\*(C'\fR on the underlying \f(CW\*(C`Term::TermKey\*(C'\fR object.
.SH "EXPORTED CONSTANTS"
.IX Header "EXPORTED CONSTANTS"
The following constant names are all derived from the underlying \f(CW\*(C`libtermkey\*(C'\fR
library. For more detail see the documentation on the library.
.PP
These constants are possible values of \f(CW\*(C`$key\->type\*(C'\fR
.ie n .IP """TYPE_UNICODE""" 4
.el .IP "\f(CWTYPE_UNICODE\fR" 4
.IX Item "TYPE_UNICODE"
a Unicode codepoint
.ie n .IP """TYPE_FUNCTION""" 4
.el .IP "\f(CWTYPE_FUNCTION\fR" 4
.IX Item "TYPE_FUNCTION"
a numbered function key
.ie n .IP """TYPE_KEYSYM""" 4
.el .IP "\f(CWTYPE_KEYSYM\fR" 4
.IX Item "TYPE_KEYSYM"
a symbolic key
.ie n .IP """TYPE_MOUSE""" 4
.el .IP "\f(CWTYPE_MOUSE\fR" 4
.IX Item "TYPE_MOUSE"
a mouse movement or button press or release
.ie n .IP """TYPE_POSITION""" 4
.el .IP "\f(CWTYPE_POSITION\fR" 4
.IX Item "TYPE_POSITION"
a cursor position report
.ie n .IP """TYPE_MODEREPORT""" 4
.el .IP "\f(CWTYPE_MODEREPORT\fR" 4
.IX Item "TYPE_MODEREPORT"
an \s-1ANSI\s0 or \s-1DEC\s0 mode report
.ie n .IP """TYPE_UNKNOWN_CSI""" 4
.el .IP "\f(CWTYPE_UNKNOWN_CSI\fR" 4
.IX Item "TYPE_UNKNOWN_CSI"
an unrecognised \s-1CSI\s0 sequence
.PP
These constants are result values from \f(CW\*(C`getkey()\*(C'\fR, \f(CW\*(C`getkey_force()\*(C'\fR,
\&\f(CW\*(C`waitkey()\*(C'\fR or \f(CW\*(C`advisereadable()\*(C'\fR
.ie n .IP """RES_NONE""" 4
.el .IP "\f(CWRES_NONE\fR" 4
.IX Item "RES_NONE"
No key event is ready.
.ie n .IP """RES_KEY""" 4
.el .IP "\f(CWRES_KEY\fR" 4
.IX Item "RES_KEY"
A key event has been provided.
.ie n .IP """RES_EOF""" 4
.el .IP "\f(CWRES_EOF\fR" 4
.IX Item "RES_EOF"
No key events are ready and the terminal has been closed, so no more will
arrive.
.ie n .IP """RES_AGAIN""" 4
.el .IP "\f(CWRES_AGAIN\fR" 4
.IX Item "RES_AGAIN"
No key event is ready yet, but a partial one has been found. This is only
returned by \f(CW\*(C`getkey()\*(C'\fR. To obtain the partial result even if it never
completes, call \f(CW\*(C`getkey_force()\*(C'\fR.
.ie n .IP """RES_ERROR""" 4
.el .IP "\f(CWRES_ERROR\fR" 4
.IX Item "RES_ERROR"
Returned by \f(CW\*(C`waitkey\*(C'\fR or \f(CW\*(C`advisereadable\*(C'\fR if an \s-1IO\s0 error occurs while trying
to read another key event.
.PP
These constants are key modifier masks for \f(CW\*(C`$key\->modifiers\*(C'\fR
.ie n .IP """KEYMOD_SHIFT""" 4
.el .IP "\f(CWKEYMOD_SHIFT\fR" 4
.IX Item "KEYMOD_SHIFT"
.PD 0
.ie n .IP """KEYMOD_ALT""" 4
.el .IP "\f(CWKEYMOD_ALT\fR" 4
.IX Item "KEYMOD_ALT"
.ie n .IP """KEYMOD_CTRL""" 4
.el .IP "\f(CWKEYMOD_CTRL\fR" 4
.IX Item "KEYMOD_CTRL"
.PD
Should be obvious ;)
.PP
These constants are types of mouse event which may be returned by
\&\f(CW\*(C`$key\->mouseev\*(C'\fR or \f(CW\*(C`interpret_mouse\*(C'\fR:
.ie n .IP """MOUSE_UNKNOWN""" 4
.el .IP "\f(CWMOUSE_UNKNOWN\fR" 4
.IX Item "MOUSE_UNKNOWN"
The type of mouse event was not recognised
.ie n .IP """MOUSE_PRESS""" 4
.el .IP "\f(CWMOUSE_PRESS\fR" 4
.IX Item "MOUSE_PRESS"
The event reports a mouse button being pressed
.ie n .IP """MOUSE_DRAG""" 4
.el .IP "\f(CWMOUSE_DRAG\fR" 4
.IX Item "MOUSE_DRAG"
The event reports the mouse being moved while a button is held down
.ie n .IP """MOUSE_RELEASE""" 4
.el .IP "\f(CWMOUSE_RELEASE\fR" 4
.IX Item "MOUSE_RELEASE"
The event reports the mouse buttons being released, or the mouse moved without
a button held.
.PP
These constants are flags for the constructor, \f(CW\*(C`Term::TermKey\->new\*(C'\fR
.ie n .IP """FLAG_NOINTERPRET""" 4
.el .IP "\f(CWFLAG_NOINTERPRET\fR" 4
.IX Item "FLAG_NOINTERPRET"
Do not attempt to interpret C0 codes into keysyms (ie. \f(CW\*(C`Backspace\*(C'\fR, \f(CW\*(C`Tab\*(C'\fR,
\&\f(CW\*(C`Enter\*(C'\fR, \f(CW\*(C`Escape\*(C'\fR). Instead report them as plain \f(CW\*(C`Ctrl\-letter\*(C'\fR events.
.ie n .IP """FLAG_CONVERTKP""" 4
.el .IP "\f(CWFLAG_CONVERTKP\fR" 4
.IX Item "FLAG_CONVERTKP"
Convert xterm's alternate keypad symbols into the plain \s-1ASCII\s0 codes they would
represent.
.ie n .IP """FLAG_RAW""" 4
.el .IP "\f(CWFLAG_RAW\fR" 4
.IX Item "FLAG_RAW"
Ignore locale settings; do not attempt to recombine \s-1UTF\-8\s0 sequences. Instead
report only raw values.
.ie n .IP """FLAG_UTF8""" 4
.el .IP "\f(CWFLAG_UTF8\fR" 4
.IX Item "FLAG_UTF8"
Ignore locale settings; force \s-1UTF\-8\s0 recombining on.
.ie n .IP """FLAG_NOTERMIOS""" 4
.el .IP "\f(CWFLAG_NOTERMIOS\fR" 4
.IX Item "FLAG_NOTERMIOS"
Even if the terminal file descriptor represents a \s-1TTY\s0 device, do not call the
\&\f(CW\*(C`tcsetattr()\*(C'\fR \f(CW\*(C`termios\*(C'\fR function on it to set in canonical input mode.
.ie n .IP """FLAG_SPACESYMBOL""" 4
.el .IP "\f(CWFLAG_SPACESYMBOL\fR" 4
.IX Item "FLAG_SPACESYMBOL"
Sets the \f(CW\*(C`CANON_SPACESYMBOL\*(C'\fR canonicalisation flag. See below.
.ie n .IP """FLAG_CTRLC""" 4
.el .IP "\f(CWFLAG_CTRLC\fR" 4
.IX Item "FLAG_CTRLC"
Disable the \f(CW\*(C`SIGINT\*(C'\fR behaviour of the \f(CW\*(C`Ctrl\-C\*(C'\fR key, allowing it to be read
as a modified Unicode keypress.
.ie n .IP """FLAG_EINTR""" 4
.el .IP "\f(CWFLAG_EINTR\fR" 4
.IX Item "FLAG_EINTR"
Disable retry on signal interrupt; instead report it as an error with
\&\f(CW\*(C`RES_ERROR\*(C'\fR and \f(CW$!\fR set to \f(CW\*(C`EINTR\*(C'\fR. Without this flag, \s-1IO\s0 operations will
be retried if interrupted.
.PP
These constants are canonicalisation flags for \f(CW\*(C`set_canonflags\*(C'\fR and
\&\f(CW\*(C`get_canonflags\*(C'\fR
.ie n .IP """CANON_SPACESYMBOL""" 4
.el .IP "\f(CWCANON_SPACESYMBOL\fR" 4
.IX Item "CANON_SPACESYMBOL"
With this flag set, the Space key will appear as a \f(CW\*(C`TYPE_KEYSYM\*(C'\fR key event
whose symname is \f(CW"Space"\fR. Without this flag, it appears as a normal
\&\f(CW\*(C`TYPE_UNICODE\*(C'\fR character.
.ie n .IP """CANON_DELBS""" 4
.el .IP "\f(CWCANON_DELBS\fR" 4
.IX Item "CANON_DELBS"
With this flag set, the \s-1ASCII\s0 \f(CW\*(C`DEL\*(C'\fR byte is interpreted as the \f(CW"Backspace"\fR
keysym, rather than \f(CW"DEL"\fR. This flag does not affect the interpretation of
\&\s-1ASCII\s0 \f(CW\*(C`BS\*(C'\fR, which is always represented as \f(CW"Backspace"\fR.
.PP
These constants are flags to \f(CW\*(C`format_key\*(C'\fR
.ie n .IP """FORMAT_LONGMOD""" 4
.el .IP "\f(CWFORMAT_LONGMOD\fR" 4
.IX Item "FORMAT_LONGMOD"
Print full modifier names e.g. \f(CW\*(C`Shift\-\*(C'\fR instead of abbreviating to \f(CW\*(C`S\-\*(C'\fR.
.ie n .IP """FORMAT_CARETCTRL""" 4
.el .IP "\f(CWFORMAT_CARETCTRL\fR" 4
.IX Item "FORMAT_CARETCTRL"
If the only modifier is \f(CW\*(C`Ctrl\*(C'\fR on a plain character, render it as \f(CW\*(C`^X\*(C'\fR.
.ie n .IP """FORMAT_ALTISMETA""" 4
.el .IP "\f(CWFORMAT_ALTISMETA\fR" 4
.IX Item "FORMAT_ALTISMETA"
Use the name \f(CW\*(C`Meta\*(C'\fR or the letter \f(CW\*(C`M\*(C'\fR instead of \f(CW\*(C`Alt\*(C'\fR or \f(CW\*(C`A\*(C'\fR.
.ie n .IP """FORMAT_WRAPBRACKET""" 4
.el .IP "\f(CWFORMAT_WRAPBRACKET\fR" 4
.IX Item "FORMAT_WRAPBRACKET"
If the key event is a special key instead of unmodified Unicode, wrap it in
\&\f(CW\*(C`<brackets>\*(C'\fR.
.ie n .IP """FORMAT_MOUSE_POS""" 4
.el .IP "\f(CWFORMAT_MOUSE_POS\fR" 4
.IX Item "FORMAT_MOUSE_POS"
If the event is a mouse event, also include the cursor position; rendered as
\&\f(CW\*(C`@ ($col,$line)\*(C'\fR
.ie n .IP """FORMAT_VIM""" 4
.el .IP "\f(CWFORMAT_VIM\fR" 4
.IX Item "FORMAT_VIM"
Shortcut to \f(CW\*(C`FORMAT_ALTISMETA|FORMAT_WRAPBRACKET\*(C'\fR; which gives an output
close to the format the \fIvim\fR editor uses.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.ie n .SS "A simple print\-until\-""Ctrl\-C"" loop"
.el .SS "A simple print\-until\-\f(CWCtrl\-C\fP loop"
.IX Subsection "A simple print-until-Ctrl-C loop"
This program just prints every keypress until the user presses \f(CW\*(C`Ctrl\-C\*(C'\fR.
.PP
.Vb 1
\& use Term::TermKey qw( FLAG_UTF8 RES_EOF FORMAT_VIM );
\& 
\& my $tk = Term::TermKey\->new(\e*STDIN);
\& 
\& # ensure perl and libtermkey agree on Unicode handling
\& binmode( STDOUT, ":encoding(UTF\-8)" ) if $tk\->get_flags & FLAG_UTF8;
\& 
\& while( ( my $ret = $tk\->waitkey( my $key ) ) != RES_EOF ) {
\&    print "Got key: ".$tk\->format_key( $key, FORMAT_VIM )."\en";
\& }
.Ve
.SS "Configuration of custom keypresses"
.IX Subsection "Configuration of custom keypresses"
Because \f(CW\*(C`format_key()\*(C'\fR yields a plain string representation of a keypress it
can be used as a hash key to look up a \*(L"handler\*(R" routine for the key.
.PP
The following implements a simple line input program, though obviously lacking
many features in a true line editor like \fIreadline\fR.
.PP
.Vb 1
\& use Term::TermKey qw( FLAG_UTF8 RES_EOF FORMAT_LONGMOD );
\& 
\& my $tk = Term::TermKey\->new(\e*STDIN);
\& 
\& # ensure perl and libtermkey agree on Unicode handling
\& binmode( STDOUT, ":encoding(UTF\-8)" ) if $tk\->get_flags & FLAG_UTF8;
\&
\& my $line = "";
\&
\& $| = 1;
\&
\& my %key_handlers = (
\&    "Enter"  => sub { 
\&       print "\enThe line is: $line\en";
\&       $line = "";
\&    },
\&
\&    "Backspace" => sub {
\&       return unless length $line;
\&       substr( $line, \-1, 1 ) = "";
\&       print "\ecH \ecH"; # erase it
\&    },
\&
\&    # other handlers ...
\& );
\& 
\& while( ( my $ret = $tk\->waitkey( my $key ) ) != RES_EOF ) {
\&    my $handler = $key_handlers{ $tk\->format_key( $key, FORMAT_LONGMOD ) };
\&    if( $handler ) {
\&       $handler\->( $key );
\&    }
\&    elsif( $key\->type_is_unicode and !$key\->modifiers ) {
\&       my $char = $key\->utf8;
\&
\&       $line .= $char;
\&       print $char;
\&    }
\& }
.Ve
.SS "Asynchronous operation"
.IX Subsection "Asynchronous operation"
Because the \f(CW\*(C`getkey()\*(C'\fR method performs no \s-1IO\s0 itself, it can be combined with
the \f(CW\*(C`advisereadable()\*(C'\fR method in an asynchronous program.
.PP
.Vb 4
\& use IO::Select;
\& use Term::TermKey qw(
\&    FLAG_UTF8 RES_KEY RES_AGAIN RES_EOF FORMAT_VIM
\& );
\& 
\& my $select = IO::Select\->new();
\& 
\& my $tk = Term::TermKey\->new(\e*STDIN);
\& $select\->add(\e*STDIN);
\& 
\& # ensure perl and libtermkey agree on Unicode handling
\& binmode( STDOUT, ":encoding(UTF\-8)" ) if $tk\->get_flags & FLAG_UTF8;
\& 
\& sub on_key
\& {
\&    my ( $tk, $key ) = @_;
\& 
\&    print "You pressed " . $tk\->format_key( $key, FORMAT_VIM ) . "\en";
\& }
\& 
\& my $again = 0;
\& 
\& while(1) {
\&    my $timeout = $again ? $tk\->get_waittime/1000 : undef;
\&    my @ready = $select\->can_read($timeout);
\& 
\&    if( !@ready ) {
\&       my $ret;
\&       while( ( $ret = $tk\->getkey_force( my $key ) ) == RES_KEY ) {
\&          on_key( $tk, $key );
\&       }
\&    }
\& 
\&    while( my $fh = shift @ready ) {
\&       if( $fh == \e*STDIN ) {
\&          $tk\->advisereadable;
\&          my $ret;
\&          while( ( $ret = $tk\->getkey( my $key ) ) == RES_KEY ) {
\&             on_key( $tk, $key );
\&          }
\& 
\&          $again = ( $ret == RES_AGAIN );
\&          exit if $ret == RES_EOF;
\&       }
\&       # Deal with other filehandles here
\&    }
\& }
.Ve
.PP
There may also be more appropriate modules on \s-1CPAN\s0 for particular event
frameworks; see the \f(CW\*(C`SEE ALSO\*(C'\fR section below.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
<http://www.leonerd.org.uk/code/libtermkey/> \- \f(CW\*(C`libtermkey\*(C'\fR home page
.IP "\(bu" 4
Term::TermKey::Async \- terminal key input using \f(CW\*(C`libtermkey\*(C'\fR with
IO::Async
.IP "\(bu" 4
POE::Wheel::TermKey \- terminal key input using \f(CW\*(C`libtermkey\*(C'\fR with \s-1POE\s0
.IP "\(bu" 4
AnyEvent::TermKey \- terminal key input using \f(CW\*(C`libtermkey\*(C'\fR with AnyEvent
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>