libtermkey
This library allows easy processing of keyboard entry from
terminal-based programs. It handles all the necessary logic to
recognise special keys, UTF-8 combining, and so on, with a simple
interface.
DEPRECATED
Note: Use of this library for new programs is discouraged. It is being
maintained for legacy purposes only. For writing new programs, please use
libtickit instead.
All of the code in this library will be migrated into
libtickit in due course; currently it is used via an internal
dependency.
It provides the following features:
- Follows terminfo for every sequence listed there, only falling back on other methods to deal with unrecognised input.
- Recognises special keys (such as arrow and function keys), including "modified" keys like Ctrl-Left.
- Recognises XTerm-style mouse position/button reporting.
- MIT licenced to allow almost all projects to use it; both Open Source and Commercial.
- Implemented in a small handfull of .c files which allows direct embedding in a larger application, if a shared library is not desired.
- Small API - just three functions are needed in simple common cases.
- Both synchronous (blocking) and asynchronous (non-blocking) APIs are supported.
- Fully conformant with my suggested terminal key representation scheme
Comparision with Terminfo
This library uses the terminfo database for the terminal type given by
$TERM as a first attempt to convert raw incoming bytes into
symbolic keypress events. If this translation fails, and the terminal type
is known to be one that uses xterm's generic CSI scheme for representing
modified keypresses (e.g. xterm), then the sequence is
interpreted according to xterm's rules. Finally, if all of these fail, the
raw bytes will be presented as they are.
Special handling for screen is made, because of the way screen
will translate some keypresses that it recognises, but passes on
everything else verbatim. The xterm rules will also apply in this case, to
cope with the case where screen is being driven by an xterm-like terminal,
ensuring all the modified keypresses can still be interpreted.
Source
Download source in tarball from:
- libtermkey-0.22.tar.gz
- changes: bugfixes for unit tests on BSD platforms
- libtermkey-0.21.1.tar.gz
- changes: internal bugfixes, valgrind neatness
- libtermkey-0.20.tar.gz
- changes: added parsing of DCS and OSC control strings
- libtermkey-0.19.tar.gz
- changes: fixed handling of Ctrl-Space, bugfix for keypad mode switching, endian fix for unicode keys (thanks jamessan)
- libtermkey-0.18.tar.gz
- changes: look for .utf8 in locale variables, C++-compatible header, don't treat Ctrl-H as Backspace, disable IEXTEN where applicable
- libtermkey-0.17.tar.gz
- changes: added TERMKEY_FORMAT_SPACEMOD, TERMKEY_FORMAT_LOWERMOD, TERMKEY_FORMAT_LOWERSPACE and TERMKEY_FORMAT_URWID shortcut; better detection of UTF-8 locales; abstract C compiler from Makefile by using $(CC).
- libtermkey-0.16.tar.gz
- changes: recognise ANSI and DEC mode reports, extract and yield real key events for unrecognised CSI sequences; added termkey_interpret_{modereport,csi}; bugfix handling of CPR vs F3.
- libtermkey-0.15b.tar.gz
- changes: recognise SGR and rxvt mouse encodings, recognise cursor position report - (0.15a includes position report bugfix; 0.15b includes 'make install' portability fix)
- libtermkey-0.14.tar.gz
- changes: added termkey_{start,stop}, termkey_is_started, ship unit tests in distribution tarball for downstream to use
- libtermkey-0.13.tar.gz
- changes: added termkey_new_abstract, termkey_{get,set}_buffer_size, use errno rather than fprintf() to stderr, optionally use libncursesw if unibilium fails
- libtermkey-0.12.tar.gz
- changes: added termkey_push_bytes, support filehandle-less (abstract) instances, many manpage improvements
- libtermkey-0.11.tar.gz
- changes: optionally use unibilium instead of curses
- libtermkey-0.10.tar.gz
- changes: added termkey_canonicalise, canonicalisation flags, fixed some compile bugs on Solaris/OS X
- libtermkey-0.9.tar.gz
- changes: added FLAG_EINTR and RES_ERROR for better control of signal handling
- libtermkey-0.8.tar.gz
- bugfixes: handle Ctrl-Space on non-Linux, gracefully ignore EINTR, handle CSI u encodings
- libtermkey-0.7.tar.gz
- changes: added termkey_strpkey and termkey_keycmp, renamed termkey_snprint_key to termkey_strfkey
- libtermkey-0.6.tar.gz
- changes: control over SIGINT behaviour, Space as Unicode
- libtermkey-0.5.tar.gz
- changes: improved libtool integration; better mouse API
- libtermkey-0.4.tar.gz
- changes: use libtool for building; preliminary mouse support
- libtermkey-0.3.tar.gz
- libtermkey-0.2.tar.gz
- libtermkey-0.1.tar.gz
The primary revision control repository is a Bazaar branch at
http://bazaar.leonerd.org.uk/c/libtermkey/.
For an overview of the API, see here.
Online versions of the manpages are available in HTML form.
Language Bindings
This is a C library, but the following bindings exist for other languages.
- Perl
- Term::TermKey
- Python
- ctypes_libtermkey