patch 8.2.0869: it is not possible to customize the quickfix window contents
Problem: It is not possible to customize the quickfix window contents.
Solution: Add 'quickfixtextfunc'. (Yegappan Lakshmanan, closes #5465)
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index b753aae..fb0b2a7 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -5508,8 +5508,9 @@
id get information for the quickfix list with
|quickfix-ID|; zero means the id for the
current list or the list specified by "nr"
- idx index of the current entry in the quickfix
- list specified by 'id' or 'nr'.
+ idx get information for the quickfix entry at this
+ index in the list specified by 'id' or 'nr'.
+ If set to zero, then uses the current entry.
See |quickfix-index|
items quickfix list entries
lines parse a list of lines using 'efm' and return
@@ -5545,7 +5546,7 @@
If not present, set to "".
id quickfix list ID |quickfix-ID|. If not
present, set to 0.
- idx index of the current entry in the list. If not
+ idx index of the quickfix entry in the list. If not
present, set to 0.
items quickfix list entries. If not present, set to
an empty list.
@@ -8841,6 +8842,11 @@
nr list number in the quickfix stack; zero
means the current quickfix list and "$" means
the last quickfix list.
+ quickfixtextfunc
+ function to get the text to display in the
+ quickfix window. Refer to
+ |quickfix-window-function| for an explanation
+ of how to write the function and an example.
title quickfix list title text. See |quickfix-title|
Unsupported keys in {what} are ignored.
If the "nr" item is not present, then the current quickfix list
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index d4d8787..82b91a6 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -5901,6 +5901,21 @@
This option cannot be set from a |modeline| or in the |sandbox|, for
security reasons.
+ *'quickfixtextfunc'* *'qftf'*
+'quickfixtextfunc' 'qftf' string (default "")
+ global
+ {only available when compiled with the |+quickfix|
+ feature}
+ This option specifies a function to be used to get the text to display
+ in the quickfix and location list windows. This can be used to
+ customize the information displayed in the quickfix or location window
+ for each entry in the corresponding quickfix or location list. See
+ |quickfix-window-function| for an explanation of how to write the
+ function and an example.
+
+ This option cannot be set from a |modeline| or in the |sandbox|, for
+ security reasons.
+
*'quoteescape'* *'qe'*
'quoteescape' 'qe' string (default "\")
local to buffer
diff --git a/runtime/doc/quickfix.txt b/runtime/doc/quickfix.txt
index 7f7f10f..d4ebf5c 100644
--- a/runtime/doc/quickfix.txt
+++ b/runtime/doc/quickfix.txt
@@ -15,6 +15,7 @@
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 @@
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: