bindings - chimay/wheel Wiki

<!-- vim: set filetype=markdown: -->

Levels

The mappings are organized in levels :

  • level 0 : basic
  • level 1 : common
  • level 2 : advanced
  • level 10 : prefixless mappings

If you set the option g:wheel_config.mappings to an integer N, all mappings of level less or equal to N will be bound to keys. So, the higher this option, the more mappings available.

E.g., if you set it to 2 :

let g:wheel_config.prefix = 2

mappings levels 0, 1 and 2 will be available.

Level 1 or 2 is fine for most usages. Level 10 is interesting if you are looking for ideas of prefixless mappings. See the level 0 and subsequent for more information.

Prefix

Prefix for mappings of level 0, 1, 2 :

 let g:wheel_config.prefix = '<M-w>'

It's <M-w> by default.

In the following discussion, I assume that you have kept the default prefix.

Mnemonic

Most mappings respect the following convention :

  • prefix + letter : location operation
  • prefix + <C-letter> : circle operation
  • prefix + <S-letter> : torus operation
  • prefix + <M-letter> : alternative operation

Level 0

Menus

The most useful mapping to discover wheel functions is <M-w><M-m> : it launches a menu in a dedicated buffer, and from there you can trigger all sort of actions on the Wheel. See the dedicated buffers menus for more information.

Prefix + With default prefix Action
<M-m> <M-w><M-m> Main menu
= <M-w>= Meta menu

Info

Prefix + With default prefix Action
i <M-w>i Dashboard

Sync

Prefix + With default prefix Action
<M-$> <M-w><M-$> Sync up, follow current file
$ <M-w>$ Sync down, jump to location

Read / Write file

Prefix + With default prefix Action
r <M-w>r Load wheel file
w <M-w>w Save wheel in file
R <M-w>R Load session from file
W <M-w>W Save session to file

Next / previous

Prefix + With default prefix Action
<left> <M-w><left> Go to previous location
<right> <M-w><right> Go to next location
<C-left> <M-w><C-left> Go to previous circle
<C-right> <M-w><C-right> Go to next circle
<S-left> <M-w><S-left> Go to previous torus
<S-right> <M-w><S-right> Go to next torus

History

Prefix + With default prefix Action
<Up> <M-w><Up> Go to newer location in history
<Down> <M-w><Down> Go to older location in history
<C-Up> <M-w><C-Up> Go to newer location in circle
<C-Down> <M-w><C-Down> Go to older location in circle
<S-Up> <M-w><S-Up> Go to newer location in torus
<S-Down> <M-w><S-Down> Go to older location in torus
^ <M-w>^ Alternate menu
<C-^> <M-w><C-^> Alternate anywhere
<M-^> <M-w><M-^> Alternate in the same circle
<M-C-^> <M-w><M-C-^> Alternate in another circle of the same torus

Add

Prefix + With default prefix Action
a <M-w>a Add location to the current circle
<C-a> <M-w><C-a> Add circle to the current torus
A <M-w>A Add torus to the wheel
f <M-w>+f Add file
b <M-w>+b Add buffer
* <M-w>* Add files matching glob

Level 1

Switch

Prompting functions :

Prefix + With default prefix Action
<Enter> <M-w><Enter> Switch to location
<C-CR> <M-w><C-Enter> Switch to circle
<S-CR> <M-w><S-Enter> Switch to torus
<M-CR> <M-w><M-Enter> Switch to torus, circle & location
x <M-w>x Switch location in index
<C-x> <M-w><C-x> Switch circle in index
h <M-w>h Switch location in history
e <M-w>e Switch location in frecency

Dedicated buffers :

Prefix + With default prefix Action
<Space> <M-w><Space> Go to location
<C-Space> <M-w><C-Space> Go to circle
<S-Space> <M-w><S-Space> Go to torus
X <M-w>X Index of toruses > circles > locations
<M-x> <M-w><M-x> Treeish index with folds
<M-S-x> <M-w><M-S-x> Index of toruses > circles
<M-h> <M-w><M-h> Go to location in history
<M-e> <M-w><M-e> Go to location in frecency

Reorder

Prefix + With default prefix Action
@o <M-w>@o Reorder locations in current circle
@<C-o> <M-w>@<C-o> Reorder circles in current torus
@O <M-w>@O Reorder toruses in wheel

