From daad4aed62bfa471421f960179f0ac0fd78e8040 Mon Sep 17 00:00:00 2001 From: bruvzg <7645683+bruvzg@users.noreply.github.com> Date: Sun, 11 Dec 2022 01:21:22 +0200 Subject: Cleanup and unify keyboard input. - Unify keycode values (secondary label printed on a key), remove unused hardcoded Latin-1 codes. - Unify IME behaviour, add inline composition string display on Windows and X11. - Add key_label (localized label printed on a key) value to the key events, and allow mapping actions to the unshifted Unicode events. - Add support for physical keyboard (Bluetooth or Sidecar) handling on iOS. - Add support for media key handling on macOS. Co-authored-by: Raul Santos --- doc/classes/@GlobalScope.xml | 232 ++------------------------------ doc/classes/Input.xml | 9 +- doc/classes/InputEventKey.xml | 52 ++++++- doc/classes/InputEventWithModifiers.xml | 6 + 4 files changed, 73 insertions(+), 226 deletions(-) (limited to 'doc/classes') 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 @@ Number 9 on the numeric keypad. - - Left Super key (Windows key). - - - Right Super key (Windows key). - Context menu key. - - Left Hyper key. - - - Right Hyper key. + + Hyper key. (On Linux/X11 only). Help key. - - Left Direction key. - - - Right Direction key. - Media back key. Not to be confused with the Back button on an Android device. @@ -1812,21 +1797,6 @@ Volume up key. - - Bass Boost key. - - - Bass up key. - - - Bass down key. - - - Treble up key. - - - Treble down key. - Media play key. @@ -1911,7 +1881,7 @@ Launch Shortcut F key. - + Unknown key. @@ -2121,203 +2091,23 @@ ~ key. - - Non-breakable space key. - - - ¡ key. - - - ¢ key. - - - £ key. - - - ¤ key. - ¥ key. - - ¦ key. - § key. - - ¨ key. - - - © key. - - - ª key. - - - « key. - - - ¬ key. - - - Soft hyphen key. - - - ® key. - - - ¯ key. - - - ° key. - - - ± key. - - - ² key. - - - ³ key. - - - ´ key. - - - µ key. - - - ¶ key. - - - · key. - - - ¸ key. - - - ¹ key. - - - º key. - - - » key. - - - ¼ key. - - - ½ key. - - - ¾ key. - - - ¿ key. - - - À key. - - - Á key. - - - Â key. - - - Ã key. - - - Ä key. - - - Å key. - - - Æ key. - - - Ç key. - - - È key. - - - É key. - - - Ê key. - - - Ë key. - - - Ì key. - - - Í key. - - - Î key. - - - Ï key. - - - Ð key. - - - Ñ key. - - - Ò key. - - - Ó key. - - - Ô key. - - - Õ key. - - - Ö key. - - - × key. - - - Ø key. - - - Ù key. - - - Ú key. - - - Û key. - - - Ü key. - - - Ý key. - - - Þ key. + + "Globe" key on Mac / iPad keyboard. - - ß key. + + "On-screen keyboard" key iPad keyboard. - - ÷ key. + + 英数 key on Mac keyboard. - - ÿ key. + + かな key on Mac keyboard. 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. + + + + + 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. + + - 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. 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 @@ 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. $DOCS_URL/tutorials/inputs/inputevent.html + + + + Returns a [String] representation of the event's [member key_label] and modifiers. + + + + + + Returns a [String] representation of the event's [member keycode] and modifiers. + + + + + + Returns a [String] representation of the event's [member physical_keycode] and modifiers. + + + + + + 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]. + + - 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]. @@ -29,19 +56,36 @@ If [code]true[/code], the key was already pressed before this event. It means the user is holding the key down. + + 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] + - 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] - 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]. If [code]true[/code], the key's state is pressed. If [code]false[/code], the key's state is released. - 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. 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 @@ $DOCS_URL/tutorials/inputs/inputevent.html + + + + Returns the keycode combination of modifier keys. + + -- cgit v1.2.3