Merge pull request #70052 from bruvzg/key_unicode_actions

Cleanup and unify keyboard input.

4 files changed, 73 insertions, 226 deletions

diff --git a/doc/classes/@GlobalScope.xml b/doc/classes/@GlobalScope.xml
index 7e7cb07cef..2be15d5100 100644
--- a/doc/classes/@GlobalScope.xml
+++ b/doc/classes/@GlobalScope.xml
@@ -1767,30 +1767,15 @@
 		<constant name="KEY_KP_9" value="4194447" enum="Key">
 			Number 9 on the numeric keypad.
 		</constant>
-		<constant name="KEY_SUPER_L" value="4194368" enum="Key">
-			Left Super key (Windows key).
-		</constant>
-		<constant name="KEY_SUPER_R" value="4194369" enum="Key">
-			Right Super key (Windows key).
-		</constant>
 		<constant name="KEY_MENU" value="4194370" enum="Key">
 			Context menu key.
 		</constant>
-		<constant name="KEY_HYPER_L" value="4194371" enum="Key">
-			Left Hyper key.
-		</constant>
-		<constant name="KEY_HYPER_R" value="4194372" enum="Key">
-			Right Hyper key.
+		<constant name="KEY_HYPER" value="4194371" enum="Key">
+			Hyper key. (On Linux/X11 only).
 		</constant>
 		<constant name="KEY_HELP" value="4194373" enum="Key">
 			Help key.
 		</constant>
-		<constant name="KEY_DIRECTION_L" value="4194374" enum="Key">
-			Left Direction key.
-		</constant>
-		<constant name="KEY_DIRECTION_R" value="4194375" enum="Key">
-			Right Direction key.
-		</constant>
 		<constant name="KEY_BACK" value="4194376" enum="Key">
 			Media back key. Not to be confused with the Back button on an Android device.
 		</constant>
@@ -1812,21 +1797,6 @@
 		<constant name="KEY_VOLUMEUP" value="4194382" enum="Key">
 			Volume up key.
 		</constant>
-		<constant name="KEY_BASSBOOST" value="4194383" enum="Key">
-			Bass Boost key.
-		</constant>
-		<constant name="KEY_BASSUP" value="4194384" enum="Key">
-			Bass up key.
-		</constant>
-		<constant name="KEY_BASSDOWN" value="4194385" enum="Key">
-			Bass down key.
-		</constant>
-		<constant name="KEY_TREBLEUP" value="4194386" enum="Key">
-			Treble up key.
-		</constant>
-		<constant name="KEY_TREBLEDOWN" value="4194387" enum="Key">
-			Treble down key.
-		</constant>
 		<constant name="KEY_MEDIAPLAY" value="4194388" enum="Key">
 			Media play key.
 		</constant>
@@ -1911,7 +1881,7 @@
 		<constant name="KEY_LAUNCHF" value="4194415" enum="Key">
 			Launch Shortcut F key.
 		</constant>
-		<constant name="KEY_UNKNOWN" value="16777215" enum="Key">
+		<constant name="KEY_UNKNOWN" value="8388607" enum="Key">
 			Unknown key.
 		</constant>
 		<constant name="KEY_SPACE" value="32" enum="Key">
@@ -2121,203 +2091,23 @@
 		<constant name="KEY_ASCIITILDE" value="126" enum="Key">
 			~ key.
 		</constant>
-		<constant name="KEY_NOBREAKSPACE" value="160" enum="Key">
-			Non-breakable space key.
-		</constant>
-		<constant name="KEY_EXCLAMDOWN" value="161" enum="Key">
-			¡ key.
-		</constant>
-		<constant name="KEY_CENT" value="162" enum="Key">
-			¢ key.
-		</constant>
-		<constant name="KEY_STERLING" value="163" enum="Key">
-			£ key.
-		</constant>
-		<constant name="KEY_CURRENCY" value="164" enum="Key">
-			¤ key.
-		</constant>
 		<constant name="KEY_YEN" value="165" enum="Key">
 			¥ key.
 		</constant>
