patch 8.1.1513: all popup functionality is in functions, except :popupclear

Problem:    All popup functionality is in functions, except :popupclear.
Solution:   Add popup_clear() for consistency.  Also rename sound_stopall() to
            sound_clear().

Author: brammool

runtime/doc/eval.txt

@@ -1,4 +1,4 @@
-*eval.txt*	For Vim version 8.1.  Last change: 2019 Jun 06
+*eval.txt*	For Vim version 8.1.  Last change: 2019 Jun 10
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -2623,12 +2623,12 @@ sin({expr})			Float	sine of {expr}
 sinh({expr})			Float	hyperbolic sine of {expr}
 sort({list} [, {func} [, {dict}]])
 				List	sort {list}, using {func} to compare
+sound_clear()			none	stop playing all sounds
 sound_playevent({name} [, {callback}])
 				Number	play an event sound
-sound_playfile({name} [, {callback}])
-				Number	play a sound file
+sound_playfile({path} [, {callback}])
+				Number	play sound file {path}
 sound_stop({id})		none	stop playing sound {id}
-sound_stopall()			none	stop playing all sounds
 soundfold({word})		String	sound-fold {word}
 spellbadword()			String	badly spelled word at cursor
 spellsuggest({word} [, {max} [, {capital}]])
@@ -7360,7 +7360,7 @@ prop_remove({props} [, {lnum} [, {lnum-end}]])
 				not just the first one
 		A property matches when either "id" or "type" matches.
 		If buffer "bufnr" does not exist you get an error message.
-		If buffer 'bufnr" is not loaded then nothing happens.
+		If buffer "bufnr" is not loaded then nothing happens.
 
 		Returns the number of properties that were removed.
 
@@ -8852,6 +8852,10 @@ sort({list} [, {func} [, {dict}]])			*sort()* *E702*
 			   return a:i1 - a:i2
 			endfunc
 <
+sound_clear()						*sound_clear()*
+		Stop playing all sounds.
+		{only available when compiled with the +sound feature}
+
 							*sound_playevent()*
 sound_playevent({name} [, {callback}])
 		Play a sound identified by {name}.  Which event names are
@@ -8877,22 +8881,17 @@ sound_playevent({name} [, {callback}])
 		{only available when compiled with the +sound feature}
 
 							*sound_playfile()*
-sound_playfile({name} [, {callback}])
-		Like `sound_playevent()` but play sound file {name}.  {name}
+sound_playfile({path} [, {callback}])
+		Like `sound_playevent()` but play sound file {path}.  {path}
 		must be a full path.  On Ubuntu you may find files to play
 		with this command: >
 		    :!find /usr/share/sounds -type f | grep -v index.theme
-
 <		{only available when compiled with the +sound feature}
 
 
 sound_stop({id})					*sound_stop()*
 		Stop playing sound {id}.  {id} must be previously returned by
 		`sound_playevent()` or `sound_playfile()`.
-		{only available when compiled with the +sound feature}
-
-sound_stopall()						*sound_stopall()*
-		Stop playing all sounds.
 		{only available when compiled with the +sound feature}
 
 							*soundfold()*
@@ -13083,19 +13082,22 @@ Sometimes old syntax of functionality gets in the way of making Vim better.
 When support is taken away this will break older Vim scripts.  To make this
 explicit the |:scriptversion| command can be used.  When a Vim script is not
 compatible with older versions of Vim this will give an explicit error,
-instead of failing in mysterious ways. >
+instead of failing in mysterious ways.
 
+							*scriptversion-1*  >
  :scriptversion 1
 <	This is the original Vim script, same as not using a |:scriptversion|
 	command.  Can be used to go back to old syntax for a range of lines.
 	Test for support with: >
 		has('vimscript-1')
 
+<							*scriptversion-2*  >
  :scriptversion 2
 <	String concatenation with "." is not supported, use ".." instead.
 	This avoids the ambiguity using "." for Dict member access and
 	floating point numbers.  Now ".5" means the number 0.5.
->
+
+							*scriptversion-3*  >
  :scriptversion 3
 <	All |vim-variable|s must be prefixed by "v:".  E.g. "version" doesn't
 	work as |v:version| anymore, it can be used as a normal variable.

runtime/doc/popup.txt

