patch 8.1.1645: cannot use a popup window for a balloon

Problem:    Cannot use a popup window for a balloon.
Solution:   Add popup_beval().  Add the "mousemoved" property.  Add the
            screenpos() function.

runtime/doc/eval.txt

@@ -2535,6 +2535,7 @@ or({expr}, {expr})		Number	bitwise OR
 pathshorten({expr})		String	shorten directory names in a path
 perleval({expr})		any	evaluate |Perl| expression
 popup_atcursor({what}, {options}) Number create popup window near the cursor
+popup_beval({what}, {options}) 	Number 	create popup window for 'ballooneval'
 popup_clear()			none	close all popup windows
 popup_close({id} [, {result}])	none	close popup window {id}
 popup_create({what}, {options}) Number	create a popup window
@@ -2613,6 +2614,7 @@ screenattr({row}, {col})	Number	attribute at screen position
 screenchar({row}, {col})	Number	character at screen position
 screenchars({row}, {col})	List	List of characters at screen position
 screencol()			Number	current cursor column
+screenpos({winid}, {lnum}, {col}) Dict	screen row and col of a text character
 screenrow()			Number	current cursor row
 screenstring({row}, {col})	String	characters at screen position
 search({pattern} [, {flags} [, {stopline} [, {timeout}]]])
@@ -7907,6 +7909,23 @@ screencol()							*screencol()*
 			nnoremap <expr> GG ":echom ".screencol()."\n"
 			nnoremap <silent> GG :echom screencol()<CR>
 <
+screenpos({winid}, {lnum}, {col})				*screenpos()*
+		The result is a Dict with the screen position of the text
+		character in window {winid} at buffer line {lnum} and column
+		{col}.  {col} is a one-based byte index.
+		The Dict has these members:
+			row	screen row
+			col	first screen column
+			endcol	last screen column
+			curscol	cursor screen column
+		If the specified position is not visible, all values are zero.
+		The "endcol" value differs from "col" when the character
+		occupies more than one screen cell.  E.g. for a Tab "col" can
+		be 1 and "endcol" can be 8.
+		The "curscol" value is where the cursor would be placed.  For
+		a Tab it would be the same as "endcol", while for a double
+		width character it would be the same as "col".
+
 screenrow()							*screenrow()*
 		The result is a Number, which is the current screen row of the
 		cursor.  The top line has number one.

runtime/doc/popup.txt

@@ -146,6 +146,8 @@ 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
@@ -184,6 +186,20 @@ popup_atcursor({what}, {options})			*popup_atcursor()*
 <		Use {options} to change the properties.
 
 
+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.lnum - 1,
+			\ 'col': pos.col,
+			\ 'mousemoved': 'WORD',
+			\ })
+<		Use {options} to change the properties.
+		See |popup_beval_example| for an example use.
+
+
 							*popup_clear()*
 popup_clear()	Emergency solution to a misbehaving plugin: close all popup
 		windows for the current tab and global popups.
@@ -276,8 +292,11 @@ popup_getoptions({id})					*popup_getoptions()*
 		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 minimum and maximum column,
-		[0, 0] when not set.
+		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.
 
 		"border" and "padding" are not included when all values are
 		zero.  When all values are one then an empty list is included.
@@ -566,6 +585,7 @@ The second argument of |popup_create()| is a dictionary with options:
 			- "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}
 			The popup also closes if the cursor moves to another
@@ -736,5 +756,45 @@ Extend popup_filter_menu() with shortcut keys: >
 	  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
+
+	func BalloonExpr()
+	  if s:winid
+	    call popup_close(s:winid)
+	    let s:winid = 0
+	  endif
+	  let s:winid = popup_beval([bufname(v:beval_bufnr), 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 similated with a timer callback: >
+
+	set ballooneval balloonevalterm
+	set balloonexpr=BalloonExpr()
+	let s:winid = 0
+
+	func BalloonExpr()
+	  if s:winid
+	    call popup_close(s:winid)
+	    let s:winid = 0
+	  endif
+	  " simulate an asynchronous loopup for the text to display
+	  let s:balloonFile = bufname(v:beval_bufnr)
+	  let s:balloonWord = v:beval_text
+	  call timer_start(100, 'ShowPopup')
+	  return ''
+	endfunc
+
+	func ShowPopup(id)
+	  let s:winid = popup_beval([s:balloonFile, s:balloonWord], {})
+	endfunc
+<
 
  vim:tw=78:ts=8:noet:ft=help:norl:

runtime/doc/usr_41.txt

@@ -720,6 +720,7 @@ Cursor and mark position:		*cursor-functions* *mark-functions*
 	cursor()		position the cursor at a line/column
 	screencol()		get screen column of the cursor
 	screenrow()		get screen row of the cursor
+	screenpos()		screen row and col of a text character
 	getcurpos()		get position of the cursor
 	getpos()		get position of cursor, mark, etc.
 	setpos()		set position of cursor, mark, etc.
@@ -1046,6 +1047,8 @@ Popup window:					*popup-window-functions*
 	popup_create()		create popup centered in the screen
 	popup_atcursor()	create popup 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()		create popup centered with padding and border
 	popup_menu()		prompt for selecting an item from a list