19

The vim manual says we can use timeoutlen to specify the timeout length of mapped key sequences and can use ttimeoutlen to specify the timeout length of key codes:

A useful setting would be

:set timeout timeoutlen=3000 ttimeoutlen=100

(time out on mapping after three seconds, time out on key codes after a tenth of a second).

What are key codes? How are they different from mapped key sequences?

I know an example of a mapped key sequence is jk from the below mapping:

inoremap jk <esc>

In this example, when I'm in insert mode and type j, vim will wait timeoutlen milliseconds for me to press k before deciding what my intent is.

But what is a key code and how does ttimeoutlen affect it? Thanks you.

21

In short:

  • keycodes is a way to represent a key
  • A mapped key sequence is a succession of keycodes triggering an action

Now I think that your question is more about the difference between timeoutlen and ttimeoutlen instead of the difference between a mapped key sequence and a key code.

My answer is based on this wikia article that you really should read because it addresses some points that I didn't mention here to keep the answer as short and clear as possible.


First let's talk about key codes. The article defines two types of keycodes:

  • Terminal keycodes:

    They are how the terminal represents a key.

    These codes that are sent by the terminal to Vim.

    To get a list of these keycodes you should use your terminal documentation. You can also see them by typing the command cat in your terminal and typing the key you want to know the keycode. For example on my terminal the key code for ShiftF1 looks like:

    ^[[23~

  • Vim keycodes:

    They are how vim represent a key.

    Vim needs a consistent way to represent the keys because terminal's keycodes change from a terminal to another. A list of Vim keycodes is accessible at :h t_ku. The Vim keycode for ShiftF1 looks like:

    <S-F1>

Thus when I press ShiftF1 on my keyboard, the drivers and OS will let the terminal know that I pressed these keys that it will interpret as ^[[23~. The terminal will send that to Vim which will understand that it means <S-F1> and will trigger the action mapped to this key code.

We can set Vim keycodes, so if your terminal sends a keycode that Vim doesn't understand as <S-F1> for example you could use the following command. This will tell Vim when your receive the keycode ^[[24~, translate it has <S-F1>:

set <S-F1> ^[[24~

So what is a mapped key sequence?

A mapped key sequence will be a lhs of a mapping and can be Vim key codes or Terminal key codes. For example:

:nmap ^[[24~ :bn<CR>
:nmap <S-F1> :bn<CR>

The first mapping will map the terminal keycode while the second maps the Vim keycode.

Now for the difference between timeoutlen and ttimeoutlen?

  • ttimeoutlen is the time Vim will wait for the different parts of a terminal key codes (in our previous example that would be ^[ then [ then 2, etc...

    As these keycodes are sent by the terminal there should not be a delay between these input (since they are sent 'all at once' by the terminal). This is why the doc recommends a really small value for this setting.

  • timeoutlen is the time Vim will wait for the successive Vim keycodes which are entered manually by a user and thus is longer to input than a terminal keycode.

To use an example let's say that:

  • You mapped ^[[1;6B to an action
  • ^[1;6B is your terminal's keycode for ctrlshiftdown
  • ^[ is your terminal's keycode for Escape.

The behavior that you should expect:

  • If you set a large ttimeoutlen, each time you type on Escape, Vim will wait to see if you meant ^[ (i.e. Escape) or ^[1;6B (i.e. ctrlshiftdown)
  • If you set a small ttimeoutlen, you will not have a delay when you'll type Escape because Vim will know that it is a complete keycode.

And timeoutlen will act on a 'higher level', if you have the following mappings:

inoremap jj <Esc>
inoremap jk <Esc>:nohl<CR>

When you type j vim will wait timeoutlen not because the beginning of the terminal keycode for j is not complete but because it is waiting for the next Vim keycode.


I hope my explanation makes sense, note that some of the mappings I used don't make sense in a functional point of view but are here for the convenience the explanation.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.