@@ -1,4 +1,4 @@
-*popup.txt*  For Vim version 8.1.  Last change: 2019 Jun 02
+*popup.txt*  For Vim version 8.1.  Last change: 2019 Jun 09
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -89,15 +89,18 @@ Probably 2. is the best choice.
 
 
 IMPLEMENTATION:
-- Code is in popupwin.c
+- buffers remain after popup was deleted.
+- do not redraw whole window when popup was changed, mark affected lines for
+  redraw.
 - Why does 'nrformats' leak from the popup window buffer???
-- Make redrawing more efficient and avoid flicker.
-    First draw popups, creating a mask, use the mask in screen_line() when
-    drawing other windows and stuff.  Mask contains zindex of popups.
-    Keep mask until next update_screen(), use when drawing status lines.
-    Remove update_popup() calls after draw_tabline()/updating statusline
-    Fix redrawing problem with completion.
-    Fix redrawing problem when scrolling non-current window
+- Add 'balloonpopup': instead of showing text, let the callback open a balloon
+  and return the window ID.   The popup will then be closed when the mouse
+  moves, except when it moves inside the popup.
+- For the "moved" property also include mouse movement?
+- Make redrawing more efficient and avoid flicker:
+    - put popup menu also put in popup_mask?
+    - Use changes in popup_mask to decide what windows and range of lines to
+      redraw?
 - Disable commands, feedkeys(), CTRL-W, etc. in a popup window.
   Use NOT_IN_POPUP_WINDOW for more commands.
 - Invoke filter with character before mapping?
@@ -115,6 +118,33 @@ THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE
 
 [functions to be moved to eval.txt later, keep overview of functions here]
 
+popup_atcursor({text}, {options})			 *popup_atcursor()*
+		Show the {text} above the cursor, and close it when the cursor
+		moves.  This works like: >
+			call popup_create({text}, {
+				\ 'pos': 'botleft',
+				\ 'line': 'cursor-1',
+				\ 'col': 'cursor',
+				\ 'moved': 'WORD',
+				\ })
+<		Use {options} to change the properties.
+
+
+							*popup_clear()*
+popup_clear()	Emergency solution to a misbehaving plugin: close all popup
+		windows.
+
+
+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.
+
+
 popup_create({text}, {options})				*popup_create()*
 		Open a popup window showing {text}, which is either:
 		- a string
@@ -133,16 +163,6 @@ popup_create({text}, {options})				*popup_create()*
 <		In case of failure zero is returned.
 
 
-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.
-
-
 popup_dialog({text}, {options})				*popup_dialog()*
 	  	{not implemented yet}
 		Just like |popup_create()| but with these default options: >
@@ -155,70 +175,6 @@ popup_dialog({text}, {options})				*popup_dialog()*
 <		Use {options} to change the properties.
 
 