Rename

Prompting functions :

Prefix + With default prefix Action
n <M-w>n Rename current location
<C-n> <M-w><C-n> Rename current circle
N <M-w>N Rename current torus

Dedicated buffers :

Prefix + With default prefix Action
@n <M-w>@n Rename locations in current circle
@<C-n> <M-w>@<C-n> Rename circles in current torus
@N <M-w>@N Rename toruses in wheel

Delete

Prompting functions :

Prefix + With default prefix Action
d <M-w>d Delete current location
<C-d> <M-w><C-d> Delete current circle
D <M-w>D Delete current torus

Dedicated buffers :

Prefix + With default prefix Action
@d <M-w>@d Delete current location
@<C-d> <M-w>@<C-d> Delete current circle
@D <M-w>@D Delete current torus

Copy & Move

Prompting functions :

Prefix + With default prefix Action
c <M-w>c Copy current location
<M-c> <M-w><M-c> Copy current circle
C <M-w>C Copy current torus
m <M-w>m Move current location
M <M-w>M Move current circle

Dedicated buffers :

Prefix + With default prefix Action
@c <M-w>@c Copy or move locations in current circle
@<M-c> <M-w>@<M-c> Copy or move circles in current torus
@C <M-w>@C Copy or move toruses in wheel

Level 2

Buffers

Prompting functions :

Prefix + With default prefix Action
b <M-w>b Buffers (opened files)

Dedicated buffers :

Prefix + With default prefix Action
<M-b> <M-w><M-b> Buffers
<C-b> <M-w><C-b> All buffers, including unlisted ones

Tabs & windows

Visible buffers displayed in tabs & windows.

Prompting functions :

Prefix + With default prefix Action
v <M-w>v Switch to visible buffer

Dedicated buffers :

Prefix + With default prefix Action
<M-v> <M-w><M-v> Tree view of tabs & windows
<C-v> <M-w><C-v> Visible buffers in tabs & windows

Search for files

Prompting functions :

Prefix + With default prefix Action
f <M-w>f Find file in current directory tree
u <M-w>u Most recently used files not found in wheel

Dedicated buffers :

Prefix + With default prefix Action
<M-f> <M-w><M-f> Find file in current directory tree
&f <M-w>&f Search files with find in async mode
<M-u> <M-w><M-u> Most recently used files not found in wheel
l <M-w>l Search files with locate

Search inside files

Prompting functions :

Prefix + With default prefix Action
o <M-w>o Occur : search lines in current file

Dedicated buffer :

Prefix + With default prefix Action
<M-o> <M-w><M-o> Occur : search lines in current file
g <M-w>g Search in circle files with grep
<C-o> <M-w><C-o> Outline : folds, markdown, org mode

(Neo)vim lists

Prompting functions :

Prefix + With default prefix Action
single-quote <M-w>single-quote Markers
j <M-w>j Jumps
, <M-w>, Changes
t <M-w>t Tags

Dedicated buffers :

Prefix + With default prefix Action
<M-single-quote> <M-w><M-single-quote> Markers
<M-j> <M-w><M-j> Jumps
; <M-w>; Changes
<M-t> <M-w><M-t> Tags

Reorganizing buffers

Prefix + With default prefix Action
<M-r> <M-w><M-r> Reorganize wheel elements
<C-r> <M-w><C-r> Reorganize tabs & windows

Narrow

Prefix + With default prefix Action
-% <M-w>-% Narrow current file
-c <M-w>-c Narrow all circle files
<M-g> <M-w><M-g> Grep edit mode

Operator command, waiting for a move :

Prefix + With default prefix Action
-- <M-w>-- Narrow current file

Visual mode :

Prefix + With default prefix Action
-- <M-w>-- Narrow current file

Yank ring

Prompting functions :

Prefix + With default prefix Action
<C-y> <M-w><C-y> Switch default register to use in yank functions
y <M-w>y Yank ring prompt, linewise after
p <M-w>p Yank ring prompt, charwise after
Y <M-w>Y Yank ring prompt, linewise before
P <M-w>P Yank ring prompt, charwise before

Dedicated buffers :

Prefix + With default prefix Action
<M-y> <M-w><M-y> Yank ring in plain mode
<M-p> <M-w><M-p> Yank ring in list mode

