dedicated buffers

Introduction
- Help
- Action
- Reload
- Quit
- Recall
- Wrapping up things
Selection
Filtering
Input history
Preview
- Follow mode
Folds
Non writable
Writable
Dedicated buffers ring
Layer ring
Menu
Context menus
- Navigation
Navigation

Introduction

Dedicated buffers allow you to perform Wheel operations intuitively, using full power of your editor : search, yank, paste, completion, and so on.

The available actions depend on the buffer type :

menu buffers allow you to launch a wheel function
navigation buffers allow you to go to a :
- location, circle or torus
- MRU file, locate file
- grep result
- and so on
reorganizing buffers allow you to
- rename locations, circles or toruses
- rename files
- reorder locations, circles or toruses
- move, copy or delete locations, circles and toruses
- perform fine grain operation
  - change locations settings like name, line, col
- reorganize tabs and windows
edit buffers allow you to
- edit grep results
- edit narrow of current file
- edit narrow of all circle files

Help

The key <F1> display a basic help.

The key <F2> displays local maps in a new layer. See layer ring.

Action

The main keys are :

<enter> : trigger the default action, close the dedicated buffer
g<enter> : trigger the default action, leave the dedicated buffer opened

Reload

Press r and the dedicated buffer will reload its content.

Available on most dedicated buffers.

Quit

Press q to quit the dedicated buffer.

Recall

When you quit a dedicated buffer, its window is closed but it's not lost : it's still there, hidden. You can recall it in a new split with <M-w><left> or <M-w><Right>. See buffer ring for more information.

Wrapping up things

In normal mode, the keys j/k and <up>/<down> wrap the buffer :

if on the first line, k or <up> will go to the last line
if on the last line, j or <down> will go to the first line

Selection

Some dedicated buffers will act on selected entries. You can hit :

<space> or = to toggle the selection of a line
# to invert the selection of all visible lines
* to select all visible lines
| to clear the selection of all visible lines

If a line is selected, it will begin with a distinctive marker.

You can open all selected files in tabs, splits or vertical splits.

Filtering

In most dedicated buffers, the first line is left almost empty, with just a prompt. In insert mode, it is used as an input line to filter all the other lines with each pattern you enter.

Going to filter line

In normal mode :

pressing i or a moves the cursor to the first line and starts insert mode
- same thing with <M-i> and <Ins>
pressing cc moves the cursor to the first line, starts insert mode and clears the line content, except the prompt

Reset filter

Pressing dd in normal mode clears the filter line, except the prompt, and show all unfiltered lines.

Update candidates

In insert mode, these keys updates the candidates :

<Space> : plain space
<C-w> : delete word before cursor
<C-u> : delete until beginning of line
<C-k> : delete until end of line
<Esc> : leave insert mode
<Enter> : leave insert mode

Note that <C-w> and <C-u> do not delete the prompt.

The key <C-c> is not mapped, in case you need to go to normal mode without triggering the filter function.

Movements

<M-f> : move forward one word
<M-b> : move backward one word
<C-a> : moves at the beginning of the line, just after the prompt
<C-e> : moves at the end of the line.

Patterns

A space between two patterns is a logical and. So, one two will display lines containing both one and two.

A pipe | between two patterns is a logical or. So, one|two will display lines containing one or two.

A bang ! beginning a filtering pattern is a logical not : all lines matching this pattern will be removed from the buffer.

Here, one and two can be any vim regex. Most of the time, they are simply part of the result you want.

For example, if you have the completion list small flower, big flower, small fruit and big fruit :

the pattern sm will narrow down to small flower, small fruit
the patterns sm fl will narrow down to small flower
the patterns all !ower will narrow down to small fruit
the patterns al|owe will narrow down to small flower, small fruit, big flower

Special keywords

Special filtering keywords are available :

=s or =selection : the filtered elements will belong to the current selection
!=s or !=selection : the filtered elements will not belong to the current selection

If small flower and big fruit are selected :

the pattern =s will narrow down to small flower, big fruit
the patterns =s fl will narrow down to small flower
the patterns =s bi will narrow down to big fruit
the patterns !=s bi will narrow down to big flower

Input history

An input history is available in the filter line. You can insert the previous/next input in insert mode with <Up>/<Down> or <M-p>/<M-n>.

The keys <PageUp>/PageDown or <M-r>/<M-s> will insert the previous/next input matching the beginning of the inserted line, until the cursor.

Preview

In navigation buffers, you can preview the buffer/location matching the cursor line with p. It is displayed in the previous window.

You can go back any time in the original buffer with o.

Follow mode

The key f enable the follow mode : the preview will then follow the cursor each time you press j or k.

It's a toggle key : press f again and the follow mode is disabled. You should go back automatically to the original buffer.

Folds

Some dedicated buffers use folding to reflect the treeish structure of the represented objects.

Filtering in these buffers will keep surrounding folds ; only non matching empty folds will be removed.

Main menu

In the main menu, each fold contains a category of actions.

Default map : <M-w>m

Wheel tree

The index/tree buffer use folds to reflect the tree structure of the Wheel : toruses, circles and locations.

Default map : <M-w><M-x>

Tabs & windows

The tabwin/tree buffer use folds to reflect the tree structure of tabs and windows in (neo)vim.

Default map : <M-w><M-v>

Non writable

Some dedicated buffers are not intended to be edited, except on the filter line.