-		<constant name="KEY_BROKENBAR" value="166" enum="Key">
-			¦ key.
-		</constant>
 		<constant name="KEY_SECTION" value="167" enum="Key">
 			§ key.
 		</constant>
-		<constant name="KEY_DIAERESIS" value="168" enum="Key">
-			¨ key.
-		</constant>
-		<constant name="KEY_COPYRIGHT" value="169" enum="Key">
-			© key.
-		</constant>
-		<constant name="KEY_ORDFEMININE" value="170" enum="Key">
-			ª key.
-		</constant>
-		<constant name="KEY_GUILLEMOTLEFT" value="171" enum="Key">
-			« key.
-		</constant>
-		<constant name="KEY_NOTSIGN" value="172" enum="Key">
-			¬ key.
-		</constant>
-		<constant name="KEY_HYPHEN" value="173" enum="Key">
-			Soft hyphen key.
-		</constant>
-		<constant name="KEY_REGISTERED" value="174" enum="Key">
-			® key.
-		</constant>
-		<constant name="KEY_MACRON" value="175" enum="Key">
-			¯ key.
-		</constant>
-		<constant name="KEY_DEGREE" value="176" enum="Key">
-			° key.
-		</constant>
-		<constant name="KEY_PLUSMINUS" value="177" enum="Key">
-			± key.
-		</constant>
-		<constant name="KEY_TWOSUPERIOR" value="178" enum="Key">
-			² key.
-		</constant>
-		<constant name="KEY_THREESUPERIOR" value="179" enum="Key">
-			³ key.
-		</constant>
-		<constant name="KEY_ACUTE" value="180" enum="Key">
-			´ key.
-		</constant>
-		<constant name="KEY_MU" value="181" enum="Key">
-			µ key.
-		</constant>
-		<constant name="KEY_PARAGRAPH" value="182" enum="Key">
-			¶ key.
-		</constant>
-		<constant name="KEY_PERIODCENTERED" value="183" enum="Key">
-			· key.
-		</constant>
-		<constant name="KEY_CEDILLA" value="184" enum="Key">
-			¸ key.
-		</constant>
-		<constant name="KEY_ONESUPERIOR" value="185" enum="Key">
-			¹ key.
-		</constant>
-		<constant name="KEY_MASCULINE" value="186" enum="Key">
-			º key.
-		</constant>
-		<constant name="KEY_GUILLEMOTRIGHT" value="187" enum="Key">
-			» key.
-		</constant>
-		<constant name="KEY_ONEQUARTER" value="188" enum="Key">
-			¼ key.
-		</constant>
-		<constant name="KEY_ONEHALF" value="189" enum="Key">
-			½ key.
-		</constant>
-		<constant name="KEY_THREEQUARTERS" value="190" enum="Key">
-			¾ key.
-		</constant>
-		<constant name="KEY_QUESTIONDOWN" value="191" enum="Key">
-			¿ key.
-		</constant>
-		<constant name="KEY_AGRAVE" value="192" enum="Key">
-			À key.
-		</constant>
-		<constant name="KEY_AACUTE" value="193" enum="Key">
-			Á key.
-		</constant>
-		<constant name="KEY_ACIRCUMFLEX" value="194" enum="Key">
-			Â key.
-		</constant>
-		<constant name="KEY_ATILDE" value="195" enum="Key">
-			Ã key.
-		</constant>
-		<constant name="KEY_ADIAERESIS" value="196" enum="Key">
-			Ä key.
-		</constant>
-		<constant name="KEY_ARING" value="197" enum="Key">
-			Å key.
-		</constant>
-		<constant name="KEY_AE" value="198" enum="Key">
-			Æ key.
-		</constant>
-		<constant name="KEY_CCEDILLA" value="199" enum="Key">
-			Ç key.
-		</constant>
-		<constant name="KEY_EGRAVE" value="200" enum="Key">
-			È key.
-		</constant>
-		<constant name="KEY_EACUTE" value="201" enum="Key">
-			É key.
-		</constant>
-		<constant name="KEY_ECIRCUMFLEX" value="202" enum="Key">
-			Ê key.
-		</constant>
-		<constant name="KEY_EDIAERESIS" value="203" enum="Key">
-			Ë key.
-		</constant>
-		<constant name="KEY_IGRAVE" value="204" enum="Key">
-			Ì key.
-		</constant>
-		<constant name="KEY_IACUTE" value="205" enum="Key">
-			Í key.
-		</constant>
-		<constant name="KEY_ICIRCUMFLEX" value="206" enum="Key">
-			Î key.
-		</constant>
-		<constant name="KEY_IDIAERESIS" value="207" enum="Key">
-			Ï key.
-		</constant>
-		<constant name="KEY_ETH" value="208" enum="Key">
-			Ð key.
-		</constant>
-		<constant name="KEY_NTILDE" value="209" enum="Key">
-			Ñ key.
-		</constant>
-		<constant name="KEY_OGRAVE" value="210" enum="Key">
-			Ò key.
-		</constant>
-		<constant name="KEY_OACUTE" value="211" enum="Key">
-			Ó key.
-		</constant>
-		<constant name="KEY_OCIRCUMFLEX" value="212" enum="Key">
-			Ô key.
-		</constant>
-		<constant name="KEY_OTILDE" value="213" enum="Key">
-			Õ key.
-		</constant>
-		<constant name="KEY_ODIAERESIS" value="214" enum="Key">
-			Ö key.
-		</constant>
-		<constant name="KEY_MULTIPLY" value="215" enum="Key">
-			× key.
-		</constant>
-		<constant name="KEY_OOBLIQUE" value="216" enum="Key">
-			Ø key.
-		</constant>
-		<constant name="KEY_UGRAVE" value="217" enum="Key">
-			Ù key.
-		</constant>
-		<constant name="KEY_UACUTE" value="218" enum="Key">
-			Ú key.
-		</constant>
-		<constant name="KEY_UCIRCUMFLEX" value="219" enum="Key">
-			Û key.
-		</constant>
-		<constant name="KEY_UDIAERESIS" value="220" enum="Key">
-			Ü key.
-		</constant>
-		<constant name="KEY_YACUTE" value="221" enum="Key">
-			Ý key.
-		</constant>
-		<constant name="KEY_THORN" value="222" enum="Key">
-			Þ key.
+		<constant name="KEY_GLOBE" value="4194416" enum="Key">
+			"Globe" key on Mac / iPad keyboard.
 		</constant>
