Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add more detailed documentation to InputDevice#getKeyCodeForKeyLocation().

Browse Source 
Bug: 216640180
Bug: 179812917
Test: javadocs only
Change-Id: I7ebbd3ab2829667849576bf11a48689bb2714a2d
This commit is contained in:
Philip Junker
2022-02-18 15:57:38 +01:00
parent 7621e718d1
commit 810e58044d
2 changed files with 57 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
core/java/android/hardware/input/InputManager.java
View File

@@ -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.
* Gets the {@link android.view.KeyEvent key code} produced by the given location on a reference
* QWERTY keyboard layout.
* <p>
* This API is useful for querying the physical location of keys that change the character
* produced based on the current locale and keyboard layout.
* <p>
* @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
* <a href="https://www.w3.org/TR/2017/CR-uievents-code-20170601/#key-alphanumeric-writing-system">
* hypothetical keyboard</a> 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.
*
* @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.
* @hide
*/
public int getKeyCodeForKeyLocation(int deviceId, int locationKeyCode) {

48
core/java/android/view/InputDevice.java
View File

@@ -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.
* Gets the {@link android.view.KeyEvent key code} produced by the given location on a reference
* QWERTY keyboard layout.
* <p>
* This API is useful for querying the physical location of keys that change the character
* produced based on the current locale and keyboard layout.
* <p>
* The following table provides a non-exhaustive list of examples:
* <table border="2" width="85%" align="center" cellpadding="5">
* <thead>
* <tr><th>Active Keyboard Layout</th> <th>Input Parameter</th>
* <th>Return Value</th></tr>
* </thead>
*
* @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.
* <tbody>
* <tr>
* <td>French AZERTY</td>
* <td><code>{@link KeyEvent#KEYCODE_Q}</code></td>
* <td><code>{@link KeyEvent#KEYCODE_A}</code></td>
* </tr>
* <tr>
* <td>German QWERTZ</td>
* <td><code>{@link KeyEvent#KEYCODE_Y}</code></td>
* <td><code>{@link KeyEvent#KEYCODE_Z}</code></td>
* </tr>
* <tr>
* <td>US QWERTY</td>
* <td><code>{@link KeyEvent#KEYCODE_B}</code></td>
* <td><code>{@link KeyEvent#KEYCODE_B}</code></td>
* </tr>
* </tbody>
* </table>
*
* @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
* <a href="https://www.w3.org/TR/2017/CR-uievents-code-20170601/#key-alphanumeric-writing-system">
* hypothetical keyboard</a> 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);