From 810e58044d8b076009a8bcc1eade635d7e0e719d Mon Sep 17 00:00:00 2001 From: Philip Junker Date: Fri, 18 Feb 2022 15:57:38 +0100 Subject: Add more detailed documentation to InputDevice#getKeyCodeForKeyLocation(). Bug: 216640180 Bug: 179812917 Test: javadocs only Change-Id: I7ebbd3ab2829667849576bf11a48689bb2714a2d --- core/java/android/hardware/input/InputManager.java | 28 +++++++----- core/java/android/view/InputDevice.java | 50 ++++++++++++++++++---- 2 files changed, 59 insertions(+), 19 deletions(-) diff --git a/core/java/android/hardware/input/InputManager.java b/core/java/android/hardware/input/InputManager.java index 2fd79cf980c7..c38a847dfb9f 100644 --- a/core/java/android/hardware/input/InputManager.java +++ b/core/java/android/hardware/input/InputManager.java @@ -1079,16 +1079,24 @@ public final class InputManager { } /** - * Gets the key code produced by the specified location on a US keyboard layout. - * Key code as defined in {@link android.view.KeyEvent}. - * This API is only functional for devices with {@link InputDevice#SOURCE_KEYBOARD} available - * which can alter their key mapping using country specific keyboard layouts. - * - * @param deviceId The input device id. - * @param locationKeyCode The location of a key on a US keyboard layout. - * @return The key code produced when pressing the key at the specified location, given the - * active keyboard layout. Returns {@link KeyEvent#KEYCODE_UNKNOWN} if the requested - * mapping could not be determined, or if an error occurred. + * Gets the {@link android.view.KeyEvent key code} produced by the given location on a reference + * QWERTY keyboard layout. + *

+ * This API is useful for querying the physical location of keys that change the character + * produced based on the current locale and keyboard layout. + *

+ * @see InputDevice#getKeyCodeForKeyLocation(int) for examples. + * + * @param locationKeyCode The location of a key specified as a key code on the QWERTY layout. + * This provides a consistent way of referring to the physical location of a key independently + * of the current keyboard layout. Also see the + * + * hypothetical keyboard provided by the W3C, which may be helpful for identifying the + * physical location of a key. + * @return The key code produced by the key at the specified location, given the current + * keyboard layout. Returns {@link KeyEvent#KEYCODE_UNKNOWN} if the device does not specify + * {@link InputDevice#SOURCE_KEYBOARD} or the requested mapping cannot be determined. + * * @hide */ public int getKeyCodeForKeyLocation(int deviceId, int locationKeyCode) { diff --git a/core/java/android/view/InputDevice.java b/core/java/android/view/InputDevice.java index 188d7459f9a7..7d5603994efa 100644 --- a/core/java/android/view/InputDevice.java +++ b/core/java/android/view/InputDevice.java @@ -737,15 +737,47 @@ public final class InputDevice implements Parcelable { } /** - * Gets the key code produced by the specified location on a US keyboard layout. - * Key code as defined in {@link android.view.KeyEvent}. - * This API is only functional for devices with {@link InputDevice#SOURCE_KEYBOARD} available - * which can alter their key mapping using country specific keyboard layouts. - * - * @param locationKeyCode The location of a key on a US keyboard layout. - * @return The key code produced when pressing the key at the specified location, given the - * active keyboard layout. Returns {@link KeyEvent#KEYCODE_UNKNOWN} if the requested - * mapping could not be determined, or if an error occurred. + * Gets the {@link android.view.KeyEvent key code} produced by the given location on a reference + * QWERTY keyboard layout. + *

+ * This API is useful for querying the physical location of keys that change the character + * produced based on the current locale and keyboard layout. + *

+ * The following table provides a non-exhaustive list of examples: + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Active Keyboard Layout Input ParameterReturn Value
French AZERTY{@link KeyEvent#KEYCODE_Q}{@link KeyEvent#KEYCODE_A}
German QWERTZ{@link KeyEvent#KEYCODE_Y}{@link KeyEvent#KEYCODE_Z}
US QWERTY{@link KeyEvent#KEYCODE_B}{@link KeyEvent#KEYCODE_B}
+ * + * @param locationKeyCode The location of a key specified as a key code on the QWERTY layout. + * This provides a consistent way of referring to the physical location of a key independently + * of the current keyboard layout. Also see the + * + * hypothetical keyboard provided by the W3C, which may be helpful for identifying the + * physical location of a key. + * @return The key code produced by the key at the specified location, given the current + * keyboard layout. Returns {@link KeyEvent#KEYCODE_UNKNOWN} if the device does not specify + * {@link InputDevice#SOURCE_KEYBOARD} or the requested mapping cannot be determined. */ public int getKeyCodeForKeyLocation(int locationKeyCode) { return InputManager.getInstance().getKeyCodeForKeyLocation(mId, locationKeyCode); -- cgit v1.2.3-59-g8ed1b