Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/lyokha/vim-xkbswitch

vim plugin for automatic keyboard layout switching in insert mode
https://github.com/lyokha/vim-xkbswitch

keyboard-layout switch-layouts vim

Last synced: about 2 months ago
JSON representation

vim plugin for automatic keyboard layout switching in insert mode

Awesome Lists containing this project

README 

        
Vim-xkbswitch

=============



by Alexey Radkov and Dmitry Hrabrov a.k.a. DeXPeriX



Table of contents

-----------------



- [About](#about)

- [Features](#features)

- [Setup](#setup)

- [Configuration](#configuration)

    + [Basic configuration](#basic-configuration)

    + [Keymap assistance in Normal mode](#keymap-assistance-in-normal-mode)

    + [Default layouts](#default-layouts)

    + [Disable for specific filetypes](#disable-for-specific-filetypes)

    + [Enable in runtime](#enable-in-runtime)

- [Insert enter hook](#insert-enter-hook)

- [Custom keyboard layout switching rules](#custom-keyboard-layout-switching-rules)

- [Troubleshooting](#troubleshooting)



About

-----



If you speak and write in two or more languages, you may know how it's

frustrating to constantly switch keyboard layouts manually, because vim

in command mode can understand only English letters. So you need constantly

change keyboard layout into English if you need perform some command and

if you are writing texts, for example, in Russian, German or Chinese at the

same time.



Vim plugin XkbSwitch can be used to easily switch current keyboard layout back

and forth when entering and leaving Insert mode. Say, you are typing some

document in Russian and have to leave Insert mode: when you press ````

your keyboard layout switches to US/English automatically. When you further

enter Insert mode once again the Russian keyboard layout will be automatically

switched back!



XkbSwitch requires an OS dependent keyboard layout switcher. Below is the list

of compatible switchers.



- **UNIX / Linux / X Server**:

  [xkb-switch](http://github.com/ierton/xkb-switch).

- **Windows**: [xkb-switch-win](http://github.com/DeXP/xkb-switch-win).

- **Mac OS X**: [xkbswitch-macosx](http://github.com/myshov/xkbswitch-macosx) or

  [Input Source Switcher](http://github.com/vovkasm/input-source-switcher). In

  the latter case, put line



    ```vim

  let g:XkbSwitchLib = '/usr/local/lib/libInputSourceSwitcher.dylib'

    ```



  into your .vimrc settings.

- **Gnome 3 and 4x**: [g3kb-switch](http://github.com/lyokha/g3kb-switch). The

  plugin can be loaded with



    ```vim

  let g:XkbSwitchLib = '/usr/local/lib/libg3kbswitch.so'

    ```



- **i3wm**: [xkb-switch-i3](http://github.com/Zebradil/xkb-switch-i3).

- **sway**: [sway-vim-kbswitch](http://github.com/khaser/sway-vim-kbswitch).



Features

--------



* Supported OS: UNIX (X Server / Sway), Windows, Mac OS X.

* Switches keyboard layout when entering / leaving Insert and Select modes

  as well as the command line when searching patterns.

* Dynamic keymap assistance in commands like *r* and *f* in Normal mode.

* Keyboard layouts are stored separately for each buffer.

* Keyboard layouts are kept intact while navigating between windows or

  tabs without leaving Insert mode.

* Automatic loading of language-friendly Insert mode mappings duplicates.

  For example, when Russian mappings have loaded then if there was a mapping



    ```vim

  S        ISurround

    ```



  a new mapping



    ```vim

  Ы        ISurround

    ```



  will be loaded. Insert mode mappings duplicates make it easy to apply

  existing maps in Insert mode without switching current keyboard layout.

* Fast and easy building of custom syntax based keyboard layout switching

  rules in Insert mode.



Setup

-----



Before installation of the plugin the OS dependent keyboard layout switcher

must be installed (see [About](#about)). The plugin itself is installed by

extracting of the distribution in your vim runtime directory.



Configuration

-------------



### Basic configuration



Basic configuration requires only 1 line in your .vimrc:



```vim

let g:XkbSwitchEnabled = 1

```



Additionally path to the backend switcher library can be defined:



```vim

let g:XkbSwitchLib = '/usr/local/lib/libxkbswitch.so'

```



However normally it is not necessary as far as the plugin is able to find it

automatically. To enable Insert mode mappings duplicates user may want to add



```vim

let g:XkbSwitchIMappings = ['ru']

```



Here Insert mappings duplicates for Russian winkeys layout will be generated

whenever Insert mode is started. It is possible to define a list of different

layouts, for example



```vim

let g:XkbSwitchIMappings = ['ru', 'de']

```



but currently only Russian winkeys ('ru') and Ukrainian ('uk') layout

translation maps are supported out of the box. There are 2 ways how a user can

provide extra definitions of keyboard layout translation maps (or alter/remove

existing default 'ru' and 'uk' maps):



* Define variable g:XkbSwitchIMappingsTr:



    ```vim

  let g:XkbSwitchIMappingsTr = {

              \ 'ru':

              \ {'<': 'qwertyuiop[]asdfghjkl;''zxcvbnm,.`/'.

              \       'QWERTYUIOP{}ASDFGHJKL:"ZXCVBNM<>?~@#$^&|',

              \  '>': 'йцукенгшщзхъфывапролджэячсмитьбюё.'.

              \       'ЙЦУКЕНГШЩЗХЪФЫВАПРОЛДЖЭЯЧСМИТЬБЮ,Ё"№;:?/'},

              \ 'de':

              \ {'<': 'yz-[];''/YZ{}:"<>?~@#^&*_\',

              \  '>': 'zyßü+öä-ZYÜ*ÖÄ;:_°"§&/(?#'},

              \ }

    ```



* Create a file with layout translation maps and put its path into variable

  g:XkbSwitchIMappingsTrData, for example:



    ```vim

  let g:XkbSwitchIMappingsTrData = $HOME.'/opt/xkbswitch.tr'

    ```



  File with maps must follow this format:



    ```

  ru  Russian winkeys layout

  < qwertyuiop[]asdfghjkl;'zxcvbnm,.`/QWERTYUIOP{}ASDFGHJKL:"ZXCVBNM<>?~@#$^&|

  > йцукенгшщзхъфывапролджэячсмитьбюё.ЙЦУКЕНГШЩЗХЪФЫВАПРОЛДЖЭЯЧСМИТЬБЮ,Ё"№;:?/



  de

  < yz-[];'/YZ{}:"<>?~@#^&*(_\

  > zyßü+öä-ZYÜ*ÖÄ;:_°"§&/()?#

    ```



  Sample file xkbswitch.tr with exactly this content is shipped with this

  plugin distribution. Files with translation maps can be easily created from

  vim keymap definitions: see details [here](utils/README.md).



Be very careful with mapping duplicates! They won't replace existing Insert

mode mappings but may define extra mappings that will change normal Insert

mode user experience. For example, plugin echofunc defines Insert mode

mappings for '(' and ')', therefore assuming that in Deutsch translation map

there could be ')' to '=' translation, we would get '=' unusable in any

keyboard layout (as far as echofunc treats ')' in a very specific way). That

is why this translation is missing in example above and in file xkbswitch.tr

content.



There are multiple examples of similar issues. For instance Russian winkeys

translate '.' into 'ю' and when you are editing a C/C++ source file with

enabled omnicompletion plugin character 'ю' (which you can use in comments)

will always be replaced by '.'. To address these issues starting from **version

0.10** a new variable g:XkbSwitchSkipIMappings was introduced. It defines which

original Insert mode mappings should not be translated for specific filetypes.

Add into your .vimrc lines



```vim

let g:XkbSwitchSkipIMappings =

        \ {'c'   : ['.', '>', ':', '{', '/*', '/*'],

        \  'cpp' : ['.', '>', ':', '{', '/*', '/*']}

```



and now you will be able to print 'ю' in C and C++ source files. In this

example six Insert mode mappings were prohibited for translation in two

filetypes: C and C++. The first three correspond to omnicompletion plugin and

the last three address plugin c.vim. Why mappings duplicates starting from '/'

were added: Russian winkeys translate '/' into '.' and this makes vim wait for

a while until the next character after '.' has been inserted which makes

omnicompletion plugin almost unusable. If you want to skip specific Insert

mode mappings for all filetypes then you can use '\*' as the filetype key in

g:XkbSwitchSkipIMappings.



Beware: variable g:XkbSwitchSkipIMappings is not parameterized by keyboard

layouts but only by filetypes.



Besides natural Insert mode mappings, register insertion translations are also

supported. For example, being in Insert mode and having Russian winkeys layout

on, you can insert content of register 'a' just printing ``ф`` without

switching current keyboard layout. To disable translation of register names in

Insert mode put line



```vim

let g:XkbSwitchLoadRIMappings = 0

```



into your .vimrc.



### Keymap assistance in Normal mode



XkbSwitch is unable to guess keyboard layout when using Normal mode commands

*r* and *f* and, in the past, searching patterns with */* and *?*. Fortunately,

it can assist *keymap* in this by setting



```vim

let g:XkbSwitchAssistNKeymap = 1        " for commands r and f

if !exists('##CmdlineEnter')

    let g:XkbSwitchAssistSKeymap = 1    " for search lines

endif

```



given that keymap is set to some value, for example



```vim

set keymap=russian-jcukenwin

set iminsert=0

set imsearch=0

```



(Note that setting of g:XkbSwitchAssistSKeymap is deprecated because tracking

of entering / leaving command line for searching patterns is fully supported

after CmdlineEnter and CmdlineLeave events have been introduced in vim.)



Now when you leave Insert mode, the keyboard layout is switched back to the

usual Normal mode value, but values of *iminsert* and *imsearch* are set

depending on the last Insert mode keyboard layout: if it was equal to the

value of b:keymap_name that is normally defined in keymap files then they are

set to 1, otherwise to 0. If keymap names do not match system keyboard layout

names then you can remap them using variable g:XkbSwitchKeymapNames.



```vim

let g:XkbSwitchKeymapNames = {'ru' : 'ru_keymap', 'uk' : 'uk_keymap'}

```



Here *ru* and *uk* are system keyboard layout names whereas *ru_keymap* and

*uk_keymap* are values of b:keymap_name.



When more than two keyboard layouts are used it probably makes sense to set

keymaps dynamically in runtime. XkbSwitch can do it for you! You only need to

define a new variable



```vim

let g:XkbSwitchDynamicKeymap = 1

```



and map g:XkbSwitchKeymapNames to keymap names instead of values of

b:keymap_name. For example



```vim

let g:XkbSwitchKeymapNames =

            \ {'ru' : 'russian-jcukenwin', 'uk' : 'ukrainian-jcuken'}



```



Now keymap will automatically switch to the last keyboard layout when you

leave Insert mode.



To toggle keymap layout in Normal mode for using in commands *r* and *f*, you

may need to set a dedicated key:



```vim

let g:XkbSwitchIminsertToggleKey = ''

```



By default pressing the key will be echoed in the command-line which is

sometimes superfluous: modern status-line plugins such as

[airline](http://github.com/vim-airline/vim-airline) normally provide support

for showing iminsert indicators.



To disable echo messages when toggling keymap layout add line



```vim

let g:XkbSwitchIminsertToggleEcho = 0

```



into your .vimrc.



To enable the iminsert indicator in airline add line



```vim

let g:airline_detect_iminsert = 1

```



Notice that toggling keymap layout when typing a pattern for a search command

can be done with the builtin key *Ctrl-^*.



### Default layouts



By default last Normal mode keyboard layout is restored when leaving Insert

mode, but you can specify to use particular layout for that:



```vim

let g:XkbSwitchNLayout = 'us'

```



Also you can specify *original* Insert mode keyboard layout:



```vim

let g:XkbSwitchILayout = 'us'

```



Or *unconditional* Insert mode keyboard layout using buffer variable with the

same name:



```vim

let b:XkbSwitchILayout = 'us'

```



If b:XkbSwitchILayout is set to the empty value then the keyboard layout is not

changed when entering Insert mode. Be aware that momental switching from-and-to

Insert mode (e.g. with Insert mode command ```` and all types of

selections) will turn current keyboard layout to the value of

b:XkbSwitchILayout. If you want to use unconditional Insert mode keyboard layout

by default then put line



```vim

autocmd BufEnter * let b:XkbSwitchILayout = 'us'

```



into your .vimrc (change *us* to desired value if needed).



### Disable for specific filetypes



It makes sense to disable XkbSwitch for buffers with specific filetypes, for

example various file system or tag navigators. For example, to disable

XkbSwitch for NerdTree add in your .vimrc line



```vim

let g:XkbSwitchSkipFt = ['nerdtree']

```



By default (e.g. when g:XkbSwitchSkipFt is not defined in .vimrc) following

filetypes are skipped: *tagbar*, *gundo*, *nerdtree* and *fuf* (FuzzyFinder).



### Enable in runtime



You can enable XkbSwitch in runtime (e.g. when g:XkbSwitchEnabled is not set

in your .vimrc) by issuing command



```vim

:EnableXkbSwitch

```



This command will respect current settings of g:XkbSwitchIMappings etc. Be

aware that there is no way to disable XkbSwitch after it has been enabled.



Insert enter hook

-----------------



You may want to run a custom vim function when entering Insert mode. For

example, let's flash the cursor for a moment if the keyboard layout effectively

switches. Plugin [Beacon](https://github.com/DanilaMihailov/beacon.nvim) fits

very well this purpose. Just put lines



```vim

let g:XkbSwitchIEnterHook = 'XkbSwitchIEnterHook'



highlight link BeaconIEnter Cursor



fun! XkbSwitchRevertBeaconHighlight(id)

    highlight! link Beacon BeaconDefault

endfun



fun! XkbSwitchIEnterHook(old, new)

    if a:new != a:old

        let save_beacon_size = g:beacon_size

        let g:beacon_size = 20

        highlight! link Beacon BeaconIEnter

        Beacon

        let g:beacon_size = save_beacon_size

        call timer_start(500, 'XkbSwitchRevertBeaconHighlight')

    endif

endfun

```



into .vimrc file. Arguments *old* and *new* are keyboard layouts being switched

from and to while transitioning from Normal to Insert mode.



Custom keyboard layout switching rules

--------------------------------------



Imagine that you are editing a simple dictionary with 2 columns delimited by

vertical bars. In the first column you are writing down a German word and in

the second column - its Russian translation. For example:



```

| Wort         | Übersetzung |

|--------------|-------------|

| der Mond     | луна        |

| humpeln      | хромать     |

| stark        | сильный     |

```



You want the keyboard layout to be automatically switched to the corresponding

language when you are moving between the columns in Insert mode. It is

feasible! When you start editing switch layouts in the both columns manually

just once: after that XkbSwitch will learn how to switch them further. It will

restore layouts after leaving Insert mode and entering it once again.



In this section it will be shown how to achieve this. First of all there

should exist criteria upon which XkbSwitch will decide when it must switch

layouts. The simplest criteria are syntactic rules. So the content of the

columns must be syntactically distinguishable. It means that we need a file

with syntax rules and some new filetype defined, say *mdict*. For the sake of

simplicity let it be not an absolutely new filetype but rather a subclass of

an existing one, for example vimwiki. Then we should create a new file

after/syntax/vimwiki.vim:



```vim

if match(bufname('%'), '\.mdict$') == -1

    finish

endif



let s:colors = {'original':   [189, '#d7d7ff'],

              \ 'translated': [194, '#d7ffd7'],

              \ 'extra':      [191, '#d7ff5f']}



function! s:set_colors()

    let colors = deepcopy(s:colors)

    if exists('g:colors_name') && g:colors_name == 'lucius' &&

                \ g:lucius_style == 'light'

        let colors['original']   = [26,  '#005fd7']

        let colors['translated'] = [22,  '#005f00']

        let colors['extra']      = [167, '#d75f5f']

    endif

    exe 'hi mdictOriginalHl term=standout ctermfg='.colors['original'][0].

                \ ' guifg='.colors['original'][1]

    exe 'hi mdictTranslatedHl term=standout ctermfg='.colors['translated'][0].

                \ ' guifg='.colors['translated'][1]

    exe 'hi mdictExtraHl term=standout ctermfg='.colors['extra'][0].

                \ ' guifg='.colors['extra'][1]

endfunction



syntax match mdictCell '|[^|]*\ze|' containedin=VimwikiTableRow contained

            \ contains=VimwikiCellSeparator,mdictOriginal,mdictTranslated

syntax match mdictOriginal '[^|]\+\ze|\s*\S*.*$' contained contains=mdictExtra

syntax match mdictTranslated '[^|]\+\ze|\s*$' contained contains=mdictExtra

syntax match mdictExtra '([^()]*)' contained



call s:set_colors()

autocmd ColorScheme * call s:set_colors()



hi link mdictOriginal   mdictOriginalHl

hi link mdictTranslated mdictTranslatedHl

hi link mdictExtra      mdictExtraHl

```



Here the syntactic criteria have been defined: content of the first column

will have syntax id *mdictOriginal* and content of the second column -

*mdictTranslated*.



In .vimrc following lines must be added:



```vim

let g:mdict_synroles = ['mdictOriginal', 'mdictTranslated']



fun! MdictCheckLang(force)

    if !filereadable(g:XkbSwitchLib)

        return

    endif



    let cur_synid  = synIDattr(synID(line("."), col("."), 1), "name")



    if !exists('b:saved_cur_synid')

        let b:saved_cur_synid = cur_synid

    endif

    if !exists('b:saved_cur_layout')

        let b:saved_cur_layout = {}

    endif



    if cur_synid != b:saved_cur_synid || a:force

        let cur_layout = ''

        for role in g:mdict_synroles

            if b:saved_cur_synid == role

                let cur_layout =

                    \ libcall(g:XkbSwitchLib, 'Xkb_Switch_getXkbLayout', '')

                let b:saved_cur_layout[role] = cur_layout

                break

            endif

        endfor

        for role in g:mdict_synroles

            if cur_synid == role

                if exists('b:saved_cur_layout[role]')

                    call libcall(g:XkbSwitchLib, 'Xkb_Switch_setXkbLayout',

                                \ b:saved_cur_layout[role])

                else

                    let b:saved_cur_layout[role] = empty(cur_layout) ?

                                \ libcall(g:XkbSwitchLib,

                                \ 'Xkb_Switch_getXkbLayout', '') : cur_layout

                endif

                break

            endif

        endfor

        let b:saved_cur_synid = cur_synid

    endif

endfun



autocmd BufNewFile,BufRead *.mdict setlocal filetype=vimwiki |

           \ EnableXkbSwitch

autocmd BufNewFile         *.mdict VimwikiTable 2 2

autocmd BufNewFile         *.mdict exe "normal dd" | startinsert

autocmd CursorMovedI       *.mdict call MdictCheckLang(0)



let g:XkbSwitchPostIEnterAuto = [

            \ [{'pat': '*.mdict', 'cmd': 'call MdictCheckLang(1)'}, 0] ]

```



Function MdictCheckLang() does all the custom layout switching and can be

regarded as a plugin to the XkbSwitch. The first autocommand states that if

file has extension *.mdict* then its filetype must be *vimwiki* and turns on

XkbSwitch. The next two autocommands are optional and only make editing mdict

files more comfortable. The last autocommand (for CursorMovedI events) calls

MdictCheckLang() when cursor moves into different columns in Insert mode.

The next definition



```vim

let g:XkbSwitchPostIEnterAuto = [

            \ [{'pat': '*.mdict', 'cmd': 'call MdictCheckLang(1)'}, 0] ]

```



registers an InsertEnter autocommand in augroup XkbSwitch. If we had instead

defined an InsertEnter autocommand here then the command would have been put

before the standard InsertEnter autocommand in augroup XkbSwitch. Using variable

g:XkbSwitchPostIEnterAuto ensures that the new command will run after the

standard InsertEnter autocommand. The second element in an item inside

g:XkbSwitchPostIEnterAuto can be 0 or 1. If it is 1 then XkbSwitch won't switch

layout itself when entering Insert mode. In our case it should be 0 because

MdictCheckLang() requires preliminary switching keyboard layout from XkbSwitch

when entering Insert mode.



Starting from **version 0.9** a generic helper for building custom syntax based

keyboard layout switching rules was implemented inside the plugin code.  Now

building syntax rules is as simple as defining variable g:XkbSwitchSyntaxRules

in .vimrc. For example



```vim

let g:XkbSwitchSyntaxRules = [

            \ {'pat': '*.mdict', 'in': ['mdictOriginal', 'mdictTranslated']},

            \ {'ft': 'c,cpp', 'inout': ['cComment', 'cCommentL']} ]

```



registers syntax rules for files with extension *.mdict* (the first element in

g:XkbSwitchSyntaxRules: it replaces our old definitions of g:mdict_synroles,

MdictCheckLang(), autocmd CursorMovedI and g:XkbSwitchPostIEnterAuto) and

comments rules for C and C++ files (the second element in

g:XkbSwitchSyntaxRules). The comments rules define that comments areas may

have their own keyboard layouts in Insert mode and when cursor enters or

leaves them the corresponding layouts must be restored. It may be useful if

a user wants to make comments in a language that uses not standard keyboard

layout without switching layouts back and forth. Notice that the second rule

lists syntax groups in element *inout* whereas the first rule uses element

*in*. The difference is that in the case of the comments rule we want to

restore basic keyboard layout (i.e. layout for code areas) when leaving

comments areas, but in the mdict rule we do not care about leaving areas

*mdictOriginal* and *mdictTranslated* and only care about entering them.



Troubleshooting

---------------



* To test if the switcher library is well configured, run commands



    ```vim

  :echo libcall(g:XkbSwitchLib, 'Xkb_Switch_getXkbLayout', '')

    ```



  and



    ```vim

  :call libcall(g:XkbSwitchLib, 'Xkb_Switch_setXkbLayout', 'ru')

    ```



  which get and set the keyboard layout.



* Some characters from alternative keyboard layouts may fail to enter or behave

  in strange ways for certain filetypes. For example in Russian winkeys layout

  characters 'б', 'ю', 'ж' and 'э' may fail to enter in C++ source files. The

  reason of that is layout translation maps specified in variable

  g:XkbSwitchIMappings. You may work this around by simply not setting this

  variable, or better by specifying characters from the main keyboard layout

  whose translation should be skipped using variable g:XkbSwitchSkipIMappings.

  See details in section [Basic configuration](#basic-configuration).



* There is a known issue when vim-latex package is installed. In this case

  entering Russian symbols in Insert mode when editing tex files becomes

  impossible. The issue arises from clashing XkbSwitch Insert mappings

  duplicates with mappings defined in vim-latex. To work this issue around you

  can disable XkbSwitch Insert mode mappings duplicates for filetype *tex*:



    ```vim

  let g:XkbSwitchIMappingsSkipFt = ['tex']

    ```



* When leaving Insert mode after using an alternative keyboard layout (say

  Russian), there could be a time lag (of length *1 sec* if the value of

  ``timeoutlen`` was not altered) before typing commands in Normal mode gets

  back to produce any effect. To cope with this issue, the value of

  `ttimeoutlen` (notice the *double-t* in the beginning of its name!) must be

  set to some small value, say



    ```vim

  set ttimeoutlen=50

    ```



* *Related to X Server only.* When editing files on a remote host via ssh the

  ssh -X option must be supplied:



    ```sh

  ssh -X remote.host

    ```



  This option will make ssh forward X Server protocol messages between the

  local host and the remote host thus making it possible to switch the local

  host keyboard layouts.



* *Related to GTK based gvim only.* In bare X terminals keycodes for ````

  and ```` are the same which makes it possible to leave sequences with

  control keys in Insert mode mappings duplicates as they are. But this is not

  the case in GTK based gvim. The issue is still investigated.