libt3key Documentation


The libt3key library provides functions for retrieving the character sequences used by terminals to represent keys pressed by the user. Although the terminfo database provides part of this information, it lacks information for the sequences returned by modern terminals/terminal emulators for many combinations of modifiers with other keys. For example, many terminal emulators provide separate character sequences for Control combined with the cursor keys, which is not stored in the terminfo database.

Many programs contain their own databases with this information. This library tries to be a database usable by many programs, such that all programs can benefit from the information collected.

libt3key is part of the Tilde Terminal Toolkit (T3).

Database format

The database is saved as a set of configuration files. The format is described in Database Format page.

How to Use

Normal use of the library would consist of calling t3_key_load_map with NULL as the term and map_name arguments, to load the best map. After loading the map of character sequences, use t3_key_get_named_node to retrieve the desired character sequences. The name argument must be one of:

optionally combined with a plus symbol and one or more of the modifier letters c[ontrol], m[eta] and s[hift] (in alphabetical order). For example, to retrieve the character sequence for Meta-Shift-right, pass the name right+ms.

Although the library provides separate character sequences for the keypad and regular cursor keys, it is a very bad idea to distinghuish between them. They should be treated as if they are the same keys as far as the behavior of the program is concerned.

Each key may have multiple character sequences associated with it. By calling t3_key_get_named_node multiple times, the second and later times with NULL as the name argument and the returned value as the first argument, all character sequences can be retrieved.