path: root/data/vim/patches/8.1.1329

To: vim_dev@googlegroups.com
Subject: Patch 8.1.1329
Fcc: outbox
From: Bram Moolenaar <Bram@moolenaar.net>
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
------------

Patch 8.1.1329
Problem:    Plans for popup window support are spread out.
Solution:   Add a first version of the popup window help.
Files:	    runtime/doc/popup.txt, runtime/doc/Makefile, runtime/doc/help.txt


*** ../vim-8.1.1328/runtime/doc/popup.txt	2019-05-12 21:43:02.490679879 +0200
--- runtime/doc/popup.txt	2019-05-12 21:36:26.116844754 +0200
***************
*** 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:
*** ../vim-8.1.1328/runtime/doc/Makefile	2018-12-13 22:17:52.865941558 +0100
--- runtime/doc/Makefile	2019-05-12 17:14:48.011704406 +0200
***************
*** 83,88 ****
--- 83,89 ----
  	pi_tar.txt \
  	pi_vimball.txt \
  	pi_zip.txt \
+ 	popup.txt \
  	print.txt \
  	quickfix.txt \
  	quickref.txt \
***************
*** 220,225 ****
--- 221,227 ----
  	pi_tar.html \
  	pi_vimball.html \
  	pi_zip.html \
+ 	popup.html \
  	print.html \
  	quickfix.html \
  	quickref.html \
*** ../vim-8.1.1328/runtime/doc/help.txt	2019-05-05 18:11:46.312590682 +0200
--- runtime/doc/help.txt	2019-05-12 16:52:31.295380271 +0200
***************
*** 143,148 ****
--- 143,149 ----
  |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
*** ../vim-8.1.1328/src/version.c	2019-05-12 14:36:22.938437845 +0200
--- src/version.c	2019-05-12 21:42:27.510870927 +0200
***************
*** 769,770 ****
--- 769,772 ----
  {   /* Add new patch number below this line */
+ /**/
+     1329,
  /**/

-- 
If you don't get everything you want, think of
everything you didn't get and don't want.

 /// Bram Moolenaar -- Bram@Moolenaar.net -- http://www.Moolenaar.net   \\\
///        sponsor Vim, vote for features -- http://www.Vim.org/sponsor/ \\\
\\\  an exciting new programming language -- http://www.Zimbu.org        ///
 \\\            help me help AIDS victims -- http://ICCF-Holland.org    ///