Undo

Prefix + With default prefix Action
<C-u> <M-w><C-u> Undo list

Command output buffer

Prefix + With default prefix Action
: <M-w>: Display ex or !shell output
& <M-w>& Async sheel command

Managing dedicated buffers

Prefix + With default prefix Action
<Tab> <M-w><Tab> Add new dedicated buffer
<Backspace> <M-w><Backspace> Delete dedicated buffer
<M-Home> <M-w><M-Home> Cycle dedicated buffers, leftward
<End> <M-w><End> Cycle dedicated buffers, rightward
<Up> <M-w><Up> Switch to another dedicated buffer

Layouts

You can display all locations of the current circle, one location per tab or window. Same idea with circles and toruses.

Available layouts are : horizontal or vertical split, main top, main left, grid.

You can also display one circle per tab, and one location per window, or one torus per tab and one circle per window.

Note that all layout mappings use the subprefix z, so all layout maps begin with <M-w>z.

Prefix + With default prefix Action
zz <M-w>zz Zoom : one tab, one window
zt <M-w>zt One location per tab
z<C-t> <M-w>z<C-t> One circle per tab
zT <M-w>zT One torus per tab
zs <M-w>zs Locations in horizontal splits
z<C-s> <M-w>z<C-s> Circles in horizontal splits
zS <M-w>zS Toruses in horizontal splits
zv <M-w>zv Location in vertical splits
z<C-v> <M-w>z<C-v> Circles in vertical splits
zV <M-w>zV Toruses in vertical splits
zm <M-w>zm Locations in main top layout
z<C-m> <M-w>z<C-m> Circles in main top layout
zM <M-w>zM Toruses in main top layout
zl <M-w>zl Locations in main left layout
z<C-l> <M-w>z<C-l> Circles in main left layout
zL <M-w>zL Toruses in main left layout
zg <M-w>zg Locations in grid layout
z<C-g> <M-w>z<C-g> Circles in grid layout
zG <M-w>zG Toruses in grid layout
z& <M-w>z& Circles in tabs, locations in windows
z<M-&> <M-w>z<M-&> Toruses in tabs, circles in windows
z<up> <M-w>z<up> Rotate windows counter-clockwise
z<down> <M-w>z<down> Rotate windows clockwise

Level 10

The level 10 offers mappings without prefix for the most used wheel functions. You can set the mapping level to 10 to activate them, or adapt them to your taste and add them to your init file.

Maps table

Mapping Action
<M-=> Meta menu
<M-m> Main menu
<M-i> Wheel dashboard : torus > circle > location
<M-$> Sync up : find closest wheel location
<C-$> Sync down : jump to current location
<M-PageUp> Go to previous location
<M-PageDown> Go to next location
<C-PageUp> Go to previous circle
<C-PageDown> Go to next circle
<S-PageUp> Go to previous torus
<S-PageDown> Go to next torus
<M-Enter> Prompt for a location to switch to
<C-Enter> Prompt for a circle to switch to
<S-Enter> Prompt for a torus to switch to
<M-Space> Choose location in dedicated buffer
<C-Space> Choose circle in dedicated buffer
<S-Space> Choose torus in dedicated buffer
<M-x> Prompt for a location in index to switch to
<M-S-x> Index of toruses > circles > locations
<M-C-x> Choose element in wheel folding tree
<M-Home> Go to newer location in history
<M-End> Go to older location in history
<C-Home> Go to newer location in same circle
<C-End> Go to older location in same circle
<S-Home> Go to newer location in same torus
<S-End> Go to older location in same torus
<M-h> History in prompt
<M-C-h> History in dedicated buffer
<C-^> Alternate last two locations
<M-^> Alternate in the same circle
<M-C-^> Alternate in another circle of the same torus
<M-e> Frecency in prompt
<M-C-e> Frecency in dedicated buffer
<M-b> Buffers, prompting function
<M-C-b> Buffers, dedicated buffer
<M-S-b> All buffers, including unlisted ones
<M-v> Go to tab & window, prompt mode
<M-C-v> Tabs & windows in tree mode, dedicated buffer
<M-S-v> Tabs & windows, dedicated buffer
<M-'> Markers, prompting function
<M-k> Markers, prompting function
<M-j> Jumps, prompting function
<M-,> Changes, prompting function
<M-t> Tags, prompting function
<M-C-k> Markers, dedicated buffer
<M-C-j> Jumps, dedicated buffer
<M-;> Changes, dedicated buffer
<M-C-t> Tags, dedicated buffer
<M-Insert> Add location to the current circle
<M-Del> Delete current location
<M-r> Reorganize wheel elements
<M-C-r> Reorganize tabs and windows
<M-C-g> Grep in edit mode
<M-n> Narrow current file
<M-C-n> Narrow all circle files
<M-f> Find, prompting function
<M-C-f> Find, dedicated buffer
<M-C-&> Async find
<M-u> Most Recently Used files not found in wheel
<M-l> Locate
<M-o> Occur in current file, prompting function
<M-C-o> Occur in current file, dedicated buffer
<M-g> Grep in current circle files
<M-S-o> Outline in current circle files
<M-y> Paste yank ring element linewise, after cursor
<M-p> Paste yank ring element charwise, after cursor
<M-S-y> Paste yank ring element linewise, before cursor
<M-S-p> Paste yank ring element charwise, before cursor
<M-C-y> Yank ring dedicated buffer in plain mode
<M-C-p> Yank ring dedicated buffer in list mode
<M-S-u> Undo list
<M-!> Buffer with output of ex or shell command
<M-&> Async shell command in dedicated buffer
<M-Tab> Add a new dedicated buffer
<M-Backspace> Delete current dedicated buffer
<M-Left> Cycle dedicated buffers, leftward
<M-Right> Cycle dedicated buffers, rightward
<C-Up> Switch dedicated buffer
<M-z> Zoom : one tab, one window

