Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
973 lines (718 sloc) 36.4 KB
*fixkey.txt* Plugin to fix key codes for console Vim
*fixkey* Version 0.3.8
==============================================================================
1. Introduction |fixkey-intro|
2. Installation |fixkey-installation|
3. Terminal setup |fixkey-term-setup|
3.1 Setup xterm |fixkey-term-xterm|
3.2 Setup gnome-terminal |fixkey-term-gnome|
3.3 Setup Konsole |fixkey-term-konsole|
3.4 Setup Linux console |fixkey-term-linux|
3.5 Setup PuTTY |fixkey-term-putty|
3.6 Setup rxvt |fixkey-term-rxvt|
3.7 Setup screen |fixkey-term-screen|
3.8 Setup tmux |fixkey-term-tmux|
3.9 Terminal testing |fixkey-term-testing|
4. ChangeLog |fixkey-changelog|
5. References |fixkey-references|
6. Credits |fixkey-credits|
==============================================================================
1. Introduction *fixkey-intro*
It is surprisingly difficult to get console Vim to recognize keys outside the
normal ASCII range. This plugin aims to hide the details of the back-flips
necessary to allow console Vim to successfully take advantage of non-ASCII
keys (e.g., function keys, alt+letters, etc.).
NOTE Because most terminal emulators use ambiguous encodings for non-ASCII
keys, the only way console Vim (and therefore Fixkey) can distinguish certain
key combinations is through the use of timeouts (as configured by
'ttimeoutlen'). Key codes closer together than 'ttimeoutlen' are considered
part of a single keypress; otherwise, the codes are considered separate
keypresses. For example, on many terminals, the keypress <a-x> (Alt plus "x")
is encoded as the two-code sequence <Escape>x; unfortunately, these same two
codes are generated by pressing the <Escape> key followed by the "x" key. This
fundamental ambiguity cannot be resolved without the additional information
provided by timing the keypresses.
While the timing-based technique works for interactive keypresses, it fails
when the key codes are recorded into a macro and played back, because macros do
not retain the timing information of the original keypresses. This can cause
recorded macros to fail upon playback. For example, consider recording a macro
that contains the two keypresses <Escape> and "x". When played back, this will
be interpreted as the single keypress <a-x>.
It's worth noting that the macro ambiguity problem exists even without fixkey
(though fixkey increases the problem by teaching Vim about more of the
ambiguous keycodes sent by the terminal). For example, consider recording a
macro into register q by pressing qq, then typing the following keys, then
pressing q once more:
iSecond<Escape>OFirst<Escape>
While recording the macro, this should enter insert mode, insert the word
"Second", escape to normal mode, open a new line with "O", then enter the word
"First", leaving these lines in the buffer:
First
Second
Upon playback, however, the macro will send the three characters <Escape>OF in
rapid succession. On many terminals, this is the code for the <End> key, in
which case executing the macro via @q will result in the following:
Secondirst
Additionally, fixkey sets 'ttimeoutlen' to a fairly short value of 5
milliseconds to ensure that rapid typing of two keys won't be incorrectly
interpreted as a single keystroke. When running over a very slow connection,
this might cause Vim to occasionally mistake a multi-byte code for a single
keypress (such as <Escape>OF, for example) as multiple keypresses. To avoid
this, set 'ttimeoutlen' in .vimrc to the desired value, and fixkey will not
override it. For example, to use 50 milliseconds, place this line in .vimrc:
set ttimeoutlen=50
===============================================================================
2. Installation *fixkey-installation*
To install directly in your personal |vimfiles| directory (~/.vim under
unix or %HOMEPATH%\vimfiles under windows), unpack the downloaded archive
to yield these files: >
doc/fixkey.txt
plugin/fixkey.vim
scripts/fixkeytest.vim
Then, re-generate your help tags with Vim's |:helptags| command, e.g.: >
:helptags ~/.vim/doc
You may also install fixkey using a tool like pathogen[1] by unpacking
the downloaded archive into a bundle directory, e.g.: >
~/.vim/bundle/fixkey
[1]: https://github.com/tpope/vim-pathogen
===============================================================================
3. Terminal Setup *fixkey-term-setup*
Unfortunately, almost no terminal seems to be setup correctly out-of-the-box,
due to various combinations of problems. Many terminals are configured with
the TERM environment variable set to an incorrect value (often "xterm")
that doesn't match the actual key codes sent by the terminal. Additionally,
Vim expects non-default behavior from most terminals, particularly with
respect to mapping Alt-keys.
Therefore, in addition to installing fixkey, there may be some
terminal-specific setup required to make everything work properly, described
in the following sections.
If necessary, see |fixkey-term-testing| for methods of testing and debugging
your terminal setup.
When properly setup, a fully functioning terminal can provide the following
keys:
- Alt-lowercase letters (<M-a> - <M-z>).
- Alt-uppercase letters (<M-A> - <M-Z>), except <M-O> due to keycode
ambiguity).
- Function keys with no modifiers or combinations of shift, control, and alt:
<F1> - <F12>, <S-F1> - <S-F12>, ..., <M-C-S-F1> - <M-C-S-F12>.
*Note* not all combination of terminal and environment send all of these.
- Arrow keys with no modifiers or combinations of shift, control, and alt:
<Up>, <Down>, <Left>, <Right>, <S-Up>, <S-Down>, <S-Left>, <S-Right>, ...,
<M-C-S-Up>, <M-C-S-Down>, <M-C-S-Left>, <M-C-S-Right>.
- Home and End keys with no modifiers or combinations of shift, control, and
alt: <Home>, <End>, <S-Home>, <S-End>, ..., <M-C-S-Home>, <M-C-S-End>.
- <S-Enter> (few terminals).
- <M-Enter> (not all terminals).
Note that <C-Enter> generally seems to alias <Enter> on most terminals and is
therefore unavailable.
Note that <M-O> is generally encoded as <Escape>O, which is a prefix of
several terminal keycodes; therefore, fixkey does not attempt to configure
<M-O>.
-------------------------------------------------------------------------------
3.1 Setup xterm *fixkey-term-xterm*
There is not much additional setup for using xterm unless the xterm defaults
are changed, as fixkey configures Vim to expect the correct key codes.
However, by default, xterm toggles its fullscreen state on <M-Enter>. To
allow this key to be seen by Vim, the following two lines should be added to
your ~/.Xresources file: >
XTerm*fullscreen: never
XTerm.omitTranslation: fullscreen
For more information, see:
http://forums.opensuse.org/english/get-technical-help-here/applications/459502-how-disable-alt-enter-maximize.html
Because many terminal emulators masquerade as TERM=xterm, xterm has the
privilege of defining the "correct" keycodes for various keys.
Reserved keys (should work if environment passes them to Vim):
<M-C-F1> - <M-C-F12> (reserved for switching virtual consoles)
<M-Enter> (reserved for fullscreen xterm switching)
Inoperable keys (terminal sends no codes):
none
Aliased keys:
<C-Enter> (same as <Enter>)
-------------------------------------------------------------------------------
3.2 Setup gnome-terminal *fixkey-term-gnome*
gnome-terminal generally uses TERM=xterm (or TERM=xterm-256color), but there
are a number of differences with xterm that cannot be easily changed.
Fortunately, gnome-terminal also exports the environment variable
COLORTERM=gnome-terminal, so fixkey can detect when gnome-terminal is
masquerading as xterm and configure Vim accordingly.
However, when using ssh to connect to a remote machine, the variable COLORTERM
isn't carried to the remote machine by default, so when Vim runs on the remote
machine, the keys won't be fully correct unless COLORTERM is set in the
environment before launching the remote Vim.
When COLORTERM is not set properly, the following keys won't work properly:
<S-F1>
<S-F2>
<S-F3>
<S-F4>
<C-S-F1>
<C-S-F2>
<C-S-F3>
<C-S-F4>
<M-S-F1>
<M-S-F2>
<M-S-F3>
<M-S-F4>
<M-C-S-F1>
<M-C-S-F2>
<M-C-S-F3>
<M-C-S-F4>
Reserved keys (should work if environment passes them to Vim):
<M-C-F1> - <M-C-F12> (reserved for switching virtual consoles)
Inoperable keys (terminal sends no codes):
<F10> (reserved for menu)
<S-F10> (reserved for context menu)
<C-F1>
<C-S-Up>
<C-S-Down>
<M-C-S-Up>
<M-C-S-Down>
<S-Home> (reserved for scrollback)
<S-End> (reserved for scrollback)
<C-S-Home> (reserved for scrollback)
<C-S-End> (reserved for scrollback)
<M-S-Home> (reserved for scrollback)
<M-S-End> (reserved for scrollback)
<M-C-S-Home> (reserved for scrollback)
<M-C-S-End> (reserved for scrollback)
<M-Enter> (sends \x1b\x0a, but Vim doesn't like it)
Aliased keys:
<C-Home> (same as <Home>)
<M-Home> (same as <Home>)
<M-C-Home> (same as <Home>)
<C-End> (same as <End>)
<M-End> (same as <End>)
<M-C-End> (same as <End>)
<C-Enter> (same as <C-@>)
<S-Enter> (same as <Enter>)
-------------------------------------------------------------------------------
3.3 Setup Konsole *fixkey-term-konsole*
```````````````````````````````````````````````````````````````````````````````
Option 1: Configure Konsole to match xterm.
The KDE Konsole terminal emulator frequently masquerades as xterm via
TERM=xterm (or TERM=xterm-256color), but the key codes for <S-F1> through
<S-F4> don't match xterm.
To use TERM=xterm (or TERM=xterm-256color) with konsole, it's necessary to
change the Konsole key bindings for these keys (or live with them not working
properly).
Using Konsole 2.10.5 (from Fedora 19) as an example:
- Via the menu, visit Settings, Manage Profiles, Edit Profile, Keyboard tab.
- Highlight "Default (XFree 4)" and choose "New" to clone these default
settings as a starting point.
- Set the description (e.g., "xterm-compatible").
- Locate each of the following bindings and change "Key Combination" to have
the desired "Output" value:
Key Combination Output
F1+AnyModifier \E[1;*P
F2+AnyModifier \E[1;*Q
F3+AnyModifier \E[1;*R
F4+AnyModifier \E[1;*S
- Save this set of key bindings.
- Making sure that "xterm-compatible" is selected, choose "OK" to save the
profile to use these bindings in the future.
- Optionally, disable any Konsole shortcuts that you'd like Vim to see
(e.g., <F1>, which is normally bound to "What's This?):
- Via the menu, visit Settings | Configure Shortcuts.
- For each bound key you'd like to release, choose Custom | None to disable
the shortcut.
- Choose OK to save your settings.
- Restart all Konsole instances.
With these changes, Konsole will be xterm-compatible, both for Vim and for
other programs that use terminfo.
```````````````````````````````````````````````````````````````````````````````
Option 2: Use TERM=konsole (or TERM=konsole-256color).
Instead of masquerading as xterm, it's possible to leave Konsole's key
bindings at their default and setup the TERM environment variable to match.
- Via the Konsole menu, visit Settings, Manage Profiles, Edit Profile.
- On the General tab, choose Environment Edit.
- Change TERM=xterm to TERM=konsole (or TERM=konsole-256color).
- Save the profile and restart all Konsole instances.
```````````````````````````````````````````````````````````````````````````````
With either option:
Reserved keys (should work if environment passes them to Vim):
<S-F1> (reserved for Konsole "What's This?" help)
<C-S-F10> (reserved for Konsole menu)
<C-S-F11> (reserved for KDE shortcut)
<M-F2> (reserved for KDE "Run Command Interface")
<M-F4> (reserved for KDE windows-close shortcut)
<M-S-F2> (reserved for KDE "Run Command Interface")
<M-S-F12> (reserved for KDE "suspend compositing")
<M-C-F1> - <M-C-F12> (reserved for switching virtual consoles)
<S-Left> (reserved for Konsole "previous tab")
<S-Right> (reserved for Konsole "next tab")
<C-S-Left> (reserved for Konsole "move tab left")
<C-S-Right> (reserved for Konsole "move tab right")
Inoperable keys (terminal sends no codes):
none
Aliased keys:
<C-Enter> (same as <Enter>)
-------------------------------------------------------------------------------
3.4 Setup Linux console *fixkey-term-linux*
There is no additional setup for using the Linux text-mode console
(TERM=linux).
Inoperable keys (terminal sends no codes):
<C-F1> - <C-F12>
<S-F9>
<S-F10>
<S-F11>
<S-F12>
<C-S-F1> - <C-S-F12>
<M-F1> - <M-F12> (reserved for virtual terminal switching)
<M-C-F1> - <M-C-F12> (reserved for virtual terminal switching)
<M-C-S-F1> - <M-C-S-F12>
<M-C-S-Home>
<M-C-S-End>
<M-Up>
<M-C-S-Up>
<M-C-S-Down>
<M-Left> (reserved for "previous virtual terminal")
<M-C-S-Left>
<M-Right> (reserved for "next virtual terminal")
<M-C-S-Right>
Aliased keys:
<C-Home> (same as <Home>)
<S-Home> (same as <Home>)
<C-S-Home> (same as <Home>)
<C-End> (same as <End>)
<S-End> (same as <End>)
<C-S-End> (same as <End>)
<C-Up> (same as <Up>)
<S-Up> (same as <Up>)
<C-S-Up> (same as <Up>)
<M-C-Up> (same as <Up>)
<M-S-Up> (same as <Up>)
<C-Down> (same as <Down>)
<S-Down> (same as <Down>)
<C-S-Down> (same as <Down>)
<M-Down> (same as <Down>)
<M-C-Down> (same as <Down>)
<M-S-Down> (same as <Down>)
<C-Left> (same as <Left>)
<S-Left> (same as <Left>)
<C-S-Left> (same as <Left>)
<M-C-Left> (same as <Left>)
<M-S-Left> (same as <Left>)
<C-Right> (same as <Right>)
<S-Right> (same as <Right>)
<C-S-Right> (same as <Right>)
<M-C-Right> (same as <Right>)
<M-S-Right> (same as <Right>)
<C-Enter> (same as <Enter>)
<S-Enter> (same as <Enter>)
-------------------------------------------------------------------------------
3.5 Setup PuTTY *fixkey-term-putty*
There are a couple of ways to setup PuTTY to get reasonable functionality.
By default, PuTTY masquerades as xterm despite many keys being different from
xterm.
```````````````````````````````````````````````````````````````````````````````
Option 1: Use TERM=putty (or TERM=putty-256color).
Using PuTTY's configuration menu:
- "Connection"
- "Data"
- Set "Terminal-type string" to "putty" (or "putty-256color")
Leave the Terminal.Keyboard settings at their defaults, and fixkey will
configure Vim accordingly.
Reserved keys (should work if environment passes them to Vim):
<M-F4> (reserved to close window)
Inoperable keys (terminal sends no codes):
<C-Home>
<C-S-Home>
<M-C-Home>
<M-C-S-Home>
<C-End>
<C-S-End>
<M-C-End>
<M-C-S-End>
Aliased keys:
<C-F1> - <C-F12> (same as <F1> - <F12>)
<S-F1> - <S-F2> (same as <F11> - <F12>)
<S-F11> - <S-F12> (same as <F11> - <F12>)
<C-S-F1> - <C-S-F12> (same as <S-F1> - <S-F12>)
<M-C-F1> - <M-C-F12> (same as <M-F1> - <M-F12>)
<M-S-F1> - <M-S-F2> (same as <M-F11> - <M-F12>)
<M-S-F11> - <M-S-F12> (same as <M-F11> - <M-F12>)
<M-C-S-F1> - <M-C-S-F12> (same as <M-S-F1> - <M-S-F12>)
<S-Up> (same as <C-Up>)
<C-S-Up> (same as <C-Up>)
<M-S-Up> (same as <M-C-Up>)
<M-C-S-Up> (same as <M-C-Up>)
<S-Down> (same as <C-Down>)
<C-S-Down> (same as <C-Down>)
<M-S-Down> (same as <M-C-Down>)
<M-C-S-Down> (same as <M-C-Down>)
<S-Left> (same as <C-Left>)
<C-S-Left> (same as <C-Left>)
<M-S-Left> (same as <M-C-Left>)
<M-C-S-Left> (same as <M-C-Left>)
<S-Right> (same as <C-Right>)
<C-S-Right> (same as <C-Right>)
<M-S-Right> (same as <M-C-Right>)
<M-C-S-Right> (same as <M-C-Right>)
<S-Home> (same as <Home>)
<M-S-Home> (same as <M-Home>)
<S-End> (same as <End>)
<M-S-End> (same as <M-End>)
<S-Enter> (same as <Enter>)
<C-Enter> (same as <Enter>)
```````````````````````````````````````````````````````````````````````````````
Option 2: Use TERM=putty-sco
Full function-key support can be had by using PuTTY's "SCO" selection;
however, it has the side-effect that <Delete> is aliased to <Backspace>,
losing the <Delete> functionality.
Using PuTTY's configuration menu:
- "Connection"
- "Data"
- Set "Terminal-type string" to "putty-sco"
- "Terminal"
- "Keyboard"
- Set "The Function keys and keypad" to "SCO"
Reserved keys (should work if environment passes them to Vim):
<M-F4> (reserved to close window)
Inoperable keys (terminal sends no codes):
<C-Home>
<C-S-Home>
<M-C-Home>
<M-C-S-Home>
<C-End>
<C-S-End>
<M-C-End>
<M-C-S-End>
Inoperable keys (not enough mappable keys):
<C-S-F1> - <C-S-F12>
<M-C-F1> - <M-C-F12>
<M-S-F1> - <M-S-F12>
<M-C-S-F1> - <M-C-S-F12>
Aliased keys:
<Delete> (same as <Backspace>)
<S-Up> (same as <C-Up>)
<C-S-Up> (same as <C-Up>)
<M-S-Up> (same as <M-C-Up>)
<M-C-S-Up> (same as <M-C-Up>)
<S-Down> (same as <C-Down>)
<C-S-Down> (same as <C-Down>)
<M-S-Down> (same as <M-C-Down>)
<M-C-S-Down> (same as <M-C-Down>)
<S-Left> (same as <C-Left>)
<C-S-Left> (same as <C-Left>)
<M-S-Left> (same as <M-C-Left>)
<M-C-S-Left> (same as <M-C-Left>)
<S-Right> (same as <C-Right>)
<C-S-Right> (same as <C-Right>)
<M-S-Right> (same as <M-C-Right>)
<M-C-S-Right> (same as <M-C-Right>)
<S-Home> (same as <Home>)
<M-S-Home> (same as <M-Home>)
<S-End> (same as <End>)
<M-S-End> (same as <M-End>)
<S-Enter> (same as <Enter>)
<C-Enter> (same as <Enter>)
-------------------------------------------------------------------------------
3.6 Setup rxvt *fixkey-term-rxvt*
There is no additional setup for using rxvt (or rxvt-unicode) when
TERM=rxvt (or TERM=rxvt-unicode).
Reserved keys (should work if environment passes them to Vim):
<M-C-F1> - <M-C-F12> (reserved for switching virtual consoles)
Inoperable keys (terminal sends no codes):
<S-Up> (rxvt-unicode only; reserved for scrollback)
<S-Down> (rxvt-unicode only; reserved for scrollback)
<S-Home> (rxvt-unicode only; reserved for scrollback)
<S-End> (rxvt-unicode only; reserved for scrollback)
Inoperable keys (not enough mappable keys):
<C-S-F1> - <C-S-F12>
<M-S-F1> - <M-S-F12>
<M-C-S-F1> - <M-C-S-F12>
<M-C-S-Home>, <M-C-S-End>
Aliased keys:
<S-F1> (same as <F11>)
<S-F2> (same as <F12>)
<C-S-Up> (same as <S-Up>)
<C-S-Down> (same as <S-Down>)
<C-S-Left> (same as <S-Left>)
<C-S-Right> (same as <S-Right>)
<M-C-S-Up> (same as <M-S-Up>)
<M-C-S-Down> (same as <M-S-Down>)
<M-C-S-Left> (same as <M-S-Left>)
<M-C-S-Right> (same as <M-S-Right>)
<S-Enter> (same as <Enter>)
<C-Enter> (same as <Enter>)
-------------------------------------------------------------------------------
3.7 Setup screen *fixkey-term-screen*
There is no additional setup for using screen.
Supported TERM values: >
screen [-###color]? [-bce]? [-s]?
screen [-###color|-bce|-it|-s]*
E.g., TERM=screen, TERM=screen-bce, TERM=screen-256color-bce-s, TERM=screen-it
The "-###color" variants have additional color support.
The "-bce" variants use the Background Color Erase (BCE) feature.
The "-it" variants support italics.
The "-s" variants support a status line.
Reserved keys (should work if environment passes them to Vim):
<M-C-F1> - <M-C-F12> (reserved for switching virtual consoles)
Inoperable keys (terminal sends no codes):
none
Aliased keys:
<C-Enter> (same as <Enter>)
Note that support for <M-Enter> and <S-Enter> requires using Konsole as the
host terminal at present.
-------------------------------------------------------------------------------
3.8 Setup tmux *fixkey-term-tmux*
Tmux commonly shares terminal names with screen, in which case fixkey treats
them the same; see the "Setup screen" section for supported terminal names
starting with "screen".
In versions prior to 2.1, tmux required TERM to start with "screen"; starting
with version 2.1, users may choose terminal names beginning with "tmux" instead
(e.g., "tmux", "tmux-256color", etc.). This is useful for enabling italics
under tmux. Fixkey will detect such names and configure the keys the same as if
TERM were "screen". In addition, Fixkey will set 'ttymouse' to "xterm" as a
work-around; otherwise, Vim mis-detects the mouse and configures the
mouse-related codes such that the <Home> and <End> key mappings don't work
correctly. It works for "screen" only because Vim has special-case code to set
'ttymouse' to "xterm" whenever TERM starts with "screen", but Vim lacks that
same special-case code for "tmux". To change the default value for TERM to
"tmux", add the following to your ~/.tmux.conf file: >
set-option -g default-terminal tmux
<
Supported tmux-specific TERM values: >
tmux [-###color]? [-bce]? [-s]?
tmux [-###color|-bce|-it|-s]*
E.g., TERM=tmux, TERM=tmux-bce, TERM=tmux-256color-bce-s, TERM=tmux-it
The "-###color" variants have additional color support.
The "-bce" variants use the Background Color Erase (BCE) feature.
The "-it" variants support italics.
The "-s" variants support a status line.
In your ~/.tmux.conf, do not set default-terminal to something that doesn't
start with "screen" (or with "tmux", assuming you have a properly configured
termcap entry); instead, either allow tmux to set it properly, or choose a
supported value like "screen-256color-bce" or "tmux-it". Otherwise, things
won't work properly according to the tmux FAQ, which says: >
PLEASE NOTE: most display problems are due to incorrect TERM! Before
reporting problems make SURE that TERM settings are correct inside and
outside tmux.
Inside tmux TERM must be "screen" or similar (such as "screen-256color").
Don't bother reporting problems where it isn't!
<
In addition, to enable shifted function keys, place the following setting in
~/.tmux.conf: >
set -g xterm-keys on
You may find key code errors when pressing Escape followed by another key in
rapid succession. This is due to the same decoding ambiguities mentioned in
|fixkey-intro|. To work around this problem, you may change "escape-time" in
in your ~/.tmux.conf file to something short; the author uses 5 milliseconds in
his configuration: >
set-option -s escape-time 5
<
Reserved keys (should work if environment passes them to Vim):
<M-C-F1> - <M-C-F12> (reserved for switching virtual consoles)
Inoperable keys (terminal sends no codes):
none
Aliased keys:
<C-Enter> (same as <Enter>)
Note that support for <M-Enter> and <S-Enter> requires using Konsole as the
host terminal at present.
-------------------------------------------------------------------------------
3.9 Terminal testing *fixkey-term-testing*
Fixkey comes with a test script that helps determine when keys are working
correctly. Launch console vim as follows to initiate the test: >
vim '+runtime scripts/fixkeytest.vim'
Alternatively, launch console Vim, then run the following command: >
:runtime scripts/fixkeytest.vim
Now press keys in normal-mode or insert-mode and observe whether the correct
key is displayed.
Also, while in insert mode in Vim, pressing CTRL-v will allow literal
insertion of the next keypress. This helps for keys like <Enter> that
shouldn't be remapped by "fixkeytest". Pressing CTRL-v <Enter> in insert mode
yields "^M", showing that <Enter> generates CTRL-M (carriage return).
The terminfo settings for the entire terminal can be shown via the infocmp
program: >
infocmp xterm
# Reconstructed via infocmp from file: /usr/share/terminfo/x/xterm
xterm|xterm terminal emulator (X Window System),
am, bce, km, mc5i, mir, msgr, npc, xenl,
colors#8, cols#80, it#8, lines#24, pairs#64,
[...]
In addition, differences in terminfo between two terminals can be displayed as
well. To see what changes between xterm and xterm-256color: >
infocmp xterm xterm-256color
comparing xterm to xterm-256color.
comparing booleans.
ccc: F:T.
comparing numbers.
colors: 8, 256.
pairs: 64, 32767.
comparing strings.
initc: NULL, '\E]4;%p1%d;rgb\:%p2%{255}%*%{1000}%/%2.2X/%p3%{255}%*%{1000}%/%2.2X/%p4%{255}%*%{1000}%/%2.2X\E\\'.
setab: '\E[4%p1%dm', '\E[%?%p1%{8}%<%t4%p1%d%e%p1%{16}%<%t10%p1%{8}%-%d%e48;5;%p1%d%;m'.
setaf: '\E[3%p1%dm', '\E[%?%p1%{8}%<%t3%p1%d%e%p1%{16}%<%t9%p1%{8}%-%d%e38;5;%p1%d%;m'.
setb: '\E[4%?%p1%{1}%=%t4%e%p1%{3}%=%t6%e%p1%{4}%=%t1%e%p1%{6}%=%t3%e%p1%d%;m', NULL.
setf: '\E[3%?%p1%{1}%=%t4%e%p1%{3}%=%t6%e%p1%{4}%=%t1%e%p1%{6}%=%t3%e%p1%d%;m', NULL.
You can check the terminfo database for the expected key codes for known keys.
The tput command can echo a key code, and the cat program can display the
result. For example, to check the key code for <F1> on an xterm, the
terminfo "capability" name "kf1" may be queried: >
tput -Txterm kf1 | cat -A; echo
^[OP
This shows that the key code is \eOP (<Escape>OP) for "kf1" (<F1>).
Many terminals support "keypad transmit mode". In this mode, certain keys
(such as arrow keys) may become active, or may change key codes.
Interactive applications such as Vim typically set keypad transmit mode at
startup and reset it before they terminate, so it's important to use the right
terminfo capability name for the expected mode.
As an example, the <Up> arrow key has two different capability names. When
keypad transmit mode is enabled, the capability is named "kcuu1"; otherwise,
it is "cuu1" (dropping the leading "k"). For an xterm, these are different: >
tput -Txterm kcuu1 | cat -A; echo
^[OA
tput -Txterm cuu1 | cat -A; echo
^[[A
To interactively see what all keys do for the current terminal, you can run
the following commands at the shell prompt. The first places the terminal
into keypad transmit mode, the second displays the escape sequences, and the
third turns keypad transmit mode back off: >
tput smkx; cat > /dev/null; tput rmkx
Terminate testing by pressing CTRL-d.
If your terminal gets stuck in a strange mode, issue "reset" at the shell
prompt to restore proper operation.
Alternatively, a hex dump of the keys can be shown by replacing the "cat" with
a hexdumping tool (such as "xxd"): >
tput smkx; xxd; tput rmkx
Press and hold the key of interest for a while, then press <Enter> to flush
the input stream and see the hex output. For example, pressing <Up> for a
while, then pressing <Enter>, yields: >
0000000: 1b4f 411b 4f41 1b4f 411b 4f41 1b4f 411b .OA.OA.OA.OA.OA.
Thus, <Up> yields <Escape>OA on this terminal.
Using just "xxd" shows the sequence when not in keypad transmit mode: >
xxd
0000000: 1b5b 411b 5b41 1b5b 411b 5b41 1b5b 411b .[A.[A.[A.[A.[A.
Now, <Up> yields <Escape>[A because keypad transmit mode is off.
===============================================================================
4. ChangeLog *fixkey-changelog*
Version 0.3.8 Date 2016-10-04 *fixkey-changelog-0.3.8*
- Add work-around for TERM=tmux. Vim detects TERM=screen and sets 'ttymouse'
to the correct value, but has no such logic for TERM=tmux. Because having
an incorrect value for 'ttymouse' causes Vim to use mouse codes that
conflict with <Home> and <End>, Fixkey now sets 'ttymouse' to "xterm" when
TERM=tmux to work around this issue.
Version 0.3.7 Date 2015-10-22 *fixkey-changelog-0.3.7*
- Fixup function keys and navigation keys (home/end/arrows/etc.) for
xterm, konsole, and gnome-terminal. This corrects a problem with stock
Fedora Linux vim, because Fedora patches Vim and exchanges the definitions
for <F1> through <F4> with <xF1> through <xF4>.
Version 0.3.6 Date 2015-10-22 *fixkey-changelog-0.3.6*
- Add support for TERM=tmux.
Version 0.3.5 Date 2014-07-26 *fixkey-changelog-0.3.5*
- Add support for -it subvariants of screen (e.g.,
TERM=screen-256color-it will now work), thanks to Kevin MacMartin.
Version 0.3.4 Date 2014-06-26 *fixkey-changelog-0.3.4*
- Change 'ttimelen' to 5 milliseconds to avoid incorrect keystroke
decoding for fast typists.
- Document problems cause by using macros with fixkey.
Version 0.3.3 Date 2014-05-17 *fixkey-changelog-0.3.3*
- Add support for overlooked PuTTY-SCO keys <F1> to <F12>.
Version 0.3.2 Date 2013-10-03 *fixkey-changelog-0.3.2*
- Documentation reorganization.
Version 0.3.1 Date 2013-09-23 *fixkey-changelog-0.3.1*
- Restore cpoptions correctly, thanks to blackheaven.
Version 0.3.0 Date 2013-08-25 *fixkey-changelog-0.3.0*
- Add support for more modifier keys. Now all combinations of Shift,
Control, and Meta work with function keys, arrows, and home/end (on
supported terminals).
Version 0.2.3 Date 2013-08-20 *fixkey-changelog-0.2.3*
- Add support for -bce and -s subvariants of screen (e.g.,
TERM=screen-256color-bce-s will now work), thanks to AguirreIF.
Version 0.2.2 Date 2013-08-18 *fixkey-changelog-0.2.2*
- Add support for <M-Enter>, <S-Enter> for some terminals.
Version 0.2.1 Date 2013-08-15 *fixkey-changelog-0.2.1*
- Initial upload.
===============================================================================
5. References *fixkey-references*
- "Mapping fast keycodes in terminal Vim":
http://vim.wikia.com/wiki/Mapping_fast_keycodes_in_terminal_Vim
- ncurses FAQ describing shifted function keys:
http://invisible-island.net/ncurses/ncurses.faq.html#modified_keys
- KDE Konsole developers stating their desire to have TERM=xterm for Konsole:
https://bugs.kde.org/show_bug.cgi?id=145977
- Terminfo overview:
http://tldp.org/HOWTO/Text-Terminal-HOWTO-16.html
- Modifying an existing terminfo database entry:
http://www.jbase.com/r5/knowledgebase/howto/general/common/CreateTerminfo/modify.htm
- Function keys don't work in gnome-terminal:
https://bugs.launchpad.net/ubuntu/+source/gnome-terminal/+bug/96676
- Terminfo Source Format, from The Single Unix Specification, Version 2:
http://pubs.opengroup.org/onlinepubs/7908799/xcurses/terminfo.html
- Xterm control sequences:
http://invisible-island.net/xterm/ctlseqs/ctlseqs.html
- X resources (Arch Linux wiki):
https://wiki.archlinux.org/index.php/X_resources
-------------------------------------------------------------------------------
xterm notes
Vim's help documents xterm function keys here: |xterm-function-keys|
Two keycodes might be sent, either vt100-compatible or not. The Vim help
documents that <xF1> - <xF4> are used for the vt100-compatible keycodes:
<xF1> <Esc>OP
<xF2> <Esc>OQ
<xF3> <Esc>OR
<xF4> <Esc>OS
The actual built-in defaults for these codes use the "*" wildcard form for
modifiers that is documented here: |xterm-modifier-keys|
<xF1> <Esc>O*P
<xF2> <Esc>O*Q
<xF3> <Esc>O*R
<xF4> <Esc>O*S
xterm does send these vt100-compatible codes for these keys when no modifiers
are pressed.
Vim's built-in defaults differ from what modern xterm sends for these keys
when a modifier is pressed. The Vim defaults are:
<F1> <Esc>[11;*
<F2> <Esc>[12;*
<F3> <Esc>[13;*
<F4> <Esc>[14;*
These correspond to obsolete encodings for very old versions of xterm, which
have been deprecated in xterm (see
http://invisible-island.net/xterm/ctlseqs/ctlseqs.html):
Older versions of xterm implement different escape sequences for F1 through
F4, with a CSI prefix [CSI is Escape followed by left-bracket, as shown
above]. These can be activated by setting the oldXtermFKeys resource.
However, since they do not correspond to any hardware terminal, they have been
deprecated. (The DEC VT220 reserves F1 through F5 for local functions such as
Setup).
Key Escape Sequence
---------+-----------------
F1 | CSI 1 1 ~
F2 | CSI 1 2 ~
F3 | CSI 1 3 ~
F4 | CSI 1 4 ~
---------+-----------------
Modern xterm actually sends the following:
<F1> <Esc>[1;*P
<F2> <Esc>[1;*Q
<F3> <Esc>[1;*R
<F4> <Esc>[1;*S
Note that the prefix for modified keys (<Esc>[) differs from the unmodified keys
(<Esc>O); for this reason, both <F1> and <xF1> must be set for Vim to
handle pressing F1 with or without modifiers.
-------------------------------------------------------------------------------
gnome-terminal notes
gnome-terminal sends vt100-compatible codes for unmodified <xF1> through
<xF4>:
<xF1> <Esc>OP
<xF2> <Esc>OQ
<xF3> <Esc>OR
<xF4> <Esc>OS
With modifiers, gnome-terminal sends different codes than xterm. Where xterm
would send "[", gnome-terminal sends "O":
<F1> <Esc>O1;*P
<F2> <Esc>O1;*Q
<F3> <Esc>O1;*R
<F4> <Esc>O1;*S
Fortunately, both cases are handled using the special "1;*" encoding.
===============================================================================
6. Credits *fixkey-credits*
Developed by Michael Henry (vim at drmikehenry.com).
Distributed under Vim's |license|.
Git repository: https://github.com/drmikehenry/vim-fixkey
Contributors (in chronological order):
- AguirreIF
- blackheaven
- Kevin MacMartin
- Andy Weidenbaum
===============================================================================
vim:sts=2:et:ai:tw=78:fo=tcq2:ft=help: