Adding upstream version 2:8.2.2434.upstream/2%8.2.2434upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1073 insertions, 0 deletions

diff --git a/runtime/doc/popup.txt b/runtime/doc/popup.txt
new file mode 100644
index 0000000..6d70cec
--- /dev/null
+++ b/runtime/doc/popup.txt
@@ -0,0 +1,1073 @@
+*popup.txt*  For Vim version 8.2.  Last change: 2021 Jan 21
+
+
+		  VIM REFERENCE MANUAL    by Bram Moolenaar
+
+
+Displaying text in a floating window.	*popup* *popup-window* *popupwin*
+
+
+1. Introduction			|popup-intro|
+   Window position and size	|popup-position|
+   Closing the popup window	|popup-close|
+   Popup buffer and window	|popup-buffer|
+   Terminal in popup window	|popup-terminal|
+2. Functions			|popup-functions|
+   Details			|popup-function-details|
+3. Usage			|popup-usage|
+   popup_create() arguments	|popup_create-arguments|
+   Popup text properties	|popup-props|
+   Position popup with textprop	|popup-textprop-pos|
+   Popup filter			|popup-filter|
+   Popup callback		|popup-callback|
+   Popup scrollbar		|popup-scrollbar|
+   Popup mask			|popup-mask|
+4. Examples			|popup-examples|
+
+
+{not available if the |+popupwin| feature was disabled at compile time}
+
+==============================================================================
+1. Introduction						*popup-intro*
+
+We are talking about popup windows here, text that goes on top of the regular
+windows and is under control of a plugin.  You cannot edit the text in the
+popup window like with regular windows.
+
+A popup window can be used for such things as:
+- briefly show a message without overwriting the command line
+- prompt the user with a dialog
+- display contextual information while typing
+- give extra information for auto-completion
+
+The text in the popup window can be colored with |text-properties|.  It is
+also possible to use syntax highlighting.
+
+The default color used is "Pmenu".  If you prefer something else use the
+"highlight" argument or the 'wincolor' option, e.g.: >
+	hi MyPopupColor ctermbg=lightblue guibg=lightblue
+	call setwinvar(winid, '&wincolor', 'MyPopupColor')
+
+'hlsearch' highlighting is not displayed in a popup window.
+
+A popup window has a window-ID like other windows, but behaves differently.
+The size can be up to the whole Vim window and it overlaps other windows.
+Popup windows can also overlap each other.  The "zindex" property specifies
+what goes on top of what.
+
+The popup window contains a buffer, and that buffer is always associated with
+the popup window.  The window cannot be in Normal, Visual or Insert mode, it
+does not get keyboard focus.  You can use functions like `setbufline()` to
+change the text in the buffer.  There are more differences from how this
+window and buffer behave compared to regular windows and buffers, see
+|popup-buffer|.
+
+If this is not what you are looking for, check out other popup functionality:
+- popup menu, see |popup-menu|
+- balloon, see |balloon-eval|
+
+
+WINDOW POSITION AND SIZE				*popup-position*
+
+The height of the window is normally equal to the number of, possibly
+wrapping, lines in the buffer.  It can be limited with the "maxheight"
+property.  You can use empty lines to increase the height or the "minheight"
+property.
+
+The width of the window is normally equal to the longest visible line in the
+buffer.  It can be limited with the "maxwidth" property.  You can use spaces
+to increase the width or use the "minwidth" property.
+
+By default the 'wrap' option is set, so that no text disappears.  Otherwise,
+if there is not enough space then the window is shifted left in order to
+display more text.  When right-aligned the window is shifted right to display
+more text.  The shifting can be disabled with the "fixed" property.
+
+Vim tries to show the popup in the location you specify.  In some cases, e.g.
+when the popup would go outside of the Vim window, it will show it somewhere
+nearby.  E.g. if you use `popup_atcursor()` the popup normally shows just above
+the current cursor position, but if the cursor is close to the top of the Vim
+window it will be placed below the cursor position.
+
+When the screen scrolls up for output of an Ex command, popups move too, so
+that they will not cover the output.
+
+The current cursor position is displayed even when it is under a popup window.
+That way you can still see where it is, even though you cannot see the text
+that it is in.
+
+
+CLOSING THE POPUP WINDOW				*popup-close*
+
+Normally the plugin that created the popup window is also in charge of closing
+it.  If somehow a popup hangs around, you can close all of them with: >
+	call popup_clear(1)
+Some popups, such as notifications, close after a specified time.  This can be
+set with the "time" property on `popup_create()`.
+Otherwise, a popup can be closed by clicking on the X in the top-right corner
+or by clicking anywhere inside the popup.  This must be enabled with the
+"close" property.  It is set by default for notifications.
+
+
+POPUP BUFFER AND WINDOW					*popup-buffer*
+
+If a popup function is called to create a popup from text, a new buffer is
+created to hold the text and text properties of the popup window.  The buffer
+is always associated with the popup window and manipulation is restricted:
+- the buffer has no name
+- 'buftype' is "popup"
+- 'swapfile' is off
+- 'bufhidden' is "hide"
+- 'buflisted' is off
+- 'undolevels' is -1: no undo at all
+- all other buffer-local and window-local options are set to their Vim default
+  value.
+
+It is possible to change the specifically mentioned options, but anything
+might break then, so better leave them alone.
+
+The window does have a cursor position, but the cursor is not displayed.  In
+fact, the cursor in the underlying window is displayed, as if it peeks through
+the popup, so you can see where it is.
+
+To execute a command in the context of the popup window and buffer use
+`win_execute()`.  Example: >
+	call win_execute(winid, 'syntax enable')
+
+Options can be set on the window with `setwinvar()`, e.g.: >
+	call setwinvar(winid, '&wrap', 0)
+And options can be set on the buffer with `setbufvar()`, e.g.: >
+	call setbufvar(winbufnr(winid), '&filetype', 'java')
+You can also use `win_execute()` with a ":setlocal" command.
+
+
+TERMINAL IN POPUP WINDOW				 *popup-terminal*
+
+A special case is running a terminal in a popup window.  Many rules are then
+different:						*E863*
+- The popup window always has focus, it is not possible to switch to another
+  window.
+- When the job ends, the popup window closes.
+- The popup window can be closed with `popup_close()`, the terminal buffer
+  then becomes hidden.
+- It is not possible to open a second popup window with a terminal. *E861*
+- The default Pmenu color is only used for the border and padding.  To change
+  the color of the terminal itself set the Terminal highlight group before
+  creating the terminal.  Setting 'wincolor' later can work but requires the
+  program in the terminal to redraw everything.
+- The default minimal size is 5 lines of 20 characters; Use the "minwidth" and
+  "minheight" parameters to set a different value.
+- The terminal size will grow if the program running in the terminal writes
+  text.  Set "maxheight" and "maxwidth" to restrict the size.
+
+To run a terminal in a popup window, first create the terminal hidden.  Then
+pass the buffer number to popup_create().  Example: >
+	hi link Terminal Search
+	let buf = term_start(['picker', 'Something'], #{hidden: 1, term_finish: 'close'})
+	let winid = popup_create(buf, #{minwidth: 50, minheight: 20})
+
+==============================================================================
+2. Functions						*popup-functions*
+
+Creating a popup window:
+	|popup_create()|	centered in the screen
+	|popup_atcursor()|	just above the cursor position, closes when
+				the cursor moves away
+	|popup_beval()|		at the position indicated by v:beval_
+				variables, closes when the mouse moves away
+	|popup_notification()|	show a notification for three seconds
+	|popup_dialog()|	centered with padding and border
+	|popup_menu()|		prompt for selecting an item from a list
+
+Manipulating a popup window:
+	|popup_hide()|		hide a popup temporarily
+	|popup_show()|		show a previously hidden popup
+	|popup_move()|		change the position and size of a popup
+	|popup_setoptions()|	override options of a popup
+	|popup_settext()|	replace the popup buffer contents
+
+Closing popup windows:
+	|popup_close()|		close one popup
+	|popup_clear()|		close all popups
+
+Filter functions:
+	|popup_filter_menu()|	select from a list of items
+	|popup_filter_yesno()|	blocks until 'y' or 'n' is pressed
+
+Other:
+	|popup_getoptions()|	get current options for a popup
+	|popup_getpos()|	get actual position and size of a popup
+	|popup_locate()|	find popup window at a screen position
+	|popup_list()|		get list of all popups
+
+
+DETAILS						*popup-function-details*
+
+popup_atcursor({what}, {options})			*popup_atcursor()*
+		Show the {what} above the cursor, and close it when the cursor
+		moves.  This works like: >
+			call popup_create({what}, #{
+				\ pos: 'botleft',
+				\ line: 'cursor-1',
+				\ col: 'cursor',
+				\ moved: 'WORD',
+				\ })
+<		Use {options} to change the properties.
+		If "pos" is passed as "topleft" then the default for "line"
+		becomes "cursor+1".
+
+		Can also be used as a |method|: >
+			GetText()->popup_atcursor({})
+
+
+popup_beval({what}, {options})			*popup_beval()*
+		Show the {what} above the position from 'ballooneval' and
+		close it when the mouse moves.  This works like: >
+		  let pos = screenpos(v:beval_winnr, v:beval_lnum, v:beval_col)
+		  call popup_create({what}, #{
+			\ pos: 'botleft',
+			\ line: pos.row - 1,
+			\ col: pos.col,
+			\ mousemoved: 'WORD',
+			\ })
+<		Use {options} to change the properties.
+		See |popup_beval_example| for an example.
+
+		Can also be used as a |method|: >
+			GetText()->popup_beval({})
+<
+							*popup_clear()*
+popup_clear([{force}])
+		Emergency solution to a misbehaving plugin: close all popup
+		windows for the current tab and global popups.
+		Close callbacks are not invoked.
+		When {force} is not present this will fail if the current
+		window is a popup.
+		When {force} is present and |TRUE| the popup is also closed
+		when it is the current window.  If a terminal is running in a
+		popup it is killed.
+
+
+popup_close({id} [, {result}])				*popup_close()*
+		Close popup {id}.  The window and the associated buffer will
+		be deleted.
+
+		If the popup has a callback it will be called just before the
+		popup window is deleted.  If the optional {result} is present
+		it will be passed as the second argument of the callback.
+		Otherwise zero is passed to the callback.
+
+		Can also be used as a |method|: >
+			GetPopup()->popup_close()
+
+popup_create({what}, {options})				*popup_create()*
+		Open a popup window showing {what}, which is either:
+		- a buffer number
+		- a string
+		- a list of strings
+		- a list of text lines with text properties
+		When {what} is not a buffer number, a buffer is created with
+		'buftype' set to "popup".  That buffer will be wiped out once
+		the popup closes.
+
+		{options} is a dictionary with many possible entries.
+		See |popup_create-arguments| for details.
+
+		Returns a window-ID, which can be used with other popup
+		functions.  Use `winbufnr()` to get the number of the buffer
+		in the window: >
+			let winid = popup_create('hello', {})
+			let bufnr = winbufnr(winid)
+			call setbufline(bufnr, 2, 'second line')
+<		In case of failure zero is returned.
+
+		Can also be used as a |method|: >
+			GetText()->popup_create({})
+
+popup_dialog({what}, {options})				*popup_dialog()*
+		Just like |popup_create()| but with these default options: >
+			call popup_create({what}, #{
+				\ pos: 'center',
+				\ zindex: 200,
+				\ drag: 1,
+				\ border: [],
+				\ padding: [],
+				\ mapping: 0,
+				\})
+<		Use {options} to change the properties. E.g. add a 'filter'
+		option with value 'popup_filter_yesno'.  Example: >
+			call popup_create('do you want to quit (Yes/no)?', #{
+				\ filter: 'popup_filter_yesno',
+				\ callback: 'QuitCallback',
+				\ })
+
+<		By default the dialog can be dragged, so that text below it
+		can be read if needed.
+
+		Can also be used as a |method|: >
+			GetText()->popup_dialog({})
+
+popup_filter_menu({id}, {key})				*popup_filter_menu()*
+		Filter that can be used for a popup. These keys can be used:
+		    j <Down> <C-N>	select item below
+		    k <Up> <C-P>	select item above
+		    <Space> <Enter>	accept current selection
+		    x Esc CTRL-C	cancel the menu
+		Other keys are ignored.
+		Always returns |v:true|.
+
+		A match is set on that line to highlight it, see
+		|popup_menu()|.
+
+		When the current selection is accepted the "callback" of the
+		popup menu is invoked with the index of the selected line as
+		the second argument.  The first entry has index one.
+		Cancelling the menu invokes the callback with -1.
+
+		To add shortcut keys, see the example here:
+		|popup_menu-shortcut-example|
+
+
+popup_filter_yesno({id}, {key})				*popup_filter_yesno()*
+		Filter that can be used for a popup. It handles only the keys
+		'y', 'Y' and 'n' or 'N'.  Invokes the "callback" of the
+		popup menu with the 1 for 'y' or 'Y' and zero for 'n' or 'N'
+		as the second argument.  Pressing Esc and 'x' works like
+		pressing 'n'.  CTRL-C invokes the callback with -1.  Other
+		keys are ignored.
+		See the example here: |popup_dialog-example|
+
+
+popup_findinfo()					*popup_findinfo()*
+		Get the |window-ID| for the popup info window, as it used by
+		the popup menu.  See |complete-popup|.  The info popup is
+		hidden when not used, it can be deleted with |popup_clear()|
+		and |popup_close()|.  Use |popup_show()| to reposition it to
+		the item in the popup menu.
+		Returns zero if there is none.
+
+
+popup_findpreview()					*popup_findpreview()*
+		Get the |window-ID| for the popup preview window.
+		Return zero if there is none.
+
+
+popup_getoptions({id})					*popup_getoptions()*
+		Return the {options} for popup {id} in a Dict.
+		A zero value means the option was not set.  For "zindex" the
+		default value is returned, not zero.
+
+		The "moved" entry is a list with line number, minimum and
+		maximum column, [0, 0, 0] when not set.
+
+		The "mousemoved" entry is a list with screen row, minimum and
+		maximum screen column, [0, 0, 0] when not set.
+
+		"firstline" is the property set on the popup, unlike the
+		"firstline" obtained with |popup_getpos()| which is the actual
+		buffer line at the top of the popup window.
+
+		"border" and "padding" are not included when all values are
+		zero.  When all values are one then an empty list is included.
+
+		"borderhighlight" is not included when all values are empty.
+		"scrollbarhighlight" and "thumbhighlight" are only included
+		when set.
+
+		"tabpage" will be -1 for a global popup, zero for a popup on
+		the current tabpage and a positive number for a popup on
+		another tabpage.
+
+		"textprop", "textpropid" and "textpropwin" are only present
+		when "textprop" was set.
+
+		If popup window {id} is not found an empty Dict is returned.
+
+		Can also be used as a |method|: >
+			GetPopup()->popup_getoptions()
+
+popup_getpos({id})					*popup_getpos()*
+		Return the position and size of popup {id}.  Returns a Dict
+		with these entries:
+		    col		screen column of the popup, one-based
+		    line	screen line of the popup, one-based
+		    width	width of the whole popup in screen cells
+		    height	height of the whole popup in screen cells
+		    core_col	screen column of the text box
+		    core_line	screen line of the text box
+		    core_width	width of the text box in screen cells
+		    core_height	height of the text box in screen cells
+		    firstline	line of the buffer at top (1 unless scrolled)
+				(not the value of the "firstline" property)
+		    lastline	line of the buffer at the bottom (updated when
+				the popup is redrawn)
+		    scrollbar	non-zero if a scrollbar is displayed
+		    visible	one if the popup is displayed, zero if hidden
+		Note that these are the actual screen positions.  They differ
+		from the values in `popup_getoptions()` for the sizing and
+		positioning mechanism applied.
+
+		The "core_" values exclude the padding and border.
+
+		If popup window {id} is not found an empty Dict is returned.
+
+		Can also be used as a |method|: >
+			GetPopup()->popup_getpos()
+
+popup_hide({id})						*popup_hide()*
+		If {id} is a displayed popup, hide it now. If the popup has a
+		filter it will not be invoked for so long as the popup is
+		hidden.
+		If window {id} does not exist nothing happens.  If window {id}
+		exists but is not a popup window an error is given. *E993*
+		If popup window {id} contains a terminal an error is given.
+
+		Can also be used as a |method|: >
+			GetPopup()->popup_hide()
+
+popup_list()						 *popup_list()*
+		Return a List with the |window-ID| of all existing popups.
+
+
+popup_locate({row}, {col})				 *popup_locate()*
+		Return the |window-ID| of the popup at screen position {row}
+		and {col}.  If there are multiple popups the one with the
+		highest zindex is returned.  If there are no popups at this
+		position then zero is returned.
+
+
+popup_menu({what}, {options})				 *popup_menu()*
+		Show the {what} near the cursor, handle selecting one of the
+		items with cursorkeys, and close it an item is selected with
+		Space or Enter. {what} should have multiple lines to make this
+		useful.  This works like: >
+			call popup_create({what}, #{
+				\ pos: 'center',
+				\ zindex: 200,
+				\ drag: 1,
+				\ wrap: 0,
+				\ border: [],
+				\ cursorline: 1,
+				\ padding: [0,1,0,1],
+				\ filter: 'popup_filter_menu',
+				\ mapping: 0,
+				\ })
+<		The current line is highlighted with a match using
+		"PopupSelected", or "PmenuSel" if that is not defined.
+
+		Use {options} to change the properties.  Should at least set
+		"callback" to a function that handles the selected item.
+		Example: >
+			func ColorSelected(id, result)
+			   " use a:result
+			endfunc
+			call popup_menu(['red', 'green', 'blue'], #{
+				\ callback: 'ColorSelected',
+				\ })
+
+<		Can also be used as a |method|: >
+			GetChoices()->popup_menu({})
+
+popup_move({id}, {options})					*popup_move()*
+		Move popup {id} to the position specified with {options}.
+		{options} may contain the items from |popup_create()| that
+		specify the popup position:
+			line
+			col
+			pos
+			maxheight
+			minheight
+			maxwidth
+			minwidth
+			fixed
+		For {id} see `popup_hide()`.
+		For other options see |popup_setoptions()|.
+
+		Can also be used as a |method|: >
+			GetPopup()->popup_move(options)
+
+popup_notification({what}, {options})			 *popup_notification()*
+		Show the {what} for 3 seconds at the top of the Vim window.
+		This works like: >
+			call popup_create({what}, #{
+				\ line: 1,
+				\ col: 10,
+				\ minwidth: 20,
+				\ time: 3000,
+				\ tabpage: -1,
+				\ zindex: 300,
+				\ drag: 1,
+				\ highlight: 'WarningMsg',
+				\ border: [],
+				\ close: 'click',
+				\ padding: [0,1,0,1],
+				\ })
+<		The PopupNotification highlight group is used instead of
+		WarningMsg if it is defined.
+
+		Without the |+timers| feature the popup will not disappear
+		automatically, the user has to click in it.
+
+		The position will be adjusted to avoid overlap with other
+		notifications.
+		Use {options} to change the properties.
+
+		Can also be used as a |method|: >
+			GetText()->popup_notification({})
+
+popup_show({id})						*popup_show()*
+		If {id} is a hidden popup, show it now.
+		For {id} see `popup_hide()`.
+		If {id} is the info popup it will be positioned next to the
+		current popup menu item.
+
+
+popup_setoptions({id}, {options})			*popup_setoptions()*
+		Override options in popup {id} with entries in {options}.
+		These options can be set:
+			border
+			borderchars
+			borderhighlight
+			callback
+			close
+			cursorline
+			drag
+			filter
+			firstline
+			flip
+			highlight
+			mapping
+			mask
+			moved
+			padding
+			resize
+			scrollbar
+			scrollbarhighlight
+			thumbhighlight
+			time
+			title
+			wrap
+			zindex
+		The options from |popup_move()| can also be used.
+		Generally, setting an option to zero or an empty string resets
+		it to the default value, but there are exceptions.
+		For "hidden" use |popup_hide()| and |popup_show()|.
+		"tabpage" cannot be changed.
+
+		Can also be used as a |method|: >
+			GetPopup()->popup_setoptions(options)
+
+popup_settext({id}, {text})				*popup_settext()*
+		Set the text of the buffer in popup win {id}. {text} is the
+		same as supplied to |popup_create()|, except that a buffer
+		number is not allowed.
+		Does not change the window size or position, other than caused
+		by the different text.
+
+		Can also be used as a |method|: >
+			GetPopup()->popup_settext('hello')
+
+==============================================================================
+3. Usage						*popup-usage*
+
+POPUP_CREATE() ARGUMENTS			 *popup_create-arguments*
+
+The first argument of |popup_create()| (and the second argument to
+|popup_settext()|) specifies the text to be displayed, and optionally text
+properties.  It is in one of four forms:
+- a buffer number
+- a string
+- a list of strings
+- a list of dictionaries, where each dictionary has these entries:
+	text		String with the text to display.
+	props		A list of text properties.  Optional.
+			Each entry is a dictionary, like the third argument of
+			|prop_add()|, but specifying the column in the
+			dictionary with a "col" entry, see below:
+			|popup-props|.
+
+If you want to create a new buffer yourself use |bufadd()| and pass the buffer
+number to popup_create().
+
+The second argument of |popup_create()| is a dictionary with options:
+	line		Screen line where to position the popup.  Can use a
+			number or "cursor", "cursor+1" or "cursor-1" to use
+			the line of the cursor and add or subtract a number of
+			lines.  If omitted or zero the popup is vertically
+			centered.  The first line is 1.
+			When using "textprop" the number is relative to the
+			text property and can be negative.
+	col		Screen column where to position the popup.  Can use a
+			number or "cursor" to use the column of the cursor,
+			"cursor+9" or "cursor-9" to add or subtract a number
+			of columns.  If omitted or zero the popup is
+			horizontally centered.  The first column is 1.
+			When using "textprop" the number is relative to the
+			text property and can be negative.
+	pos		"topleft", "topright", "botleft" or "botright":
+			defines what corner of the popup "line" and "col" are
+			used for.  When not set "topleft" is used.
+			Alternatively "center" can be used to position the
+			popup in the center of the Vim window, in which case
+			"line" and "col" are ignored.
+	posinvert	When FALSE the value of "pos" is always used.  When
+			TRUE (the default) and the popup does not fit
+			vertically and there is more space on the other side
+			then the popup is placed on the other side of the
+			position indicated by "line".
+	textprop	When present the popup is positioned next to a text
+			property with this name and will move when the text
+			property moves.  Use an empty string to remove.  See
+			|popup-textprop-pos|.
+	textpropwin	What window to search for the text property.  When
+			omitted or invalid the current window is used.
+	textpropid	Used to identify the text property when "textprop" is
+			present. Use zero to reset.
+	fixed		When FALSE (the default), and:
+			 - "pos" is "botleft" or "topleft", and
+			 - "wrap" is off, and
+			 - the popup would be truncated at the right edge of
+			   the screen, then
+			the popup is moved to the left so as to fit the
+			contents on the screen.  Set to TRUE to disable this.
+	flip		When TRUE (the default) and the position is relative
+			to the cursor, flip to below or above the cursor to
+			avoid overlap with the |popupmenu-completion| or
+			another popup with a higher "zindex".  When there is
+			no space above/below the cursor then show the popup to
+			the side of the popup or popup menu.
+			{not implemented yet}
+	maxheight	Maximum height of the contents, excluding border and
+			padding.
+	minheight	Minimum height of the contents, excluding border and
+			padding.
+	maxwidth	Maximum width of the contents, excluding border,
+			padding and scrollbar.
+	minwidth	Minimum width of the contents, excluding border,
+			padding and scrollbar.
+	firstline	First buffer line to display.  When larger than one it
+			looks like the text scrolled up.  When out of range
+			the last buffer line will at the top of the window.
+			Set to zero to leave the position as set by commands.
+			Also see "scrollbar".
+	hidden		When TRUE the popup exists but is not displayed; use
+			`popup_show()` to unhide it.
+	tabpage		When -1: display the popup on all tab pages.
+			When 0 (the default): display the popup on the current
+			tab page.
+			Otherwise the number of the tab page the popup is
+			displayed on; when invalid the popup is not created
+			and an error is given. *E997*
+	title		Text to be displayed above the first item in the
+			popup, on top of any border.  If there is no top
+			border one line of padding is added to put the title
+			on.  You might want to add one or more spaces at the
+			start and end as padding.
+	wrap		TRUE to make the lines wrap (default TRUE).
+	drag		TRUE to allow the popup to be dragged with the mouse
+			by grabbing at the border.  Has no effect if the
+			popup does not have a border. As soon as dragging
+			starts and "pos" is "center" it is changed to
+			"topleft".
+	resize		TRUE to allow the popup to be resized with the mouse
+			by grabbing at the bottom right corner.  Has no effect
+			if the popup does not have a border.
+	close		When "button" an X is displayed in the top-right, on
+			top of any border, padding or text.  When clicked on
+			the X the popup will close.  Any callback is invoked
+			with the value -2.
+			When "click" any mouse click in the popup will close
+			it.
+			When "none" (the default) mouse clicks do not close
+			the popup window.
+	highlight	Highlight group name to use for the text, stored in
+			the 'wincolor' option.
+	padding		List with numbers, defining the padding
+			above/right/below/left of the popup (similar to CSS).
+			An empty list uses a padding of 1 all around.  The
+			padding goes around the text, inside any border.
+			Padding uses the 'wincolor' highlight.
+			Example: [1, 2, 1, 3] has 1 line of padding above, 2
+			columns on the right, 1 line below and 3 columns on
+			the left.
+	border		List with numbers, defining the border thickness
+			above/right/below/left of the popup (similar to CSS).
+			Only values of zero and non-zero are recognized.
+			An empty list uses a border all around.
+	borderhighlight	List of highlight group names to use for the border.
+			When one entry it is used for all borders, otherwise
+			the highlight for the top/right/bottom/left border.
+			Example: ['TopColor', 'RightColor', 'BottomColor,
+			'LeftColor']
+	borderchars	List with characters, defining the character to use
+			for the top/right/bottom/left border.  Optionally
+			followed by the character to use for the
+			topleft/topright/botright/botleft corner.
+			Example: ['-', '|', '-', '|', '┌', '┐', '┘', '└']
+			When the list has one character it is used for all.
+			When the list has two characters the first is used for
+			the border lines, the second for the corners.
+			By default a double line is used all around when
+			'encoding' is "utf-8" and 'ambiwidth' is "single",
+			otherwise ASCII characters are used.
+	scrollbar	1 or true: show a scrollbar when the text doesn't fit.
+			zero: do not show a scrollbar.  Default is non-zero.
+			Also see |popup-scrollbar|.
+	scrollbarhighlight  Highlight group name for the scrollbar. The
+			background color is what matters.  When not given then
+			PmenuSbar is used.
+	thumbhighlight  Highlight group name for the scrollbar thumb. The
+			background color is what matters.  When not given then
+			PmenuThumb is used.
+	zindex		Priority for the popup, default 50.  Minimum value is
+			1, maximum value is 32000.
+	mask		A list of lists with coordinates, defining parts of
+			the popup that are transparent.  See |popup-mask|.
+	time		Time in milliseconds after which the popup will close.
+			When omitted |popup_close()| must be used.
+	moved		Specifies to close the popup if the cursor moved:
+			- "any": if the cursor moved at all
+			- "word": if the cursor moved outside |<cword>|
+			- "WORD": if the cursor moved outside |<cWORD>|
+			- "expr": if the cursor moved outside |<cexpr>|
+			- [{start}, {end}]: if the cursor moved before column
+			  {start} or after {end}
+			- [{lnum}, {start}, {end}]: if the cursor moved away
+			  from line {lnum}, before column {start} or after
+			  {end}
+			- [0, 0, 0] do not close the popup when the cursor
+			  moves
+			The popup also closes if the cursor moves to another
+			line or to another window.
+	mousemoved	Like "moved" but referring to the mouse pointer
+			position
+	cursorline	non-zero: Highlight the cursor line. Also scrolls the
+				  text to show this line (only works properly
+				  when 'wrap' is off).
+			zero: 	  Do not highlight the cursor line.
+			Default is zero, except for |popup_menu()|.
+	filter		A callback that can filter typed characters, see
+			|popup-filter|.
+	mapping		Allow for key mapping.  When FALSE and the popup is
+			visible and has a filter callback key mapping is
+			disabled.  Default value is TRUE.
+	filtermode	In which modes the filter is used (same flags as with
+			|hasmapto()| plus "a"):
+				n	Normal mode
+				v	Visual and Select mode
+				x	Visual mode
+				s	Select mode
+				o	Operator-pending mode
+				i	Insert mode
+				l	Language-Argument ("r", "f", "t", etc.)
+				c	Command-line mode
+				a	all modes
+			The default value is "a".
+	callback	A callback that is called when the popup closes, e.g.
+			when using |popup_filter_menu()|, see |popup-callback|.
+
+Depending on the "zindex" the popup goes under or above other popups.  The
+completion menu (|popup-menu|) has zindex 100.  For messages that occur for a
+short time the suggestion is to use zindex 1000.
+
+By default text wraps, which causes a line in {lines} to occupy more than one
+screen line.  When "wrap" is FALSE then the text outside of the popup or
+outside of the Vim window will not be displayed, thus truncated.
+
+
+POPUP TEXT PROPERTIES					*popup-props*
+
+These are similar to the third argument of |prop_add()| except:
+- "lnum" is always the current line in the list
+- "bufnr" is always the buffer of the popup
+- "col" is in the Dict instead of a separate argument
+So we get:
+	col		starting column, counted in bytes, use one for the
+			first column.
+	length		length of text in bytes; can be zero
+	end_lnum	line number for the end of the text
+	end_col		column just after the text; not used when "length" is
+			present; when {col} and "end_col" are equal, this is a
+			zero-width text property
+	id		user defined ID for the property; when omitted zero is
+			used
+	type		name of the text property type, as added with
+			|prop_type_add()|
+
+
+POSITION POPUP WITH TEXTPROP				*popup-textprop-pos*
+
+Positioning a popup next to a text property causes the popup to move when text
+is inserted or deleted.  The popup functions like a tooltip.
+
+These steps are needed to make this work:
+
+- Define a text property type, it defines the name. >
+	call prop_type_add('popupMarker', {})
+
+- Place a text property at the desired text: >
+	let lnum = {line of the text}
+	let col = {start column of the text}
+	let len = {length of the text}
+	let propId = {arbitrary but unique number}
+	call prop_add(lnum, col, #{
+		\ length: len,
+		\ type: 'popupMarker',
+		\ id: propId,
+		\ })
+
+- Create a popup: >
+	let winid = popup_create('the text', #{
+		\ pos: 'botleft',
+		\ textprop: 'popupMarker',
+		\ textpropid: propId,
+		\ border: [],
+		\ padding: [0,1,0,1],
+		\ close: 'click',
+		\ })
+
+By default the popup is positioned at the corner of the text, opposite of the
+"pos" specified for the popup.  Thus when the popup uses "botleft", the
+bottom-left corner of the popup is positioned next to the top-right corner of
+the text property:
+			  +----------+
+			  | the text |
+			  +----------+
+	just some PROPERTY as an example
+
+Here the text property is on "PROPERTY".  Move the popup to the left by
+passing a negative "col" value to popup_create().  With "col: -5" you get:
+
+		     +----------+
+		     | the text |
+		     +----------+
+	just some PROPERTY as an example
+
+If the text property moves out of view then the popup will be hidden.
+If the window for which the popup was defined is closed, the popup is closed.
+
+If the popup cannot fit in the desired position, it may show at a nearby
+position.
+
+Some hints:
+- To avoid collision with other plugins the text property type name has to be
+  unique.  You can also use the "bufnr" item to make it local to a buffer.
+- You can leave out the text property ID if there is only ever one text
+  property visible.
+- The popup may be in the way of what the user is doing, making it close with
+  a click, as in the example above, helps for that.
+- If the text property is removed the popup is closed.  Use something like
+  this: >
+	call prop_remove(#{type: 'popupMarker', id: propId})
+
+
+POPUP FILTER						*popup-filter*
+
+A callback that gets any typed keys while a popup is displayed.  The filter is
+not invoked when the popup is hidden.
+
+The filter can return TRUE to indicate the key has been handled and is to be
+discarded, or FALSE to let Vim handle the key as usual in the current state.
+In case it returns FALSE and there is another popup window visible, that
+filter is also called.  The filter of the popup window with the highest zindex
+is called first.
+
+The filter function is called with two arguments: the ID of the popup and the
+key as a string, e.g.: >
+	func MyFilter(winid, key)
+	  if a:key == "\<F2>"
+	    " do something
+	    return 1
+	  endif
+	  if a:key == 'x'
+	    call popup_close(a:winid)
+	    return 1
+	  endif
+	  return 0
+	endfunc
+<							*popup-filter-mode*
+The "filtermode" property can be used to specify in what mode the filter is
+invoked.  The default is "a": all modes.  When using "nvi" Command-line mode
+is not included, so that any command typed on the command line is not
+filtered.  However, to get to Command-line mode the filter must not consume
+":".  Just like it must not consume "v" to allow for entering Visual mode.
+
+							*popup-mapping*
+Normally the key is what results after any mapping, since the keys pass on as
+normal input if the filter does not use it.  If the filter consumes all the
+keys, set the "mapping" property to zero so that mappings do not get in the
+way.  This is default for |popup_menu()| and |popup_dialog()|.
+
+Some recommended key actions:
+	x		close the popup (see note below)
+	cursor keys	select another entry
+	Tab		accept current suggestion
+
+A mouse click arrives as <LeftMouse>.  The coordinates can be obtained with
+|getmousepos()|.
+
+Vim provides standard filters |popup_filter_menu()| and
+|popup_filter_yesno()|.
+
+Keys coming from a `:normal` command do not pass through the filter.  This can
+be used to move the cursor in a popup where the "cursorline" option is set: >
+	call win_execute(winid, 'normal! 10Gzz')
+Keys coming from `feedkeys()` are passed through the filter.
+
+Note that "x" is the normal way to close a popup.  You may want to use Esc,
+but since many keys start with an Esc character, there may be a delay before
+Vim recognizes the Esc key.  If you do use Esc, it is recommended to set the
+'ttimeoutlen' option to 100 and set 'timeout' and/or 'ttimeout'.
+
+							*popup-filter-errors*
+If the filter function can't be called, e.g. because the name is wrong, then
+the popup is closed.  If the filter causes an error then it is assumed to
+return zero.  If this happens three times in a row the popup is closed.  If
+the popup gives errors fewer than 10% of the calls then it won't be closed.
+
+
+POPUP CALLBACK						*popup-callback*
+
+A callback that is invoked when the popup closes.
+
+The callback is invoked with two arguments: the ID of the popup window and the
+result, which could be an index in the popup lines, or whatever was passed as
+the second argument of `popup_close()`.
+
+If the popup is force-closed, e.g. because the cursor moved or CTRL-C was
+pressed, the number -1 is passed to the callback.
+
+Example: >
+	func SelectedColor(id, result)
+	   echo 'choice made: ' .. a:result
+	endfunc
+
+
+POPUP SCROLLBAR						*popup-scrollbar*
+
+If the text does not fit in the popup a scrollbar is displayed on the right of
+the window.  This can be disabled by setting the "scrollbar" option to zero.
+When the scrollbar is displayed mouse scroll events, while the mouse pointer
+is on the popup, will cause the text to scroll up or down as you would expect.
+A click in the upper half of the scrollbar will scroll the text down one line.
+A click in the lower half will scroll the text up one line.  However, this is
+limited so that the popup does not get smaller.
+
+
+POPUP MASK						*popup-mask*
+
+To minimize the text that the popup covers, parts of it can be made
+transparent.  This is defined by a "mask" which is a list of lists, where each
+list has four numbers:
+    col		start column, positive for counting from the left, 1 for
+		leftmost, negative for counting from the right, -1 for
+		rightmost
+    endcol	last column, like "col"
+    line	start line, positive for counting from the top, 1 for top,
+		negative for counting from the bottom, -1 for bottom
+    endline	end line, like "line"
+
+For example, to make the last 10 columns of the last line transparent:
+	[[-10, -1, -1, -1]]
+
+To make the four corners transparent:
+	[[1, 1, 1, 1], [-1, -1, 1, 1], [1, 1, -1, -1], [-1, -1, -1, -1]]
+
+==============================================================================
+4. Examples						*popup-examples*
+
+TODO: more interesting examples
+					*popup_dialog-example*
+Prompt the user to press y/Y or n/N: >
+
+	func MyDialogHandler(id, result)
+	   if a:result
+	      " ... 'y' or 'Y' was pressed
+	   endif
+	endfunc
+
+	call popup_dialog('Continue? y/n', #{
+		\ filter: 'popup_filter_yesno',
+		\ callback: 'MyDialogHandler',
+		\ })
+<
+					*popup_menu-shortcut-example*
+Extend popup_filter_menu() with shortcut keys: >
+
+	call popup_menu(['Save', 'Cancel', 'Discard'], #{
+		\ filter: 'MyMenuFilter',
+		\ callback: 'MyMenuHandler',
+		\ })
+
+	func MyMenuFilter(id, key)
+	  " Handle shortcuts
+	  if a:key == 'S'
+	     call popup_close(a:id, 1)
+	     return 1
+	  endif
+	  if a:key == 'C'
+	     call popup_close(a:id, 2)
+	     return 1
+	  endif
+	  if a:key == 'D'
+	     call popup_close(a:id, 3)
+	     return 1
+	  endif
+
+	  " No shortcut, pass to generic filter
+	  return popup_filter_menu(a:id, a:key)
+	endfunc
+<
+					*popup_beval_example*
+Example for using a popup window for 'ballooneval': >
+
+	set ballooneval balloonevalterm
+	set balloonexpr=BalloonExpr()
+	let s:winid = 0
+	let s:last_text = ''
+
+	func BalloonExpr()
+	  if s:winid && popup_getpos(s:winid) != {}
+	    " previous popup window still shows
+	    if v:beval_text == s:last_text
+	      " Still the same text, keep the existing popup
+	      return ''
+	    endif
+	    call popup_close(s:winid)
+	  endif
+	  let s:winid = popup_beval(v:beval_text, #{mousemoved: 'word'})
+	  let s:last_text = v:beval_text
+	  return ''
+	endfunc
+<
+If the text has to be obtained asynchronously return an empty string from the
+expression function and call popup_beval() once the text is available.  In
+this example simulated with a timer callback: >
+
+	set ballooneval balloonevalterm
+	set balloonexpr=BalloonExpr()
+	let s:winid = 0
+	let s:balloonText = ''
+
+	func BalloonExpr()
+	  if s:winid && popup_getpos(s:winid) != {}
+	    " previous popup window still shows
+	    if  v:beval_text == s:balloonText
+	      " Still the same text, keep the existing popup
+	      return ''
+	    endif
+	    call popup_close(s:winid)
+	    let s:winid = 0
+	  endif
+	  " simulate an asynchronous lookup for the text to display
+	  let s:balloonText = v:beval_text
+	  call timer_start(100, 'ShowPopup')
+	  return ''
+	endfunc
+
+	func ShowPopup(id)
+	  let s:winid = popup_beval(s:balloonText, #{mousemoved: 'word'})
+	endfunc
+<
+
+ vim:tw=78:ts=8:noet:ft=help:norl: