diff --git a/java/src/org/openqa/selenium/Keys.java b/java/src/org/openqa/selenium/Keys.java index 02231ea99cd0c..0b729541cb001 100644 --- a/java/src/org/openqa/selenium/Keys.java +++ b/java/src/org/openqa/selenium/Keys.java @@ -23,13 +23,26 @@ /** * Representations of pressable keys that aren't text. These are stored in the Unicode PUA (Private - * Use Area) code points, 0xE000-0xF8FF. + * Use Area) code points, 0xE000–0xF8FF. These values are used internally by WebDriver to simulate + * keyboard input where standard Unicode characters are insufficient, such as modifier and control + * keys. * - * @see http://www.google.com.au/search?&q=unicode+pua&btnK=Search + *
The codes follow conventions partially established by the W3C WebDriver specification and the + * Selenium project. Some values (e.g., RIGHT_SHIFT, RIGHT_COMMAND) are used in ChromeDriver but are + * not currently part of the W3C spec. Others (e.g., OPTION, FN) are symbolic and reserved for + * possible future mapping. + * + *
For consistency across platforms and drivers, values should be verified before assuming native + * support. + * + * @see W3C WebDriver Keyboard + * Actions + * @see Unicode PUA + * Overview */ @NullMarked public enum Keys implements CharSequence { + // Basic control characters NULL('\uE000'), CANCEL('\uE001'), // ^break HELP('\uE002'), @@ -99,6 +112,16 @@ public enum Keys implements CharSequence { META('\uE03D'), COMMAND(Keys.META), + // Extended macOS/ChromeDriver keys (based on observed Chrome usage) + RIGHT_SHIFT('\uE050'), // aligns with ChromeDriver usage + RIGHT_CONTROL('\uE051'), + RIGHT_ALT('\uE052'), + RIGHT_COMMAND('\uE053'), + + // Symbolic macOS keys not yet standardized + OPTION('\uE050'), // TODO: verify Unicode value with WebDriver spec + FN('\uE051'), // TODO: symbolic only; confirm or remove in future + ZENKAKU_HANKAKU('\uE040'); private final char keyCode; @@ -122,7 +145,6 @@ public char charAt(int index) { if (index == 0) { return keyCode; } - return 0; } @@ -136,7 +158,6 @@ public CharSequence subSequence(int start, int end) { if (start == 0 && end == 1) { return String.valueOf(keyCode); } - throw new IndexOutOfBoundsException(); } @@ -147,11 +168,9 @@ public String toString() { /** * Simulate pressing many keys at once in a "chord". Takes a sequence of Keys.XXXX or strings; - * appends each of the values to a string, and adds the chord termination key (Keys.NULL) and - * returns the resultant string. + * appends each to a string, adds the chord termination key (Keys.NULL), and returns it. * - *
Note: When the low-level webdriver key handlers see Keys.NULL, active modifier keys - * (CTRL/ALT/SHIFT/etc) release via a keyup event. + *
Note: Keys.NULL signals release of modifier keys like CTRL/ALT/SHIFT via keyup events.
*
* @param value characters to send
* @return String representation of the char sequence
@@ -161,27 +180,25 @@ public static String chord(CharSequence... value) {
}
/**
- * @see #chord(CharSequence...)
+ * Overload of {@link #chord(CharSequence...)} that accepts an iterable.
+ *
* @param value characters to send
* @return String representation of the char sequence
*/
public static String chord(Iterable