-		<constant name="KEY_SSHARP" value="223" enum="Key">
-			ß key.
+		<constant name="KEY_KEYBOARD" value="4194417" enum="Key">
+			"On-screen keyboard" key iPad keyboard.
 		</constant>
-		<constant name="KEY_DIVISION" value="247" enum="Key">
-			÷ key.
+		<constant name="KEY_JIS_EISU" value="4194418" enum="Key">
+			英数 key on Mac keyboard.
 		</constant>
-		<constant name="KEY_YDIAERESIS" value="255" enum="Key">
-			ÿ key.
+		<constant name="KEY_JIS_KANA" value="4194419" enum="Key">
+			かな key on Mac keyboard.
 		</constant>
 		<constant name="KEY_CODE_MASK" value="8388607" enum="KeyModifierMask" is_bitfield="true">
 			Key Code mask.
diff --git a/doc/classes/Input.xml b/doc/classes/Input.xml
index 6ecf903fde..3b0cfb3825 100644
--- a/doc/classes/Input.xml
+++ b/doc/classes/Input.xml
@@ -224,11 +224,18 @@
 				Returns [code]true[/code] if the system knows the specified device. This means that it sets all button and axis indices. Unknown joypads are not expected to match these constants, but you can still retrieve events from them.
 			</description>
 		</method>
