patch 8.2.0869: it is not possible to customize the quickfix window contentsv8.2.0869

Problem:    It is not possible to customize the quickfix window contents.
Solution:   Add 'quickfixtextfunc'. (Yegappan Lakshmanan, closes #5465)

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: