*vm-settings.txt*    Version 0.3.0    Last change: June 13 2019

Settings                                                 |vm-settings|
Highlight                                                |vm-highlight|



SETTINGS                                                          *vm-settings*
===============================================================================

Hopefully you won't need to alter any of these.


*g:VM_highlight_matches*                           Default: 'underline'

  Controls VM default highlighting style for patterns matched, but not
  selected. Possible useful values are 'underline' and 'red'.
  Otherwise an empty string if you want the normal |Search| highlight, or
  a full highlight command (help |:hi|), e.g.:  >
    let g:VM_highlight_matches = 'hi Search ctermfg=228 cterm=underline'
    let g:VM_highlight_matches = 'hi! link Search PmenuSel'
<

*g:VM_set_statusline*                              Default: 2

  Enable statusline when VM is active.
  With a value of 1, the statusline will be set once, on VM start.
  With a value of 2, the statusline will be refreshed on |CursorHold| event.
  With a value of 3, also on |CursorMoved| event.


*g:VM_silent_exit*                                 Default: 0

  Don't display a message when exiting VM. You may prefer it if you already set
  up statusline integration.


*g:VM_quit_after_leaving_insert_mode*              Default: 0

  So that you don't have to type <Esc> twice. If you set this to 1, maybe you
  can remap `Reselect Last`, so that you can quickly restart VM with your last
  selection. See |vm-quick-reference|.


*g:VM_show_warnings*                               Default: 1

  When entering VM and there are mapping conflicts, a warning is displayed. Set
  to 0 to disable this warning. You can still run |:VMDebug| to see if there
  are conflicts.


*g:VM_verbose_commands*                            Default: 0

  Set to 1 if you want command prompts to be more informative, rather than as
  minimal as possible.


*g:VM_skip_shorter_lines*                          Default: 1

  When adding cursors up/down, skip shorter lines.


*g:VM_skip_empty_lines*                            Default: 0

  When adding cursors up/down, skip empty lines.


*g:VM_live_editing*                                Default: 1

  Controls how often text is updated in insert mode.


*g:VM_reselect_first*                              Default: 0

  The first region will be reselected after most commands, if set to 1.


*g:VM_case_setting*                                Default: ''

  Possible values: 'smart', 'sensitive', 'ignore'.
  Starting case matching for patterns. Can be switched inside VM.
  Leave empty to use your current setting.


*g:VM_disable_syntax_in_imode*                     Default: 0

  You could want to do it for performance reasons.


*VM_recursive_operations_at_cursors*               Default: 1

  When executing normal commands in cursor mode (`dw` and similar), by default
  recursive mappings are used, so that user text object can be used as well.
  Set to 0 if you always want commands in cursor mode to be non-recursive.


*g:VM_custom_remaps*                               Default: {}

  To remap VM mappings to other VM mappings.
  Example:
  >
  " also use <c-p> to select previous and <c-s> to skip current
  let g:VM_custom_remaps = {'<c-p>': 'N', '<c-s>': 'q'}
<

*g:VM_custom_noremaps*                             Default: {}

  To remap any key to normal! commands. Example:
  >
  let g:VM_custom_noremaps = {'==': '==', '<<': '<<', '>>': '>>'}
<
  would create commands that will work on all cursors inside VM, for each
  key-value pair. It's a way to remap built-in vim commands, without having
  too many default mappings that can cause conflicts with other plugins. They
  only work in (and enforce) cursor mode.


*g:VM_custom_motions*                              Default: {}

  To remap any standard motion (h,j,k,l,f...) commands. For example this
  inverts 'h' and 'l' motions:
>
  let g:VM_custom_motions  = {'h': 'l', 'l': 'h'}
<
  It can be useful if you use keyboard layouts other than QWERTY. Valid motions
  that you can remap are:
>
    h j k l w W b B e E ge gE , ; $ 0 ^ % \| f F t T
<

*g:VM_user_operators*                              Default: []

  Cursor mode only. The elements of the list can be simple strings (then
  any text object can be accepted) or a dictionary with the operator as key,
  and the number of characters to be typed as value. Example:
>
  let VM_user_operators = ['yd', 'cx', {'cs': 2}]
