diff options
Diffstat (limited to 'runtime/doc/quickfix.txt')
-rw-r--r-- | runtime/doc/quickfix.txt | 56 |
1 files changed, 55 insertions, 1 deletions
diff --git a/runtime/doc/quickfix.txt b/runtime/doc/quickfix.txt index 7f7f10fac..d4ebf5c48 100644 --- a/runtime/doc/quickfix.txt +++ b/runtime/doc/quickfix.txt @@ -15,6 +15,7 @@ This subject is introduced in section |30.1| of the user manual. 7. The error format |error-file-format| 8. The directory stack |quickfix-directory-stack| 9. Specific error file formats |errorformats| +10. Customizing the quickfix window |quickfix-window-function| The quickfix commands are not available when the |+quickfix| feature was disabled at compile time. @@ -1921,6 +1922,59 @@ error messages into a format that quickfix mode will understand. See the start of the file about how to use it. (This script is deprecated, see |compiler-perl|.) - +============================================================================= +10. Customizing the quickfix window *quickfix-window-function* + +The default format for the lines displayed in the quickfix window and location +list window is: + + <filename>|<lnum> col <col>|<text> + +The values displayed in each line correspond to the "bufnr", "lnum", "col" and +"text" fields returned by the |getqflist()| function. + +For some quickfix/location lists, the displayed text need to be customized. +For example, if only the filename is present for a quickfix entry, then the +two "|" field separator characters after the filename are not needed. Another +use case is to customize the path displayed for a filename. By default, the +complete path (which may be too long) is displayed for files which are not +under the current directory tree. The file path may need to be simplified to a +common parent directory. + +The displayed text can be customized by setting the 'quickfixtextfunc' option +to a Vim function. This function will be called with a dict argument for +every entry in a quickfix or a location list. The dict argument will have the +following fields: + + quickfix set to 1 when called for a quickfix list and 0 when called for + a location list. + id quickfix or location list identifier + idx index of the entry in the quickfix or location list + +The function should return a single line of text to display in the quickfix +window for the entry identified by idx. The function can obtain information +about the current entry using the |getqflist()| function and specifying the +quickfix list identifier "id" and the entry index "idx". + +If a quickfix or location list specific customization is needed, then the +'quickfixtextfunc' attribute of the list can be set using the |setqflist()| or +|setloclist()| function. This overrides the global 'quickfixtextfunc' option. + +The example below displays the list of old files (|v:oldfiles|) in a quickfix +window. As there is no line, column number and error text information +associated with each entry, the 'quickfixtextfunc' function returns only the +filename. +Example: > + " create a quickfix list from v:oldfiles + call setqflist([], ' ', {'lines' : v:oldfiles, 'efm' : '%f', + \ 'quickfixtextfunc' : 'QfOldFiles'}) + func QfOldFiles(info) + " get information about the specific quickfix entry + let e = getqflist({'id' : a:info.id, 'idx' : a:info.idx, + \ 'items' : 1}).items[0] + " return the simplified file name + return fnamemodify(bufname(e.bufnr), ':p:.') + endfunc +< vim:tw=78:ts=8:noet:ft=help:norl: |