Excerpt of maps definition in centre.vim

Below is the default level 10. To customize it, first set your mapping level to less than 10, then copy and adapt the following lines :

let nmap = 'nmap <silent>'
let vmap = 'vmap <silent>'
" Menus
exe nmap '<m-m>          <plug>(wheel-menu-main)'
exe nmap '<m-=>          <plug>(wheel-menu-meta)'
" Sync
exe nmap '<m-i>          <plug>(wheel-dashboard)'
exe nmap '<m-$>          <plug>(wheel-sync-up)'
exe nmap '<c-$>          <plug>(wheel-sync-down)'
" ---- navigate in the wheel
" --  next / previous
exe nmap '<m-pageup>   <plug>(wheel-previous-location)'
exe nmap '<m-pagedown> <plug>(wheel-next-location)'
exe nmap '<c-pageup>   <plug>(wheel-previous-circle)'
exe nmap '<c-pagedown> <plug>(wheel-next-circle)'
exe nmap '<s-pageup>   <plug>(wheel-previous-torus)'
exe nmap '<s-pagedown> <plug>(wheel-next-torus)'
" -- switch
exe nmap '<m-cr>        <plug>(wheel-prompt-location)'
exe nmap '<c-cr>        <plug>(wheel-prompt-circle)'
exe nmap '<s-cr>        <plug>(wheel-prompt-torus)'
exe nmap '<m-space>     <plug>(wheel-dedibuf-location)'
exe nmap '<c-space>     <plug>(wheel-dedibuf-circle)'
exe nmap '<s-space>     <plug>(wheel-dedibuf-torus)'
" -- index
exe nmap '<m-x>         <plug>(wheel-prompt-index)'
exe nmap '<m-s-x>       <plug>(wheel-dedibuf-index)'
exe nmap '<m-c-x>       <plug>(wheel-dedibuf-index-tree)'
" -- history
exe nmap '<m-home>      <plug>(wheel-history-newer)'
exe nmap '<m-end>       <plug>(wheel-history-older)'
exe nmap '<c-home>      <plug>(wheel-history-newer-in-circle)'
exe nmap '<c-end>       <plug>(wheel-history-older-in-circle)'
exe nmap '<s-home>      <plug>(wheel-history-newer-in-torus)'
exe nmap '<s-end>       <plug>(wheel-history-older-in-torus)'
exe nmap '<m-h>         <plug>(wheel-prompt-history)'
exe nmap '<m-c-h>       <plug>(wheel-dedibuf-history)'
" -- alternate
exe nmap '<c-^>          <plug>(wheel-alternate-anywhere)'
exe nmap '<m-^>          <plug>(wheel-alternate-same-circle)'
exe nmap '<m-c-^>        <plug>(wheel-alternate-same-torus-other-circle)'
" -- frecency
exe nmap '<m-e>         <plug>(wheel-prompt-frecency)'
exe nmap '<m-c-e>       <plug>(wheel-dedibuf-frecency)'
" ---- navigate with vim native tools
" -- buffers
exe nmap '<m-b>          <plug>(wheel-prompt-buffer)'
exe nmap '<m-c-b>        <plug>(wheel-dedibuf-buffer)'
exe nmap '<m-s-b>        <plug>(wheel-dedibuf-buffer-all)'
" -- tabs & windows : visible buffers
exe nmap '<m-v>          <plug>(wheel-prompt-tabwin)'
exe nmap '<m-c-v>        <plug>(wheel-dedibuf-tabwin-tree)'
exe nmap '<m-s-v>        <plug>(wheel-dedibuf-tabwin)'
" -- (neo)vim lists
exe nmap "<m-'>          <plug>(wheel-prompt-marker)"
exe nmap "<m-k>          <plug>(wheel-prompt-marker)"
exe nmap '<m-j>          <plug>(wheel-prompt-jump)'
exe nmap '<m-,>          <plug>(wheel-prompt-change)'
exe nmap '<m-c>          <plug>(wheel-prompt-change)'
exe nmap '<m-t>          <plug>(wheel-prompt-tag)'
exe nmap "<m-c-k>        <plug>(wheel-dedibuf-marker)"
exe nmap '<m-c-j>        <plug>(wheel-dedibuf-jump)'
exe nmap '<m-;>          <plug>(wheel-dedibuf-change)'
exe nmap '<m-c-t>        <plug>(wheel-dedibuf-tag)'
" ---- organize the wheel
exe nmap '<m-insert>     <plug>(wheel-prompt-add-here)'
exe nmap '<m-del>        <plug>(wheel-prompt-delete-location)'
exe nmap '<m-r>          <plug>(wheel-dedibuf-reorganize)'
" ---- organize other things
exe nmap '<m-c-r>        <plug>(wheel-dedibuf-reorg-tabwins)'
" ---- refactoring
exe nmap '<m-c-g>        <plug>(wheel-dedibuf-grep-edit)'
exe nmap '<m-n>          <plug>(wheel-dedibuf-narrow-operator)'
exe vmap '<m-n>          <plug>(wheel-dedibuf-narrow)'
exe nmap '<m-c-n>        <plug>(wheel-dedibuf-narrow-circle)'
" ---- search
" -- files
exe nmap '<m-f>          <plug>(wheel-prompt-find)'
exe nmap '<m-c-f>        <plug>(wheel-dedibuf-find)'
exe nmap '<m-c-&>        <plug>(wheel-dedibuf-async-find)'
exe nmap '<m-u>          <plug>(wheel-prompt-mru)'
exe nmap '<m-c-u>        <plug>(wheel-dedibuf-mru)'
exe nmap '<m-l>          <plug>(wheel-dedibuf-locate)'
" -- inside files
exe nmap '<m-o>          <plug>(wheel-prompt-occur)'
exe nmap '<m-c-o>        <plug>(wheel-dedibuf-occur)'
exe nmap '<m-g>          <plug>(wheel-dedibuf-grep)'
exe nmap '<m-s-o>        <plug>(wheel-dedibuf-outline)'
" ---- yank ring
exe nmap '<m-y>          <plug>(wheel-prompt-yank-plain-linewise-after)'
exe nmap '<m-p>          <plug>(wheel-prompt-yank-plain-charwise-after)'
exe nmap '<m-s-y>        <plug>(wheel-prompt-yank-plain-linewise-before)'
exe nmap '<m-s-p>        <plug>(wheel-prompt-yank-plain-charwise-before)'
exe nmap '<m-c-y>        <plug>(wheel-dedibuf-yank-plain)'
exe nmap '<m-c-p>        <plug>(wheel-dedibuf-yank-list)'
" ---- undo list
exe nmap '<m-s-u>        <plug>(wheel-dedibuf-undo-list)'
" ---- ex or shell command output
exe nmap '<m-!>          <plug>(wheel-dedibuf-command)'
exe nmap '<m-&>          <plug>(wheel-dedibuf-async)'
" ---- dedicated buffers
exe nmap '<m-tab>        <plug>(wheel-mandala-add)'
exe nmap '<m-backspace>  <plug>(wheel-mandala-delete)'
exe nmap '<m-left>       <plug>(wheel-mandala-backward)'
exe nmap '<m-right>      <plug>(wheel-mandala-forward)'
exe nmap '<c-up>         <plug>(wheel-mandala-switch)'
" ---- layouts
exe nmap '<m-z>          <plug>(wheel-zoom)'

