vim-qf-preview

A plugin for the quickfix and location list window to quickly preview the file under the cursor at the current quickfix location in a popup window.

Usage

Quickfix window mapping

To avoid conflicts with other plugins no default key mapping for opening the popup window is provided. You will first have to bind <plug>(qf-preview-open) to a key-sequence of your choice.

For example, to open the popup window with p, add the following to ~/.vim/after/ftplugin/qf.vim:

nmap <buffer> p <plug>(qf-preview-open)

Or alternatively, if you prefer to keep your plugin settings in your vimrc:

augroup qfpreview
    autocmd!
    autocmd FileType qf nmap <buffer> p <plug>(qf-preview-open)
augroup END

In the quickfix window navigate the cursor to the desired error and press p to preview the file at the current quickfix location in a popup window. The window is scrolled such that the buffer line with the error is at the top of the popup window.

Popup window mappings

The following default popup mappings are provided:

• Scroll up/down one text line: Ctrl-k, Ctrl-j
• Scroll to first/last line of displayed buffer: Shift-Home, Shift-End
• Scroll back to error line ("reset"): r
• Close the popup window: q, Ctrl-c

Configuration

b:qfpreview and g:qfpreview

The default popup key mappings and the appearance of the popup window can be configured through the variable b:qfpreview in after/ftplugin/qf.vim, or alternatively through the global variable g:qfpreview. The variable must be a dictionary containing any of the following entries:

Entry	Description	Default
top	Scroll to the first line of the buffer.	"\<S-Home>"
bottom	Scroll to the bottom of the buffer.	"\<S-End>"
scrollup	Scroll window up one text line.	"\<C-k>"
scrolldown	Scroll window down one text line.	"\<C-j>"
halfpageup	Scroll window up one half page.	none
halfpagedown	Scroll window down one half page.	none
fullpageup	Scroll window up one full page.	none
fullpagedown	Scroll window down one full page.	none
reset	Scroll window back to error line.	"r"
close	Close the popup window.	"q"
next	Navigate to next quickfix item in current list.	none
previous	Navigate to previous quickfix item in current list.	none
height	Number of text lines to display in the popup window.	15
offset	Number of buffer lines to show above the error line.	3
number	Enable the 'number' column in the popup window.	false
sign	Place a sign on the error line in the displayed buffer.¹	{linehl: 'CursorLine'}
matchcolumn	Highlight column of current quickfix item in popup window.	true

¹For valid sign attributes see :help qfpreview.sign and the examples below.

Highlighting

The highlighting of the popup window can be configured through the highlighting groups QfPreview, QfPreviewTitle, QfPreviewScrollbar, QfPreviewThumb and QfPreviewColumn. See :help qfpreview-highlight for more details.

Examples

1. Override the popup scrolling keys:

   vim9script
   g:qfpreview = {
       top: 'g',
       bottom: 'G',
       scrollup: 'k',
       scrolldown: 'j',
       halfpageup: 'u',
       halfpagedown: 'd',
       fullpageup: 'b',
       fullpagedown: 'f',
       next: 'n',
       previous: 'p'
   }

2. Instead of displaying a cursorline, display a sign in the 'signcolumn':

   g:qfpreview = {
       sign: {
           text: '>>',
           texthl: 'Search'
       }
   }

3. Same as 2., but also enable the 'number' column. In this case the placed sign is shown in the 'number' column:

   g:qfpreview = {
       number: true,
       sign: {
           text: '>>',
           texthl: 'Search'
       }
   }

Screenshots of default configuration, 2. and 3.:

Installation

Run the following commands in your terminal:

$ cd ~/.vim/pack/git-plugins/start
$ git clone https://github.com/bfrg/vim-qf-preview
$ vim -u NONE -c 'helptags vim-qf-preview/doc | quit'

Note: The directory name git-plugins is arbitrary, you can pick any other name. For more details see :help packages. Alternatively, use your favorite plugin manager.

License

Distributed under the same terms as Vim itself. See :help license.