<
  This will accept commands like `ydE`, `cxiw`, or `cs` followed by two
  characters, for example `cs{[`. These operators can be either vim or
  plugin operators, mappings are passed recursively.

  Note: |vim-surround| and |vim-abolish| have built-in support, this isn't
  needed for them to work.


*g:VM_use_first_cursor_in_line*                    Default: 0

  In insert mode, the active cursor is normally the last selected one. Set this
  option to `1` to always use the first cursor in the line.


*g:VM_insert_special_keys*                         Default: ['c-v']

  Some keys in insert mode can have a different behaviour, compared to vim
  defaults. Possible values:

  `c-a`  <C-A> go to the beginning of the line, at indent level
  `c-e`  <C-E> go to the end of the line
  `c-v`  <C-V> paste from VM unnamed register


*g:VM_single_mode_maps*                            Default: 1

Set to 0 to disable entirely insert mode mappings to cycle cursors in
|vm-single-mode|. If you only want to change the default mappings, see
|vm-mappings-buffer|.


*g:VM_single_mode_auto_reset*                      Default: 1

If insert mode is entered while |vm-single-mode| is enabled, it will be reset
automatically when exiting insert mode, unless this value is 0.


*g:VM_filesize_limit*                              Default: 0 (disabled)

  VM won't start if buffer size is greater than this.


*g:VM_persistent_registers*                        Default: 0

  If true VM registers will be stored in the |viminfo|. The 'viminfo' option
  must include !, for this to work. Also see |:VMRegisters|.


*g:VM_reindent_filetypes*                          Default: []

  Autoindentation (via |indentkeys|) is temporarily disabled in insert mode,
  and you have to reindent edited lines yoursef. For filetypes included in this
  list, edited lines are automatically reindented when exiting insert mode.


*g:VM_plugins_compatibilty*                        Default: {}

Used for plugins compatibility, see |vm-compatibility|.




HIGHLIGHT                                                        *vm-highlight*
===============================================================================


VM default theme is based on your color scheme, if you don't like it you can:

* select a theme
* relink highlight groups
                                                                   *g:VM_theme*
You can load a theme by default by defining:  >
    let g:VM_theme = 'your_chosen_theme'
<                                                                    *:VMTheme*
If you want to change theme, run: >
    :VMTheme <tab>
<
To relink VM highlight groups: >

  let g:VM_Mono_hl   = 'DiffText'
  let g:VM_Extend_hl = 'DiffAdd'
  let g:VM_Cursor_hl = 'Visual'
  let g:VM_Insert_hl = 'DiffChange'
<
*g:VM_Mono_hl*    is the highlight in cursor mode
*g:VM_Extend_hl*  ,, in extend mode (the selections)
*g:VM_Cursor_hl*  ,, in extend mode (the cursors)
*g:VM_Insert_hl*  ,, in insert mode (the virtual cursors)




DEFINING THEMES IN COLORSCHEMES                               *vm-colorschemes*
===============================================================================

If you want to load a theme inside a colorscheme, just put in the colorscheme
script:
>
  silent! VMTheme theme_name
<
If you want to apply a custom theme, you may either relink groups as shown
above (but then settings would persist for other colorschemes), or do it like
this (example):
>
  if exists(':VMTheme')

    " to avoid that current theme is reapplied on colorscheme change
    let g:VM_theme_set_by_colorscheme = 1

    " you can define both or just one, depending on the scheme
    if &background == 'light'
      hi VM_Extend ctermbg=24    ctermfg=237    guibg=#AAF0D6    guifg=NONE
      hi VM_Cursor ctermbg=31    ctermfg=237    guibg=#78dede    guifg=#262626
      hi VM_Insert ctermbg=239   ctermfg=237    guibg=#ffffaf    guifg=#262626
      hi VM_Mono   ctermbg=180   ctermfg=235    guibg=#B23A2D    guifg=#ffffff
    else
      hi VM_Extend ctermbg=24    ctermfg=237    guibg=#5f8787    guifg=#ffffff
      hi VM_Cursor ctermbg=31    ctermfg=237    guibg=#00af87    guifg=#ffffff
      hi VM_Insert ctermbg=239   ctermfg=237    guibg=#5f0087    guifg=#ffffff
      hi VM_Mono   ctermbg=180   ctermfg=235    guibg=#e05f51    guifg=#ffffff
    endif

  endif
<

 vim: ft=help et sw=2 ts=2 sts=2 tw=79
