diff runtime/doc/eval.txt @ 16638:4790302965fc v8.1.1321

patch 8.1.1321: no docs or tests for listener functions commit https://github.com/vim/vim/commit/a334772967de25764ed7b11d768e8b977818d0c6 Author: Bram Moolenaar <Bram@vim.org> Date: Sat May 11 21:14:24 2019 +0200 patch 8.1.1321: no docs or tests for listener functions Problem: No docs or tests for listener functions. Solution: Add help and tests for listener_add() and listener_remove(). Invoke the callbacks before redrawing.
author Bram Moolenaar <Bram@vim.org>
date Sat, 11 May 2019 21:15:06 +0200
parents 1a911bd57f11
children a7f06505ad39
line wrap: on
line diff
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -2457,6 +2457,9 @@ line({expr})			Number	line nr of cursor,
 line2byte({lnum})		Number	byte count of line {lnum}
 lispindent({lnum})		Number	Lisp indent for line {lnum}
 list2str({list} [, {utf8}])	String	turn numbers in {list} into a String
+listener_add({callback} [, {buf}])
+				Number	add a callback to listen to changes
+listener_remove({id})		none	remove a listener callback
 localtime()			Number	current time
 log({expr})			Float	natural logarithm (base e) of {expr}
 log10({expr})			Float	logarithm of Float {expr} to base 10
@@ -6311,6 +6314,53 @@ list2str({list} [, {utf8}])				*list2str
 		With utf-8 composing characters work as expected: >
 			list2str([97, 769])	returns "á"
 <
+listener_add({callback} [, {buf}])			*listener_add()*
+		Add a callback function that will be invoked when changes have
+		been made to buffer {buf}.
+		{buf} refers to a buffer name or number. For the accepted
+		values, see |bufname()|.  When {buf} is omitted the current
+		buffer is used.
+		Returns a unique ID that can be passed to |listener_remove()|.
+
+		The {callback} is invoked with a list of items that indicate a
+		change.  Each list item is a dictionary with these entries:
+		    lnum	the first line number of the change
+		    end		the first line below the change
+		    added	number of lines added; negative if lines were
+				deleted
+		    col		first column in "lnum" that was affected by
+				the change; one if unknown or the whole line
+				was affected; this is a byte index, first
+				character has a value of one.
+		When lines are inserted the values are:
+		    lnum	line below which the new line is added
+		    end		equal to "lnum"
+		    added	number of lines inserted
+		    col		one
+		When lines are deleted the values are:
+		    lnum	the first deleted line
+		    end		the line below the first deleted line, before
+				the deletion was done
+		    added	negative, number of lines deleted
+		    col		one
+		When lines are changed:
+		    lnum	the first changed line
+		    end		the line below the last changed line
+		    added	zero
+		    col		first column with a change or one
+
+		The {callback} is invoked just before the screen is updated.
+		To trigger this in a script use the `:redraw` command.
+
+		The {callback} is not invoked when the buffer is first loaded.
+		Use the |BufReadPost| autocmd event to handle the initial text
+		of a buffer.
+		The {callback} is also not invoked when the buffer is
+		unloaded, use the |BufUnload| autocmd event for that.
+
+listener_remove({id})					*listener_remove()*
+		Remove a listener previously added with listener_add().
+
 localtime()						*localtime()*
 		Return the current time, measured as seconds since 1st Jan
 		1970.  See also |strftime()| and |getftime()|.