Usage of timeoutlen and ttimeoutlen

Question

I was trying to set a timeout length to apply to:

• Key combination presses (for example, pressing gh in netrw); and
• Exiting modes (for example, zero delay when exiting visual mode).

Here is a portion of what the docs say in :h timeoutlen as an example:

   :set timeout timeoutlen=3000 ttimeoutlen=100
    (time out on mapping after three seconds, time out on key codes after
    a tenth of a second).

I still have a hard time understanding what this referring to. What actually would be the difference between the two? For example if I pressed g then h for the gh combination in netrw which one(s) would apply to that? What about exiting the visual mode? Which would apply to that?

Answer 1

timeout and timeoutlen apply to mappings, such as netrw's gh.

These are pretty straightforward: if you increase the length of timeoutlen, then Vim will wait for longer after each keystroke of the mapping before aborting it and carrying out the behaviour of the keys typed so far. If you instead unset timeout, then Vim will wait forever for you to either type the complete mapping or type something which doesn't match any of your mappings.

ttimeout and ttimeoutlen apply to key codes.

A common example of something sends key codes is the arrow keys. In the terminal presses of the arrow keys are generally represented by sequences of characters. You can see what (Vim thinks) your terminal is sending when you press e.g. the left arrow key by executing the command:

:set <left>?

In my terminal, when I run the above, Vim outputs the following:

t_kl <Left>     ^[O*D

This means that what my terminal sends to Vim when I press the arrow key is the sequences of characters: EscapeO*D.

^{(^[ is a plain-text representation of the ESC character)}

The only way that Vim can distinguish these sequences from actual keypresses is the speed with which it receives them, and you configure this with the ttimeout and ttimeoutlen settings.

Thus, if you set ttimeoutlen to a sufficiently large value (try 5000: five seconds) then you can move your cursor to the left by literally typing EscapeO*D on your keyboard.

However, this also means that if you press Escape in visual mode, then Vim will wait 5 seconds to whether you actually pressed Escape (to exit visual mode) or in fact just pressed Left in an extremely slow terminal.

Generally, you want to set timeout and timeoutlen according to how quickly you generally type mappings, and you should set ttimeoutlen to a pretty small value: defaults.vim sets this to 100 milliseconds, but you can probably go a fair bit shorter than this without unwanted consequences.

Longer values of ttimeoutlen are only required for "slow terminals or very busy systems" when key codes are timing out, but as processor and network speeds increase this is less and less of an issue in practice.

Answer 2

The timeouts are applicable when you have entered a key and its ambiguous whether a mapping will come next or if there is a choice for the next key due to multiple mappings starting with the same character.

If I've mapped ab and ac to something and I press a Vim doesn't know whether I want to enter only a or ab or ac so the timeout, if set, will be triggered in this scenario if you wait long enough.

Without timeouts enabled then a scenario like this is handled like so, per the Vim help docs:

If both options are off, Vim will wait until either the complete mapping or key sequence has been received, or it is clear that there is no mapping or key sequence for the received characters.

So specifically to your first question, the timeout will come into play only after the g. You will, of course, lose the opportunity to execute a mapped sequence if you let the timeout expire.

(Regarding the second question, about visual mode, I'm not sure what you mean. Exiting visual mode, e.g. with <esc>, happens immediately. If I'm missing a scenario please clarify.)

Note that keycode timeout (enabled unless both 'timeout' and 'ttimeout' are off) is something you are unlikely to encounter very often, if at all. About the only scenario that I've seen come up (rarely) is if you have an Insert mode mapping that includes <esc> (then you must also have setting 'esckeys' enabled).

Based on all this, you mostly just need to ask yourself if you want timeouts for mapped keys, ie. those created with the :map family of commands. If so the easiest thing to do then is probably to turn 'timeout' and 'ttimeout' on, set 'ttimeoutlen' to a negative number and then you'll control both timeout durations with 'timeoutlen'.

Update: Matt's answer better addresses the key code issue IF your implementation uses keycodes (admittedly the more common case). But for some gvim versions, like Windows, they aren't used and you'll only deal with associated timeouts with rare scenarios like the one mentioned above. You can see what you have with :set termcap. They'll be under the --- Terminal keys --- header.