Key notation and contexts

This page lists how a key is written in keys.bind, how a count works, which contexts exist in tt, and the two keys settings in config.toml.

Notation

Keys are written in vim notation. A plain character is one key. Everything else goes in angle brackets.

Written	Key
j, G, /, é	a character
gg, ZZ	a sequence: two keys one after the other, at most 8 keys
<Space>, <Tab>, <Esc>, <CR>, <BS>, <Del>	a named key
<Up>, <Down>, <Left>, <Right>, <Home>, <End>, <PageUp>, <PageDown>, <Insert>	more named keys
<F1> to <F12>	function keys
<C-d>	Ctrl-d
<A-x> or <M-x>	Alt-x
<S-Tab>	Shift on a named key
<C-A-x>	modifiers combine
<lt>	a literal <
<leader>r	the leader key, then r

• Names are not case sensitive. <CR>, <Enter> and <Return> are the same key, and so are <BS> and <Backspace>, <Del> and <Delete>, and <Esc> and <Escape>.
• Shift works on named keys only. Write X, not <S-x>.
• A space is not a key. Write <Space>.
• A refused key gives a message that names the part at fault: an empty string, an unclosed <, an unknown name such as <Nope>, or a ninth key.

Counts

Digits typed before a key give the command a count. 5j runs index.next 5, so the count is the first word the command receives. A key with no count passes no word.

• The digits 1 to 9 start a count, so they cannot start a binding or be the leader.
• A count typed before a key that has no binding is dropped with the key.
• In writing, digits are text and no count is typed.

Contexts

A context is the part of tt that has the focus. A key is looked up in the focused context first and then in global. writing and dialog look only in their own keys.

Context	Where it applies
global	Everywhere, as the fallback of the others.
sidebar	The tree of accounts and folders.
list	The list of messages.
reader	The message in the reader window.
writing	A line of text while you type in it, such as the command line or the search. A binding there is one key, and any other key is typed.
dialog	A window opened by a script. Global keys do nothing behind it.

A context name is lowercase letters, digits, _ and -, starting with a letter. A name that nothing uses is not an error, so a typo in a name binds a key that never fires.

The leader and the wait

Two settings are in config.toml, because the leader is needed before the scripts run:

[keys]
leader = "<Space>"
timeout_ms = 1000

• leader is the key that <leader> stands for: one key, written like any other. A digit cannot be the leader.
• timeout_ms is how long tt waits for the next key of a sequence such as gg before it runs what the keys typed so far mean. The range is 100 to 10000.

Both are in the reference of the configuration. The default keys are in keybind.lua; how to change one is on Change a key.