README.markdown

vim-wheel

Screen-anchored cursor movement for Vim

---

---

Features

This plugin merges the standard cursor movement of j and k with the scrolling of <CTRL-E> and <CTRL-Y> to produce a new screen-anchored cursor movement. This roughly emulates movement when using a trackpad or scroll wheel.

• By default, two keys are mapped: <CTRL-J> (like j) moves towards the end of buffer and <CTRL-K> (like k) move towards its beginning
• Movement is tied to trackpad/scroll wheel for ‘natural’ scrolling
• Due to Vim’s inherent jumpiness with wrap enabled, you have option to degrade to gj and gk (more details below)
• Supports Visual selection
• Pure Vimscript with no dependencies

Installation

You can install using your favorite Vim package manager. (E.g., Pathogen, Vundle, or Plug.) If you are using a recent version of vim or neovim, you can also use native package support. (See :help packages.)

Configuration

You can change the behavior of this plugin in your .vimrc:

For instance, the default mappings of:

let g:wheel#map#up   = '<c-k>'
let g:wheel#map#down = '<c-j>'

...can be changed to use the Command key in MacVim:

let g:wheel#map#up   = '<D-k>'
let g:wheel#map#down = '<D-j>'

If you have any existing mappings to <c-k> or <c-j>, they will be preserved.

Trackpad/Scroll wheel behavior

By default the scroll behavior of the mouse will reflect this new behavior. You can disable in your .vimrc if not desired.

• Natural - content tracks finger movement on trackpad
• Reverse - swiping down moves content up

let g:wheel#map#mouse = 1       " 1=natural, 0=disable, -1=reverse

End of buffer threshold

wheel’s scrolling will cease when cursor nears the start or end of the buffer, degrading to gj and gk. You can adjust this threshold in your .vimrc:

let g:wheel#line#threshold = 5      " lines from start or end

Behavior with wrap

With large blocks of wrapped text, Vim’s native scrolling with CTRL-E and CTRL-Y can be jumpy. wheel inherits this behavior, unfortunately. If you would prefer that wheel degrade to gj and gk when wrap is on, you can disable the anchored scrolling in your .vimrc:

let g:wheel#scroll_on_wrap = 1      " 0=disable, 1=enable (default)

See also

If you find this plugin useful, check out these others originally by @reedes:

• vim-colors-pencil - color scheme for Vim inspired by IA Writer
• vim-lexical - building on Vim’s spell-check and thesaurus/dictionary completion
• vim-litecorrect - lightweight auto-correction for Vim
• vim-pencil - Rethinking Vim as a tool for writers
• vim-textobj-quote - extends Vim to support typographic (‘curly’) quotes
• vim-textobj-sentence - improving on Vim's native sentence motion command
• vim-thematic - modify Vim’s appearance to suit your task and environment
• vim-wordy - uncovering usage problems in writing
• vim-wordchipper - power tool for shredding text in Insert mode

Future development

There’s an experimental horizontal scrolling movement hidden within for those who wish to try it out.

If you’ve spotted a problem or have an idea on improving this plugin, please post it to the GitHub project issue page.