+		<method name="is_key_label_pressed" qualifiers="const">
+			<return type="bool" />
+			<param index="0" name="keycode" type="int" enum="Key" />
+			<description>
+				Returns [code]true[/code] if you are pressing the key with the [param keycode] printed on it. You can pass a [enum Key] constant or any Unicode character code.
+			</description>
+		</method>
 		<method name="is_key_pressed" qualifiers="const">
 			<return type="bool" />
 			<param index="0" name="keycode" type="int" enum="Key" />
 			<description>
-				Returns [code]true[/code] if you are pressing the key in the current keyboard layout. You can pass a [enum Key] constant.
+				Returns [code]true[/code] if you are pressing the Latin key in the current keyboard layout. You can pass a [enum Key] constant.
 				[method is_key_pressed] is only recommended over [method is_physical_key_pressed] in non-game applications. This ensures that shortcut keys behave as expected depending on the user's keyboard layout, as keyboard shortcuts are generally dependent on the keyboard layout in non-game applications. If in doubt, use [method is_physical_key_pressed].
 				[b]Note:[/b] Due to keyboard ghosting, [method is_key_pressed] may return [code]false[/code] even if one of the action's keys is pressed. See [url=$DOCS_URL/tutorials/inputs/input_examples.html#keyboard-events]Input examples[/url] in the documentation for more information.
 			</description>
diff --git a/doc/classes/InputEventKey.xml b/doc/classes/InputEventKey.xml
index c3d682de9e..4d10a183d4 100644
--- a/doc/classes/InputEventKey.xml
+++ b/doc/classes/InputEventKey.xml
@@ -5,15 +5,42 @@
 	</brief_description>
 	<description>
 		Stores key presses on the keyboard. Supports key presses, key releases and [member echo] events.
+		[b]Note:[/b] Events received from the keyboard usually have all properties set. Event mappings should have only one of the [member keycode], [member physical_keycode] or [member unicode] set.
+		When events are compared, properties are checked in the following priority - [member keycode], [member physical_keycode] and [member unicode], events with the first matching value will be considered equal.
 	</description>
 	<tutorials>
 		<link title="InputEvent">$DOCS_URL/tutorials/inputs/inputevent.html</link>
 	</tutorials>
 	<methods>
+		<method name="as_text_key_label" qualifiers="const">
+			<return type="String" />
+			<description>
+				Returns a [String] representation of the event's [member key_label] and modifiers.
+			</description>
+		</method>
+		<method name="as_text_keycode" qualifiers="const">
+			<return type="String" />
+			<description>
+				Returns a [String] representation of the event's [member keycode] and modifiers.
+			</description>
+		</method>
+		<method name="as_text_physical_keycode" qualifiers="const">
+			<return type="String" />
+			<description>
+				Returns a [String] representation of the event's [member physical_keycode] and modifiers.
+			</description>
+		</method>
+		<method name="get_key_label_with_modifiers" qualifiers="const">
+			<return type="int" enum="Key" />
+			<description>
+				Returns the localized key label combined with modifier keys such as [kbd]Shift[/kbd] or [kbd]Alt[/kbd]. See also [InputEventWithModifiers].
+				To get a human-readable representation of the [InputEventKey] with modifiers, use [code]OS.get_keycode_string(event.get_key_label_with_modifiers())[/code] where [code]event[/code] is the [InputEventKey].
+			</description>
+		</method>
 		<method name="get_keycode_with_modifiers" qualifiers="const">
 			<return type="int" enum="Key" />
 			<description>
-				Returns the keycode combined with modifier keys such as [kbd]Shift[/kbd] or [kbd]Alt[/kbd]. See also [InputEventWithModifiers].
+				Returns the Latin keycode combined with modifier keys such as [kbd]Shift[/kbd] or [kbd]Alt[/kbd]. See also [InputEventWithModifiers].
 				To get a human-readable representation of the [InputEventKey] with modifiers, use [code]OS.get_keycode_string(event.get_keycode_with_modifiers())[/code] where [code]event[/code] is the [InputEventKey].
 			</description>
 		</method>