Trouble with xterm & fixkey

If you use vim in a xterm with the fixkey plugin, the map <M-S-p> can cause a strange in the empty buffer at startup. To avoid it, add :

let g:Fixkey_setupDelay = 500

to your vimrc.

Level 20

For debugging only.

Prefix + With default prefix Action
Z <M-w>Z Reset wheel variables to empty wheel

Define your own maps

The recommended approach is to use plug maps. Example :

nmap <silent> <M-m> <Plug>(wheel-menu-main)

Plug maps are middle men between wheel autoload functions and user mappings, so you have to use recursive maps. The above example would not work with :nnoremap.

You can also use the meta-command :

nnoremap <silent> <M-m> :Wheel dedibuf menu-main<cr>

In that case, no need for a recursive map.

Exhaustive list

In the menus

In the help submenu of the main or meta menu, you have access to :

  • the list of current wheel mappings
  • the list of available plugs mappings

You can then browse them in a dedicated wheel buffer. It is only a command output collector though, you can't launch any map from there.

Plugs

You can find an exhaustive list of plugs maps in :

:help wheel-mappings-exhaustive-list

Other ideas

Some maps that you may find useful if the super key <D-*> bindings work in your setup :

" index of locations in torus > circle > location format
nmap <silent> <d-x>       <plug>(wheel-dedibuf-index)
" index of locations, open in new tab
nmap <silent> <d-cr>      <cmd>call wheel#vortex#helix('tab')<cr>

" history
nmap <silent> <d-h>       <plug>(wheel-dedibuf-history)
" alternate
nmap <silent> <d-^>       <plug>(wheel-alternate-other-torus)
" frecency
nmap <silent> <d-e>       <plug>(wheel-dedibuf-frecency)

" visible buffers in tabs & windows
nmap <silent> <d-v>       <plug>(wheel-dedibuf-tabwin)

nmap <silent> <d-o>       <plug>(wheel-dedibuf-occur)
nmap <silent> <d-b>       <plug>(wheel-dedibuf-buffer-all)
nmap <silent> <d-k>       <plug>(wheel-dedibuf-markers)
nmap <silent> <d-j>       <plug>(wheel-dedibuf-jumps)
nmap <silent> <d-c>       <plug>(wheel-dedibuf-changes)
nmap <silent> <d-t>       <plug>(wheel-dedibuf-tag)

" narrow
nmap <silent> <d-n>       <plug>(wheel-dedibuf-narrow-operator)
vmap <silent> <d-n>       <plug>(wheel-dedibuf-narrow)

" yank ring
nmap <silent> <d-y>       <plug>(wheel-dedibuf-yank-plain)
nmap <silent> <d-p>       <plug>(wheel-dedibuf-yank-list)

" undo list
nmap <silent> <d-u>       <plug>(wheel-dedibuf-undo-list)

" reorganize tabs & windows (visible buffers)
nmap <silent> <d-r> <plug>(wheel-reorg-tabwins)

" next/previous dedicated buffer
nmap <silent> <d-space>   <plug>(wheel-mandala-forward)
nmap <silent> <d-s-space> <plug>(wheel-mandala-backward)

" k on the beginning of the buffer -> end
nmap <silent> k :call wheel#mandala#wrap_up()<cr>
" j on the end of the buffer -> beginning
nmap <silent> j :call wheel#mandala#wrap_down()<cr>

" clear search highlight and center the cursor with Fibonacci ratio
nmap <silent> <c-l> :nohlsearch<cr><plug>(wheel-spiral-cursor)
" same in insert mode
imap <silent> <c-l> <esc>:nohlsearch<cr><plug>(wheel-spiral-cursor)a
⚠️ **GitHub.com Fallback** ⚠️