patch 9.1.1070: Cannot control cursor positioning of getchar()

Problem:  Cannot control cursor positioning of getchar().
Solution: Add "cursor" flag to {opts}, with possible values "hide",
          "keep" and "msg".

related: #10603
closes: #16569

Signed-off-by: zeertzjq <zeertzjq@outlook.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>

runtime/doc/builtin.txt

@@ -3953,6 +3953,13 @@ getchar([{expr} [, {opts}]])				*getchar()*
 		The optional argument {opts} is a Dict and supports the
 		following items:
 
+			cursor		A String specifying cursor behavior
+					when waiting for a character.
+					"hide": hide the cursor.
+					"keep": keep current cursor unchanged.
+					"msg": move cursor to message area.
+					(default: "msg")
+
 			number		If |TRUE|, return a Number when getting
 					a single character.
 					If |FALSE|, the return value is always

runtime/doc/todo.txt

@@ -1,4 +1,4 @@
-*todo.txt*      For Vim version 9.1.  Last change: 2025 Jan 16
+*todo.txt*      For Vim version 9.1.  Last change: 2025 Feb 02
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -467,9 +467,6 @@ IDEA: when drawing the text, store the text byte index in ScreenLinesIdx[].
 When converting screen column to text position use this.
 The line number can be obtained from win->w_lines[].
 
-Version of getchar() that does not move the cursor - #10603 Use a separate
-argument for the new flag.
-
 test_arglist func Test_all_not_allowed_from_cmdwin() hangs on MS-Windows.
 
 Can we add highlighting to ":echowindow"?

runtime/doc/version9.txt

@@ -41636,6 +41636,8 @@ Changed~
 - add |dist#vim9#Launch()| and |dist#vim9#Open()| to the |vim-script-library|
   and decouple it from |netrw|
 - new digraph "APPROACHES THE LIMIT" using ".="
+- Add the optional {opts} |Dict| argument to |getchar()| to control: cursor
+  behaviour, return type and whether or not to simplify the returned key
 
 							*added-9.2*
 Added ~