@@ -29,19 +56,36 @@
 		<member name="echo" type="bool" setter="set_echo" getter="is_echo" default="false">
 			If [code]true[/code], the key was already pressed before this event. It means the user is holding the key down.
 		</member>
+		<member name="key_label" type="int" setter="set_key_label" getter="get_key_label" enum="Key" default="0">
+			Represents the localized label printed on the key in the current keyboard layout, which corresponds to one of the [enum Key] constants or any valid Unicode character.
+			For keyboard layouts with a single label on the key, it is equivalent to [member keycode].
+			To get a human-readable representation of the [InputEventKey], use [code]OS.get_keycode_string(event.key_label)[/code] where [code]event[/code] is the [InputEventKey].
+			[codeblock]
+			    +-----+ +-----+
+			    | Q   | | Q   | - "Q" - keycode
+			    |   Й | |  ض | - "Й" and "ض" - key_label
+			    +-----+ +-----+
+			[/codeblock]
+		</member>
 		<member name="keycode" type="int" setter="set_keycode" getter="get_keycode" enum="Key" default="0">
-			The key keycode, which corresponds to one of the [enum Key] constants. Represent key in the current keyboard layout.
+			Latin label printed on the key in the current keyboard layout, which corresponds to one of the [enum Key] constants.
 			To get a human-readable representation of the [InputEventKey], use [code]OS.get_keycode_string(event.keycode)[/code] where [code]event[/code] is the [InputEventKey].
+			[codeblock]
+			    +-----+ +-----+
+			    | Q   | | Q   | - "Q" - keycode
+			    |   Й | |  ض | - "Й" and "ض" - key_label
+			    +-----+ +-----+
+			[/codeblock]
 		</member>
 		<member name="physical_keycode" type="int" setter="set_physical_keycode" getter="get_physical_keycode" enum="Key" default="0">
-			Key physical keycode, which corresponds to one of the [enum Key] constants. Represent the physical location of a key on the 101/102-key US QWERTY keyboard.
+			Represents the physical location of a key on the 101/102-key US QWERTY keyboard, which corresponds to one of the [enum Key] constants.
 			To get a human-readable representation of the [InputEventKey], use [code]OS.get_keycode_string(event.keycode)[/code] where [code]event[/code] is the [InputEventKey].
 		</member>
 		<member name="pressed" type="bool" setter="set_pressed" getter="is_pressed" default="false">
 			If [code]true[/code], the key's state is pressed. If [code]false[/code], the key's state is released.
 		</member>
 		<member name="unicode" type="int" setter="set_unicode" getter="get_unicode" default="0">
-			The key Unicode identifier (when relevant). Unicode identifiers for the composite characters and complex scripts may not be available unless IME input mode is active. See [method Window.set_ime_active] for more information.
+			The key Unicode character code (when relevant), shifted by modifier keys. Unicode character codes for composite characters and complex scripts may not be available unless IME input mode is active. See [method Window.set_ime_active] for more information.
 		</member>
 	</members>
 </class>
diff --git a/doc/classes/InputEventWithModifiers.xml b/doc/classes/InputEventWithModifiers.xml
index c6311d780c..26b88e6ff2 100644
--- a/doc/classes/InputEventWithModifiers.xml
+++ b/doc/classes/InputEventWithModifiers.xml
@@ -10,6 +10,12 @@
 		<link title="InputEvent">$DOCS_URL/tutorials/inputs/inputevent.html</link>
 	</tutorials>
 	<methods>
+		<method name="get_modifiers_mask" qualifiers="const">
+			<return type="int" enum="KeyModifierMask" />
+			<description>
+				Returns the keycode combination of modifier keys.
+			</description>
+		</method>
 		<method name="is_command_or_control_pressed" qualifiers="const">
 			<return type="bool" />
 			<description>