patch 8.1.1329: plans for popup window support are spread out

Problem:    Plans for popup window support are spread out.
Solution:   Add a first version of the popup window help.

runtime/doc/Makefile

@@ -83,6 +83,7 @@ DOCS = \
 	pi_tar.txt \
 	pi_vimball.txt \
 	pi_zip.txt \
+	popup.txt \
 	print.txt \
 	quickfix.txt \
 	quickref.txt \
@@ -220,6 +221,7 @@ HTMLS = \
 	pi_tar.html \
 	pi_vimball.html \
 	pi_zip.html \
+	popup.html \
 	print.html \
 	quickfix.html \
 	quickref.html \

runtime/doc/help.txt

@@ -143,6 +143,7 @@ Special issues ~
 |remote.txt|	using Vim as a server or client
 |term.txt|	using different terminals and mice
 |terminal.txt|	Terminal window support
+|popup.txt|	popop window support
 
 Programming language support ~
 |indent.txt|	automatic indenting for C and other languages

runtime/doc/popup.txt

@@ -0,0 +1,274 @@
+*popup.txt*  For Vim version 8.1.  Last change: 2019 May 12
+
+
+		  VIM REFERENCE MANUAL    by Bram Moolenaar
+
+
+Displaying text with properties attached.	*popup* *popup-window*
+
+THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE  
+
+1. Introduction			|popup-intro|
+2. Functions			|popup-functions|
+3. Examples			|popup-examples|
+
+
+{not able to use text properties when the |+textprop| feature was
+disabled at compile time}
+
+==============================================================================
+1. Introduction						*popup-intro*
+
+We are talking about popup windows here, text that goes on top of the buffer
+text and is under control of a plugin.  Other popup functionality:
+- popup menu, see |popup-menu|
+- balloon, see |balloon-eval|
+
+TODO
+
+==============================================================================
+2. Functions						*popup-functions*
+
+THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE  
+
+Proposal and discussion on issue #4063: https://github.com/vim/vim/issues/4063
+
+[to be moved to eval.txt later]
+
+popup_show({lines}, {options})				*popup_show()*
+		Open a popup window showing {lines}, which is a list of lines,
+		where each line has text and text properties.
+
+		{options} is a dictionary with many possible entries.
+
+		Returns a unique ID to be used with |popup_close()|.
+
+		See |popup_show-usage| for details.
+
+
+popup_dialog({lines}, {options})			*popup_dialog()*
+		Just like |popup_show()| but with different default options:
+			pos		"center"
+			zindex		200
+			border		[]
+
+
+popup_notification({text}, {options})			 *popup_notification()*
+		Show the string {text} for 3 seconds at the top of the Vim
+		window.  This works like: >
+			call popup_show([{'text': {text}}], {
+				\ 'line': 1,
+				\ 'col': 10,
+				\ 'time': 3000,
+				\ 'zindex': 200,
+				\ 'highlight': 'WarningMsg',
+				\ 'border: [],
+				\ })
+<		Use {options} to change the properties.
+
+popup_atcursor({text}, {options})			 *popup_atcursor()*
+		Show the string {text} above the cursor, and close it when the
+		cursor moves.  This works like: >
+			call popup_show([{'text': {text}}], {
+				\ 'line': 'cursor-1',
+				\ 'col': 'cursor',
+				\ 'zindex': 50,
+				\ 'moved': 'WORD',
+				\ })
+<		Use {options} to change the properties.
+
+
+popup_menu({lines}, {options})			 *popup_atcursor()*
+		Show the {lines} near the cursor, handle selecting one of the
+		items with cursorkeys, and close it an item is selected with
+		Space or Enter.  This works like: >
+			call popup_show({lines}, {
+				\ 'pos': 'center',
+				\ 'zindex': 200,
+				\ 'wrap': 0,
+				\ 'border': [],
+				\ 'filter': 'popup_filter_menu',
+				\ })
+<		Use {options} to change the properties.  Should at least set
+		"callback" to a function that handles the selected item.
+
+
+popup_move({id}, {options})					*popup_move()*
+		Move popup {id} to the position speficied with {options}.
+		{options} may contain the items from |popup_show()| that
+		specify the popup position: "line", "col", "pos", "maxheight",
+		"minheight", "maxwidth" and "minwidth".
+
+
+popup_filter_menu({id}, {key})				*popup_filter_menu()*
+		Filter that can be used for a popup. It handles the cursor
+		keys to move the selected index in the popup. Space and Enter
+		can be used to select an item.  Invokes the "callback" of the
+		popup menu with the index of the selected line as the second
+		argument.
+
+
+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 CTRL-C works like
+		pressing 'n'.
+
+
+popup_setlines({id}, {lnum}, {lines})			*popup_setlines()*
+		In popup {id} set line {lnum} and following to {lines}.
+
+		{lnum} is one-based and must be either an existing line or
+		just one below the last line, in which case the line gets
+		appended.
+
+		{lines} has the same format as one item in {lines} of
+		|popup_show()|.  Existing lines are replaced. When {lines}
+		extends below the last line of the popup lines are appended.
+
+popup_getlines({id})					*popup_getlines()*
+		Return the {lines} for popup {id}.
+
+
+popup_setoptions({id}, {options})			*popup_setoptions()*
+		Override options in popup {id} with entries in {options}.
+
+
+popup_getoptions({id})					*popup_getoptions()*
+		Return the {options} for popup {id}.
+
+
+popup_close({id})					*popup_close()*
+		Close popup {id}.
+
+
+POPUP_SHOW() ARGUMENTS					*popup_show-usage*
+
+The first argument of |popup_show()| is a list of text lines.  Each item in
+the list is a dictionary with these entries:
+	text		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|.
+
+The second argument of |popup_show()| is a dictionary with options:
+	line		screen line where to position the popup; can use
+			"cursor", "cursor+1" or "cursor-1" to use the line of
+			the cursor and add or subtract a number of lines;
+			default is "cursor-1".
+	col		screen column where to position the popup; can use
+			"cursor" to use the column of the cursor, "cursor+99"
+			and "cursor-99" to add or subtract a number of
+			columns; default is "cursor"
+	pos		"topleft", "topright", "botleft" or "botright":
+			defines what corner of the popup "line" and "col" are
+			used for.  Default is "botleft".  Alternatively
+			"center" can be used to position the popup somewhere
+			near the cursor.
+	maxheight	maximum height
+	minheight	minimum height
+	maxwidth	maximum width
+	minwidth	minimum width
+	title		text to be displayed above the first item in the
+			popup, on top of any border
+	wrap		TRUE to make the lines wrap (default TRUE)
+	highlight	highlight group name to use for the text, defines the
+			background and foreground color
+	border		list with numbers, defining the border thickness
+			above/right/below/left of the popup; an empty list
+			uses a border of 1 all around
+	borderhighlight	highlight group name to use for the border
+	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
+			topright/botright/botleft/topleft corner; an empty
+			list can be used to show a double line all around
+	zindex		priority for the popup, default 50
+	time		time in milliseconds after which the popup will close;
+			when omitted |popup_close()| must be used.
+	moved		"cell": close the popup if the cursor moved at least
+			one screen cell; "word" allows for moving within
+			|<cword>|, "WORD" allows for moving within |<cWORD>|,
+			a list with two numbers specifies the start and end
+			column
+	filter		a callback that can filter typed characters, see 
+			|popup-filter|
+	callback	a callback to be used 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()|, but not exactly the
+same, since they only apply to one line.
+	col		starting column, counted in bytes, use one for the
+			first column.
+	length		length of text in bytes; can be zero
+	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()|
+	transparent	do not show these characters, show the text under it;
+			if there is an border character to the right or below
+			it will be made transparent as well
+
+
+POPUP FILTER						*popup-filter*
+
+A callback that gets any typed keys while a popup is displayed.  It 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.
+
+The filter function is called with two arguments: the ID of the popup and the
+key.
+
+Some common key actions:
+	Esc		close the popup
+	cursor keys	select another entry
+	Tab		accept current suggestion
+
+Vim provides standard filters |popup_filter_menu()| and
+|popup_filter_yesno()|.
+
+
+POPUP CALLBACK						*popup-callback*
+
+A callback that is invoked when the popup closes.  Used by
+|popup_filter_menu()|.  Invoked with two arguments: the ID of the popup and
+the result, which would usually be an index in the popup lines, or whatever
+the filter wants to pass.
+
+==============================================================================
+3. Examples						*popup-examples*
+
+TODO
+
+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_show([{'text': 'Continue? y/n'}], {
+		\ 'filter': 'popup_filter_yesno',
+		\ 'callback': 'MyDialogHandler',
+		\ })
+<
+
+ vim:tw=78:ts=8:noet:ft=help:norl:

src/version.c

@@ -767,6 +767,8 @@ static char *(features[]) =
 
 static int included_patches[] =
 {   /* Add new patch number below this line */
+/**/
+    1329,
 /**/
     1328,
 /**/