step by step

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

• Prefix
• One map to ring them all
• One command to launch them all
• First circles
  • Adding quicker
• Moving around
  • Cycling
  • Switching
  • Switching using a dedicated buffer
• Alternate : square the circle
• Tags

Prefix

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

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

One map to ring them all

To get an overview of the Wheel, I suggest you take a look at the main menu. Press <M-w><M-m> and a new buffer will appear, listing the actions you can perform. Insert mode is used to filter the lines. Press enter in normal mode to trigger an action (if you know what you’re doing), or q to quit the menu.

To learn more about menus, see the dedicated buffers menus.

One command to launch them all

The :Wheel command can be used to launch any wheel functionality. The general syntax is :

:Wheel {subcommand}
" or
:Wheel {subcommand} {action}

To see all possibilities, just hit tab after a space, e.g. :

:Wheel <tab>
" or
:Wheel {subcommand} <tab>

For example, you can use :

:Wheel dedibuf menu-main

to launch the main menu.

First circles

Let’s say we have the files Juice, Tea, Coffee and we want to group them. So, we go to Juice and type <M-w>a to add a location to the wheel. If no category (no torus) is present in the wheel, it will create it and ask for a name. Let’s say we name it Food. If no group (no circle) is found in the torus, it will be created and prompt for a name. Let’s say we choose Drinks. Finally, our file Juice is added to the group. Its name is the filename without extension by default.

Then, we go to Tea and type <M-w>a again. This time, it will just ask us if we want to keep the default location name. Press enter, and Tea is added to the Drinks group.

Same process with Coffee. We now have a circle Drink containing three files.

A group can contain more than one location of the same file. Suppose that in the Juice file, you have a Pineapple and a Mango sections, and you want to add both of them in the circle. Just go to the Pineapple section, and use <M-w>a ; we give it the Juice-Pineapple name. The location Juice:pineapple-line:pineapple-col is added to the current circle. Then, go to the Mango section, and do the same. Let's say we give it the Juice-Mango name. The Juice:mango-line:mango-col is also added to the circle.

If you want to create another group (circle), let’s say Fruits, simply launch <M-w><C-a>, and answer Fruits to the prompt. You can then add the files Apple, Pear and Orange to it. You can even also add Juice: a file can be added to more than one circle.

If you want to create another category (torus), let’s say Books, simply launch <M-w><S-a>, and answer Books to the prompt.

Adding quicker

If you want to edit a file and add it at the same time, you can use <M-w>+f ; a file completion is available at the prompt. This map can also be used to edit a new file and add it to the wheel at once.

If you want to add a buffer, you can use <M-w>+b ; a buffer completion is available.

What happens if you have a lot of files ? Let's say the novels folder, located in the current directory, contains dozen of novels in plain text format. You can add all of them at once with the add_glob function. Press <M-w>* and wheel will ask you to enter a glob pattern. You can answer novels/* to add all files in there. If there are more levels of subdirs and you want to include all of them, you can enter novels/**/* instead. Then, it will ask if you want to add the files in a new circle. You can answer yes and call this circle Novels. And voilà, your new Novels group contain all the files in the novels folder.

Moving around

Cycling

You can cycle the files of a circle with <M-w><Left> and <M-w><Right>. These are often used bindings, so I suggest you map them to more convenient keys, like <C-PageUp> and <C-PageDown>. See the level 10 mappings.

To cycle the circles, use <M-w><C-Left> and <M-w><C-Right>. You can also map them to more convenient keys, like <C-Home> and <C-End>.

To cycle the toruses, use <M-w><S-Left> and <M-w><S-Right> or map them to <S-Home> and <S-End>.

Switching

You can also switch wheel element by name :

• <M-w><Enter> : switch location by name
• <M-w><C-Enter> : switch circle by name
• <M-w><S-Enter> : switch torus by name

A completion is available, see completion.

Let's say you have these entries in the wheel :

torus	circle	location
config	browser	w3m
config	browser	elinks
config	browser	qutebrowser
config	edit	vim
config	edit	neovim
config	edit	emacs
script	shell	autostart
script	shell	autostop

If you launch the "switch in index" action with <M-w>x, and pre-fill the prompt with "ed vi" before hitting <tab>, the plugin will give you this completion candidates :

• config > edit > vim
• config > edit > neovim

If you pre-fill the prompt with "ed vi neo" before hitting <tab>, the plugin will only give you "config > edit > neovim".

As usual, hit enter to validate you choice.

Switching using a dedicated buffer

You can also switch location, circle or torus by chosing it in a wheel navigation buffer. In this buffer, filtering is available, on top of all your favorite (neo)vim commands. See the navigation buffers.

Alternate : square the circle

Over time, the number of circles will grow. Completion is great, but if you just want to alternate the last two locations in history, you’ll probably prefer the alternate functions :

Default map	Function
<M-w><C-^>	alternate anywhere
<M-w><M-^>	alternate in the same circle
<M-w><M-C-^>	alternate in in same torus but another circle
<M-w>^	alternate menu

I strongly suggest you map a convenient key, like <C-^>, to alternate-anywhere, it's one of the most often used binding. Same thing with <M-C-^> and alternate-same-torus-other-circle.

A common case is to alternate two files in the same circle, and two circles in the same torus. So, you have the square :

Alternate	File 1	File 2
Circle Drinks	Juice	Tea
Circle Fruits	Apple	Pear

at your fingertips.

Tags

If you use a tags file, you can jump to any tag with <M-w>t. Completion is available at the prompt.

For instance, pro fol<tab> gives me the function wheel#projection#follow straight away. Warp speed, Scotty.

You can also search for a tag in a dedicated buffer with <M-w><M-t>.

There are also functions for native vim list, like marks, jumps or changes. See the switching prompting functions.