patch 8.1.2304: cannot get the mouse position when getting a mouse clickv8.1.2304

Problem:    Cannot get the mouse position when getting a mouse click.
Solution:   Add getmousepos().

2 files changed, 35 insertions, 10 deletions

diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 9ba53887be..9bac54e990 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -1956,15 +1956,11 @@ v:mouse_winid	Window ID for a mouse click obtained with |getchar()|.
 
 					*v:mouse_lnum* *mouse_lnum-variable*
 v:mouse_lnum	Line number for a mouse click obtained with |getchar()|.
-		Also used for a click in a popup window when the filter is
-		invoked.
 		This is the text line number, not the screen line number.  The
 		value is zero when there was no mouse button click.
 
 					*v:mouse_col* *mouse_col-variable*
 v:mouse_col	Column number for a mouse click obtained with |getchar()|.
-		Also used for a click in a popup window when the filter is
-		invoked.
 		This is the screen column number, like with |virtcol()|.  The
 		value is zero when there was no mouse button click.
 
@@ -2484,6 +2480,7 @@ getline({lnum})			String	line {lnum} of current buffer
 getline({lnum}, {end})		List	lines {lnum} to {end} of current buffer
 getloclist({nr} [, {what}])	List	list of location list items
 getmatches([{win}])		List	list of current matches
+getmousepos()			Dict	last known mouse position
 getpid()			Number	process ID of Vim
 getpos({expr})			List	position of cursor, mark, etc.
 getqflist([{what}])		List	list of quickfix items
@@ -4922,8 +4919,9 @@ getchar([expr])						*getchar()*
 
 		When the user clicks a mouse button, the mouse event will be
 		returned.  The position can then be found in |v:mouse_col|,
-		|v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|.  This
-		example positions the mouse as it would normally happen: >
+		|v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|.
+		|getmousepos()| can also be used.  This example positions the
+		mouse as it would normally happen: >
 			let c = getchar()
 			if c == "\<LeftMouse>" && v:mouse_win > 0
 			  exe v:mouse_win . "wincmd w"
@@ -5333,6 +5331,35 @@ getmatches([{win}])					*getmatches()*
 			'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
 			:unlet m
 <
+getmousepos()						*getmousepos()*
+		Returns a Dictionary with the last known position of the
+		mouse.  This can be used in a mapping for a mouse click or in
+		a filter of a popup window.  The items are:
+			screenrow	screen row
+			screencol	screen column
+			winid		Window ID of the click
+			winrow		row inside "winid"
+			wincol		column inside "winid"
+			line		text line inside "winid"
+			column		text column inside "winid"
+		All numbers are 1-based.
+
+		If not over a window, e.g. when in the command line, then only
+		"screenrow" and "screencol" are valid, the others are zero.
+
+		When on the status line below a window or the vertical
+		separater right of a window, the "line" and "column" values
+		are zero.
+
+		When the position is after the text then "column" is the
+		length of the text in bytes.
+
+		If the mouse is over a popup window then that window is used.
+
+
+		When using |getchar()| the Vim variables |v:mouse_lnum|,
+		|v:mouse_col| and |v:mouse_winid| also provide these values.
+
 							*getpid()*
 getpid()	Return a Number which is the process ID of the Vim process.
 		On Unix and MS-Windows this is a unique number, until Vim
diff --git a/runtime/doc/popup.txt b/runtime/doc/popup.txt
index 39e4a3ce83..bdd8272811 100644
--- a/runtime/doc/popup.txt
+++ b/runtime/doc/popup.txt
@@ -862,10 +862,8 @@ Some recommended key actions:
 	cursor keys	select another entry
 	Tab		accept current suggestion
 
-A mouse click arrives as <LeftMouse>.  The coordinates are in |v:mouse_col|
-and |v:mouse_lnum|.  |v:mouse_winid| holds the window ID, |v:mouse_win| is
-always zero.  The top-left screen cell of the popup is col 1, row 1 (not
-counting the border).
+A mouse click arrives as <LeftMouse>.  The coordinates can be obtained with
+|mousegetpos()|.
 
 Vim provides standard filters |popup_filter_menu()| and
 |popup_filter_yesno()|.