-popup_notification({text}, {options})			 *popup_notification()*
-	  	{not implemented yet}
-		Show the {text} for 3 seconds at the top of the Vim window.
-		This works like: >
-			call popup_create({text}, {
-				\ 'line': 1,
-				\ 'col': 10,
-				\ 'time': 3000,
-				\ 'tab': -1,
-				\ 'zindex': 200,
-				\ 'highlight': 'WarningMsg',
-				\ 'border': [],
-				\ })
-<		Use {options} to change the properties.
-
-
-popup_atcursor({text}, {options})			 *popup_atcursor()*
-		Show the {text} above the cursor, and close it when the cursor
-		moves.  This works like: >
-			call popup_create({text}, {
-				\ 'pos': 'botleft',
-				\ 'line': 'cursor-1',
-				\ 'col': 'cursor',
-				\ 'moved': 'WORD',
-				\ })
-<		Use {options} to change the properties.
-
-
-popup_menu({text}, {options})				 *popup_menu()*
-	  	{not implemented yet}
-		Show the {text} near the cursor, handle selecting one of the
-		items with cursorkeys, and close it an item is selected with
-		Space or Enter. {text} should have multiple lines to make this
-		useful.  This works like: >
-			call popup_create({text}, {
-				\ '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_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*
-
-popup_show({id})						*popup_show()*
-		If {id} is a hidden popup, show it now.
-		For {id} see `popup_hide()`.
-
-popup_move({id}, {options})					*popup_move()*
-		Move popup {id} to the position speficied with {options}.
-		{options} may contain the items from |popup_create()| that
-		specify the popup position: "line", "col", "pos", "maxheight",
-		"minheight", "maxwidth" and "minwidth".
-		For {id} see `popup_hide()`.
-
-
 popup_filter_menu({id}, {key})				*popup_filter_menu()*
 	  	{not implemented yet}
 		Filter that can be used for a popup. It handles the cursor
@@ -237,11 +193,6 @@ popup_filter_yesno({id}, {key})				*popup_filter_yesno()*
 		pressing 'n'.
 
 
-popup_setoptions({id}, {options})			*popup_setoptions()*
-	  	{not implemented yet}
-		Override options in popup {id} with entries in {options}.
-
-
 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
@@ -253,6 +204,7 @@ popup_getoptions({id})					*popup_getoptions()*
 
 <		If popup window {id} is not found an empty Dict is returned.
 
+
 popup_getpos({id})					*popup_getpos()*
 		Return the position and size of popup {id}.  Returns a Dict
 		with these entries:
@@ -274,9 +226,64 @@ popup_getpos({id})					*popup_getpos()*
 		If popup window {id} is not found an empty Dict is returned.
 
 
-							*:popupclear* *:popupc*
-:popupc[lear]	Emergency solution to a misbehaving plugin: close all popup
-		windows.
+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*
+
+
+popup_menu({text}, {options})				 *popup_menu()*
+	  	{not implemented yet}
+		Show the {text} near the cursor, handle selecting one of the
+		items with cursorkeys, and close it an item is selected with
+		Space or Enter. {text} should have multiple lines to make this
+		useful.  This works like: >
+			call popup_create({text}, {
+				\ '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_create()| that
+		specify the popup position: "line", "col", "pos", "maxheight",
+		"minheight", "maxwidth" and "minwidth".
+		For {id} see `popup_hide()`.
+
+
+popup_notification({text}, {options})			 *popup_notification()*
+	  	{not implemented yet}
+		Show the {text} for 3 seconds at the top of the Vim window.
+		This works like: >
+			call popup_create({text}, {
+				\ 'line': 1,
+				\ 'col': 10,
+				\ 'time': 3000,
+				\ 'tab': -1,
+				\ 'zindex': 200,
+				\ 'highlight': 'WarningMsg',
+				\ 'border': [],
+				\ })
+<		Use {options} to change the properties.
+
+
+popup_show({id})						*popup_show()*
+		If {id} is a hidden popup, show it now.
+		For {id} see `popup_hide()`.
+
+
+popup_setoptions({id}, {options})			*popup_setoptions()*
+	  	{not implemented yet}
+		Override options in popup {id} with entries in {options}.
+
 
 
 POPUP BUFFER AND WINDOW					*popup-buffer*
@@ -405,7 +412,8 @@ The second argument of |popup_create()| is a dictionary with options:
 			By default a double line is used all around when
 			'encoding' is "utf-8", otherwise ASCII characters are
 			used.
-	zindex		Priority for the popup, default 50.
+	zindex		Priority for the popup, default 50.  Mininum value is
+			1, maximum value is 32000.
 	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:
@@ -496,7 +504,7 @@ Vim provides standard filters |popup_filter_menu()| and
 
 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 reecommended to set the
+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'.
 
 

src/evalfunc.c

@@ -812,6 +812,7 @@ static struct fst
 #endif
 #ifdef FEAT_TEXT_PROP
     {"popup_atcursor",	2, 2, f_popup_atcursor},
+    {"popup_clear",	0, 0, f_popup_clear},
     {"popup_close",	1, 2, f_popup_close},
     {"popup_create",	2, 2, f_popup_create},
     {"popup_getoptions", 1, 1, f_popup_getoptions},
@@ -928,10 +929,10 @@ static struct fst
 #endif
     {"sort",		1, 3, f_sort},
 #ifdef FEAT_SOUND
+    {"sound_clear",	0, 0, f_sound_clear},
     {"sound_playevent",	1, 2, f_sound_playevent},
     {"sound_playfile",	1, 2, f_sound_playfile},
     {"sound_stop",	1, 1, f_sound_stop},
-    {"sound_stopall",	0, 0, f_sound_stopall},
 #endif
     {"soundfold",	1, 1, f_soundfold},
     {"spellbadword",	0, 1, f_spellbadword},