Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 810e5804 authored by Philip Junker's avatar Philip Junker
Browse files

Add more detailed documentation to InputDevice#getKeyCodeForKeyLocation(). 

Bug: 216640180
Bug: 179812917
Test: javadocs only
Change-Id: I7ebbd3ab2829667849576bf11a48689bb2714a2d
parent 7621e718

core/java/android/hardware/input/InputManager.java

+18 −10
Original line number Diff line number Diff line
@@ -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.

     * <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.

     *

     * @hide

     */

    public int getKeyCodeForKeyLocation(int deviceId, int locationKeyCode) {

core/java/android/view/InputDevice.java

+41 −9
Original line number Diff line number Diff line
@@ -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.

     * <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>

     *

     *     <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);