patch 9.1.0050: Win32 Keyboard handling is sub-optimalv9.1.0050

Problem:  Win32 Keyboard handling is sub-optimal and has
          many issues with international keyboards
          (risa2000) (after v8.2.4807)
Solution: soft-rollback the change, allow the user to select
          a suitable key-translation strategy
          (Anton Sharonov)

Read about the details in the help:
    :h w32-experimental-keycode-trans-strategy

fixes: #10615
fixes: #12595
closes: #12752

Signed-off-by: Anton Sharonov <anton.sharonov@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>

3 files changed, 47 insertions, 2 deletions

diff --git a/runtime/doc/gui_w32.txt b/runtime/doc/gui_w32.txt
index 780c0a00fa..c6f5725d82 100644
--- a/runtime/doc/gui_w32.txt
+++ b/runtime/doc/gui_w32.txt
@@ -1,4 +1,4 @@
-*gui_w32.txt*   For Vim version 9.1.  Last change: 2022 Mar 09
+*gui_w32.txt*   For Vim version 9.1.  Last change: 2024 Jan 23
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -454,4 +454,38 @@ You may need to get the vim16x16.xpm file from github:
 https://github.com/vim/vim/blob/master/runtime/vim16x16.xpm
 
 
+Keycode translation strategy    *w32-experimental-keycode-trans-strategy*
+
+In Patch v8.2.4807 W32 GVIM was changed over to experimental keycode
+translation method with the aim to be able to use more keyboard shortcuts and
+especially supporting non-standard keyboard layouts. In order to implement
+this support Win API TranslateMessage() call was dropped, and instead the
+recognition of keycode was changed over to ToUnicode() Win API call. This
+approach uncovered numerous corner cases, which are apparently covered by
+TranslateMessage() implementation, each of it is necessary to be dealt with on
+an individual basis. Therefore the decision was taken to declare this
+functionality experimental for the time being and to recover "classic" keycode
+translation method as default again.
+
+Discussion about use of "experimental" keycode translation method will
+probably last some time yet. In the meantime, if you are impacted by this
+change over back to "classic" keycode translation method in W32 GVIM, you can
+enable "experimental" translation method again in your vimrc using following
+snippet:
+>
+  :call test_mswin_event('set_keycode_trans_strategy', {'strategy': 'experimental'})
+<
+Similarly, in case you need to turn back "classic" keycode translation method
+(for example for testing purposes), please use:
+>
+  :call test_mswin_event('set_keycode_trans_strategy', {'strategy': 'classic'})
+<
+Alternatively (this method is especially useful for the TINY GVIM build, where
+test_mswin_event() cannot be called), an environment variable
+VIM_KEYCODE_TRANS_STRATEGY can be set to the desired value ("experimental" or
+"classic"), to override the default, e.g., type in dos prompt:
+>
+        set VIM_KEYCODE_TRANS_STRATEGY=experimental
+        gvim.exe
+<
  vim:tw=78:sw=4:ts=8:noet:ft=help:norl:
diff --git a/runtime/doc/tags b/runtime/doc/tags
index 46a396e9fc..809c6fd33f 100644
--- a/runtime/doc/tags
+++ b/runtime/doc/tags
@@ -11189,6 +11189,7 @@ vt100-cursor-keys	term.txt	/*vt100-cursor-keys*
 vt100-function-keys	term.txt	/*vt100-function-keys*
 w	motion.txt	/*w*
 w32-clientserver	remote.txt	/*w32-clientserver*
+w32-experimental-keycode-trans-strategy	gui_w32.txt	/*w32-experimental-keycode-trans-strategy*
 w32-xpm-support	gui_w32.txt	/*w32-xpm-support*
 w:	eval.txt	/*w:*
 w:current_syntax	syntax.txt	/*w:current_syntax*
diff --git a/runtime/doc/testing.txt b/runtime/doc/testing.txt
index dabdd32b02..442285dc86 100644
--- a/runtime/doc/testing.txt
+++ b/runtime/doc/testing.txt
@@ -1,4 +1,4 @@
-*testing.txt*	For Vim version 9.1.  Last change: 2023 May 18
+*testing.txt*	For Vim version 9.1.  Last change: 2024 Jan 23
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -234,6 +234,8 @@ test_mswin_event({event}, {args})		*test_mswin_event()*
 		{event} is a String and the supported values are:
 		    "mouse"	mouse event.
 		    "key"	keyboard event.
+		    "set_keycode_trans_strategy"
+				Change the key transation method
 
 		"mouse":
 		  Inject either a mouse button click, or a mouse move, event.
@@ -290,6 +292,14 @@ test_mswin_event({event}, {args})		*test_mswin_event()*
 				unprocessed key events.  All other {args}
 				items are optional when this is set and true.
 
+		"set_keycode_trans_strategy":
+		  |w32-experimental-keycode-trans-strategy|
+		  Switch the keycode translation method. The supported methods are:
+		    experimental:   The method used after Patch v8.2.4807
+				    using ToUnicode() Win API call.
+		    classic:	    The method used pre Patch v8.2.4807
+				    using the TranslateMessage() Win API call.
+
 		Returns TRUE if the event is successfully added or executed,
 		FALSE if there is a failure.