Preface

This plugin solves a series of user experience problems in vim's preview window and provide a handy way to preview tags, files and function signatures.

Note: Active development on this plugin has stopped. The only future changes will be bug fixes.

Please see vim-quickui.

Installation

Plug 'skywind3000/vim-preview'

Commands

vim-preview introduces several commands:

Command	Arguments	Description
PreviewTag	[tagname]	Display the tag in the preview window circularly
PreviewFile	[+cmd] filename	Display the file in the preview window
PreviewClose	N/A	Close the preview window
PreviewGoto	command	Open the previewing file in a non-preview window
PreviewScroll	offset	Scroll preview window without leaving current window or inser mode
PreviewQuickfix	[linenr]	Preview file in quickfix list
PreviewSignature	[function name]	Preview the function signature circularly in the command line

PreviewTag

This command can display tag definition in the preview window circularly:

PreviewTag [tagname]

When the first argument tagname is not provided, current word under cursor is chosen as the tag name.

Every body uses a wide-screen display today, but the default preview window can still only be opened in a new split above or below current window. vsplit is usually better than split when you are working with a 16:9 LCD.

:PreviewTag command will open the preview window on your favorite position (right by default), and the tag name will be highlighted.

Previously, when we got multiple matches, CTRL+] or CTRL+W } will display a list:

	 nr pri kind tag		file
	  1 F	f    mch_delay		os_amiga.c
			mch_delay(msec, ignoreinput)
	> 2 F	f    mch_delay		os_msdos.c
			mch_delay(msec, ignoreinput)
	  3 F	f    mch_delay		os_unix.c
			mch_delay(msec, ignoreinput)
	Enter nr of choice (<CR> to abort):

And you have to choose one of them, this is very annoying and disturbing when you are focusing on editing or navigating the sources.

You don't need to care about this anymore when you use :PreviewTag with a new tag name, the first match will be displayed in the preview window, execute :PreviewTag with the same tag name again, the next match will be used. If there is no more result, the first one is used again.

When you get multiple matches, the current match will be displayed in the command line. (1/2) represents there are two tags matched and this is the first one. Assume that you bind :PreviewTag to F3, all your need is move the cursor on an identifier and repeatly press F3, and all the matches will be displayed on the right preview window circularly.

In the past, scrolling the preview window may involve mode change and window switching. If the preview window is not height enough to view the whole function implementation, you must jump to the preview window press CTRL+F to scroll down then jump back. Leaving and Re-entering insert mode may also be required.

noremap <m-u> :PreviewScroll -1<cr>
noremap <m-d> :PreviewScroll +1<cr>
inoremap <m-u> <c-\><c-o>:PreviewScroll -1<cr>
inoremap <m-d> <c-\><c-o>:PreviewScroll +1<cr>

With the keymaps above, you can use <m-u> and <m-d> directly to scroll preview window without switching window or leaving insert mode.

When you are done, press CTRL+w z to close the preview window or :PreviewGoto to open the previewing file and location in a non-preview window.

PreviewFile

Open arbitrary file in the preview window:

PreviewFile [++opt] [+cmd] filename

Just like PreviewTag but preview a given file, the +cmd could be any vim command which will be executed after opening the file. For example:

PreviewFile +:10 ~/.vimrc

This will open .vimrc in the preview window and jump to line 10.

PreviewFile ++nohl +:10 ~/.vimrc

This will do the same without highlighting line 10.

PreviewGoto

When you want to open the current previewing tag in a non-preview window you can use:

PreviewGoto action

The action can be either edit, split, vsplit or tabe.

PreviewClose

Close the preview window

PreviewClose

A command version of CTRL+W z.

PreviewQuickfix

This command can preview files listed in quickfix window without opening it directly.

PreviewQuickfix [linenr]

The [linenr] parameter is the line number in the quickfix window. The current line number in the quickfix window will be taken if it is not provided.

autocmd FileType qf nnoremap <silent><buffer> p :PreviewQuickfix<cr>
autocmd FileType qf nnoremap <silent><buffer> P :PreviewClose<cr>

We can have the above keymap in quickfix window for convenience.

Now we switch to quickfix window and press p, the item under cursor will be displayed in the preview window immediately, then move around the cursor choose another item and press p again, all files is displayed in the same preview window.

It will not open new split or switch away your current buffer no matter what switchbuf is. When you finished, just use P (upper case) or CTRL+W z to close the preview window.

PreviewSignature

Preview the function signature circularly in the command line:

PreviewSignature[!] [function name]

If the function name is not provided, current word under cursor will be taken as function name. If bang ! sign is given, the nearest function name to the cursor position is chosen.

Function signature is displayed at the bottom including file name and line number. Execute PreviewSignature again, the next signature will be displayed if there are multiple matches, just like PreviewTag.

Calling PreviewSignature without any argument will use the current word under cursor as the function name and PreviewSignature! will find a function name closest to the cursor position.

The bang sign is very useful, think that:

printf(<cursor position>

When you input printf( and you can't remember the parameters, you can execute PreviewSignature! directly in the insert mode. The cursor is on the right side of left paren the function name printf is on the left side, but with the bang sign, function name printf can be find out because it is the nearest function name to the cursor position.

Now we have the below setting:

noremap <F4> :PreviewSignature!<cr>
inoremap <F4> <c-\><c-o>:PreviewSignature!<cr>

Then we can have F4 to display the signature of printf even if we typed a (. And signatures can be displayed automatically by using CursorMovedI autocommands or remapping ( in insert mode.

F4 can be pressed multiple times until you find the right signature when you got multiple results. Remember to set noshowmode before this, displaying signature in insert mode requires turn off showmode option.

Requirements

When you are generating tags file, the n and S fields are required:

ctags --fields=+nS

n will tell ctags add a line number filed in each tag record and S means including function signatures.

vim-preview can work fine without these two fields but it can't tell you line number in the command line and it will guess the function signature which may get an incorrect result sometimes.

Tips

Don't generate tags file manually, use some tags manager like gutentags and gen_tags. They will take good care of your tags files.

When you are using Language Servers with LanguageClient-neovim, You can use PreviewFile to preview definition instead of jump to it:

call LanguageClient#textDocument_definition({'gotoCmd':'PreviewFile'})

Your current buffer will not be switched away, and just close the preview window by CTRL+W z when you are done.