The 'readonly' and 'nomodifiable' are set, except when you use the filter on the first line.

For example, navigation-only mandalas are non writable.

Writable

Some dedicated buffers are writable, i.e. they have a BufWriteCmd autocommand, triggered when you :write the buffer.

Saving such a buffer will reflect the changes on the objects represented by the buffer lines.

For instance, saving a rename/location buffer will rename the involved locations in the wheel.

Confirmation before writing

A confirmation is asked if you use :write, but not if you use the bang version :write!.

These buffer local maps are also defined :

<leader>w : equivalent to :write
<leader>W : equivalent to :write!

Be careful with :wall! though, for it would save without warning any modified writable mandala.

Prompt

To distinguish non-writable and writable dedicated buffers, the prompt are different. You can customize them, see prompt configuration

Filter

On most writable buffers, a filter line is available. In that case, some adjustement are made to the local maps, so that you can edit the buffer with the usual vim keys.

To access the filter line, press <M-i> or <Ins> instead of i and a.

The key dd is not mapped, use <M-d> to reset the filter.

To move to begin/end of filter line, use <M-a> and <M-e> instead of <C-a> and <C-e>.

The input history is available only with <M-p>/<M-n> and <M-r>/<M-s>.

Some keys have a distinct meaning if the cursor is on the first line or in another one.

On the first line :

<Enter>, <Esc>, <Space>, <C-w> and <C-u> update the filter
cc and <C-u> do not delete the prompt

On the other lines :

<Enter>, <Esc>, <Space> and <C-w> have their usual vim meaning
cc and <C-u> delete only the last field of the line

Range

If you use an ex command to perform an operation on all the visible lines of a buffer with filter functionality, don't forget to skip the first line.

E.g. :

2,$substiture/before/after/g
2,$sort

Pressed the wrong button ?

If something goes wrong, you can quit the dedicated buffer and :

re-read the wheel variables with <M-w>r, if your changes implied the wheel
undo your changes in the buffers, or quit (neo)vim without saving your files with :qa! if your changes implied files content

Anyway, it's always a good thing to do a backup :

of the wheel, with <M-w>w
of your files, or even better, to work within a VCS repository, like git

Dedicated buffers ring

Wheel manages a dedicated buffers ring. You can :

add a new dedicated buffer as default one with <M-w><Tab>
switch to another dedicated buffer with <M-w><M-Space>, completion is available
cycle the dedicated buffers with <M-w><home> (left) or <M-w><end> (right)
- reopens the current dedicated buffer in a new window if it is closed
change the buffer label with <M-n>
- displayed in dedicated buffer statusline, or in the echo area
- defaults to a unique buffer id
remove the current dedicated buffer with <M-w><Backspace>
- it is removed from the stack and wiped from vim buffers

When switching, you can complete by dedicated buffer labels & types, wich will lead you to the buffer you want. Example of completion candidates :

0 | index/tree 1 | history yank | yank/plain menu | menu/main

A wheel dedicated buffer is also called a mandala.

Layer ring

Each dedicated buffer has its own layer ring.

Each time you launch a wheel function involving a dedicated buffer, a new associated layer is added to a stack local to the buffer. You can see it as a kind of dedicated buffer history. You can :

go forward to the next layer by pressing <M-j>, or <M-Down>
go back to the previous layer by pressing <M-k>, or <M-Up>
switch to another layer with <M-l> or <C-Down>, completion is available
destroy current layer and go back to the previous one by pressing <Backspace>

0 | index/tree 1 | history 2 | yank/plain

The maximum size of the layer ring is determined by g:wheel_config.maxim.layers

So, there are two levels :

a dedicated buffer ring
a layer ring in each dedicated buffer

A layer in a dedicated buffer is also called a leaf.

wheel help
wheel status
save & load wheel file, session file
wheel navigation
native (neo)vim navigation (buffer, tab, window, marker, jump, change, tag, ...)
organize wheel
organize native (neo)vim elements (tabs, windows, ...)
refactoring
search file
search inside file
paste from yank ring
undo list
run a command and collect its output
layouts
- in tabs
- in windows
- in tabs & windows

Just open a fold to access its content.

Meta menu

Press <M-w>= to open the meta menu.

Hitting <Enter> on a line launches a sub-menu. Each sub-menu holds actions of the same category.

These categories are the same as in the main menu.

In these sub-menus, you can use the keys :

<Enter> : launch the action on the cursor line
g<Enter>, <Tab>, <Space> : launch action and leave the menu opened
<M-k> : leads you back to the meta menu
<Backspace> : back to the meta menu, delete submenu layer

Context menus

Some dedicated buffers have context menu support. In that case, pressing <tab> will open a menu where you can choose the action you want to apply to the selected or cursor line(s).

If you change your mind and wish to come back, just press <M-k> or <Backspace>.

Navigation

Context menu of a navigation buffer :

open selection
open in tab(s)
open in horizontal split(s)
open in vertical split(s)
open in horizontal golden split(s)
open in vertical golden split(s)

Navigation

The navigation buffers allow you to quickly switch to a Wheel location by pressing <enter> on the matching line. The buffer will be opened in previous used window. You can also use the keys :

t : open buffer in a new tab
s : open buffer in a new split
v : open buffer in a new vsplit
S : open buffer in a new split with golden ratio
V : open buffer in a new vsplit with golden ratio

Same keys as above, but leave the navigation buffer opened :