Module org.htmlunit

Class Keyboard

java.lang.Object
org.htmlunit.html.Keyboard

public class Keyboard extends Object
Represents a sequence of keyboard actions—such as typed characters, key presses, and key releases—used to simulate realistic user input on HTML elements.

A Keyboard instance acts as a keystroke recorder that queues key actions and maintains modifier state (SHIFT, CONTROL, ALT, META) across sequential events. When executed against an element via element.type(keyboard), it drives the full browser event lifecycle (keydown, keypress, input, and keyup) and mutates DOM text values accordingly.

Core Features

  • Character and Key Code Queuing: Supports typing printable characters as well as holding and releasing raw key codes (e.g., navigation, BACK_SPACE, or modifier keys).
  • Modifier State Persistence: Tracks modifier keys so subsequent keystrokes inherit the active modifier flags during JavaScript event dispatching.
  • Caret Positioning: Supports configured cursor placement (isStartAtEnd()) to position the selection caret at the end of input fields before typing begins.
Author:
Ahmed Ashour, Ronald Brill
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final record 
    Only the key down or only the key up of a character, e.g. via keyDown(char) or keyUp(char).
    static interface 
    Represents a single keyboard input action.
    static final record 
    A key-code press or release, e.g. via press(int) or release(int).
    static final record 
    Only the key down or only the key up of a key code, e.g. via keyDown(int) or keyUp(int, int).
    static final record 
    A character typed directly, e.g. via type(char).
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    Use the default location of the key code (e.g. the left one for the shift key).
  • Constructor Summary

    Constructors
    Constructor
    Description
    Creates a new instance.
    Keyboard(boolean startAtEnd)
    Creates a new instance, specifying whether typing should start at the text end or not.
  • Method Summary

    Modifier and Type
    Method
    Description
    void
    Clears all keys.
    boolean
    Returns whether typing should start at the text end or not.
    void
    keyDown(char ch)
    Presses only the key of the specified character; the key stays pressed until keyUp(char) is called for the same character.
    void
    keyDown(int keyCode)
    Presses only the specified key code; the key stays pressed until keyUp(int) is called for the same key code (in contrast to press(int) no keyup is fired for keys that are not modifiers).
    void
    keyDown(int keyCode, int location)
    Presses only the specified key code at the specified location; the key stays pressed until keyUp(int, int) is called for the same key.
    void
    keyUp(char ch)
    Releases the key of the specified character pressed by keyDown(char); only the keyup event is fired.
    void
    keyUp(int keyCode)
    Releases the specified key code pressed by keyDown(int); only the keyup event is fired.
    void
    keyUp(int keyCode, int location)
    Releases the specified key code at the specified location pressed by keyDown(int, int); only the keyup event is fired.
    void
    press(int keyCode)
    Press the specified key code (without releasing it).
    void
    release(int keyCode)
    Releases the specified key code.
    void
    setPressedModifiers(boolean shift, boolean ctrl, boolean alt, boolean meta)
    Sets the state of the modifier keys that are already pressed when this keyboard is typed (e.g. pressed by a previous keyboard); no events are fired for these keys.
    void
    type(char ch)
    Types the specified character.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • DEFAULT_LOCATION

      public static final int DEFAULT_LOCATION
      Use the default location of the key code (e.g. the left one for the shift key).
      See Also:
  • Constructor Details

    • Keyboard

      public Keyboard()
      Creates a new instance.
    • Keyboard

      public Keyboard(boolean startAtEnd)
      Creates a new instance, specifying whether typing should start at the text end or not.
      Parameters:
      startAtEnd - whether typing should start at the text end or not
  • Method Details

    • type

      public void type(char ch)
      Types the specified character.
      Parameters:
      ch - the character
    • press

      public void press(int keyCode)
      Press the specified key code (without releasing it).

      An example of predefined values is KeyboardEvent.DOM_VK_PAGE_DOWN.

      Parameters:
      keyCode - the key code
    • release

      public void release(int keyCode)
      Releases the specified key code.

      An example of predefined values is KeyboardEvent.DOM_VK_PAGE_DOWN.

      Parameters:
      keyCode - the key code.
    • keyDown

      public void keyDown(char ch)
      Presses only the key of the specified character; the key stays pressed until keyUp(char) is called for the same character. Like in the browsers, the keydown and keypress events are fired and the character is typed.
      Parameters:
      ch - the character
    • keyUp

      public void keyUp(char ch)
      Releases the key of the specified character pressed by keyDown(char); only the keyup event is fired.
      Parameters:
      ch - the character
    • keyDown

      public void keyDown(int keyCode)
      Presses only the specified key code; the key stays pressed until keyUp(int) is called for the same key code (in contrast to press(int) no keyup is fired for keys that are not modifiers).
      Parameters:
      keyCode - the key code (e.g. KeyboardEvent.DOM_VK_LEFT)
    • keyDown

      public void keyDown(int keyCode, int location)
      Presses only the specified key code at the specified location; the key stays pressed until keyUp(int, int) is called for the same key.
      Parameters:
      keyCode - the key code (e.g. KeyboardEvent.DOM_VK_SHIFT)
      location - the location of the key (e.g. KeyboardEvent.DOM_KEY_LOCATION_RIGHT for the right shift key) or DEFAULT_LOCATION
    • keyUp

      public void keyUp(int keyCode)
      Releases the specified key code pressed by keyDown(int); only the keyup event is fired.
      Parameters:
      keyCode - the key code (e.g. KeyboardEvent.DOM_VK_LEFT)
    • keyUp

      public void keyUp(int keyCode, int location)
      Releases the specified key code at the specified location pressed by keyDown(int, int); only the keyup event is fired.
      Parameters:
      keyCode - the key code (e.g. KeyboardEvent.DOM_VK_SHIFT)
      location - the location of the key (e.g. KeyboardEvent.DOM_KEY_LOCATION_RIGHT for the right shift key) or DEFAULT_LOCATION
    • setPressedModifiers

      public void setPressedModifiers(boolean shift, boolean ctrl, boolean alt, boolean meta)
      Sets the state of the modifier keys that are already pressed when this keyboard is typed (e.g. pressed by a previous keyboard); no events are fired for these keys.
      Parameters:
      shift - whether the shift key is pressed
      ctrl - whether the control key is pressed
      alt - whether the alt key is pressed
      meta - whether the meta key is pressed
    • clear

      public void clear()
      Clears all keys.
    • isStartAtEnd

      public boolean isStartAtEnd()
      Returns whether typing should start at the text end or not.
      Returns:
      whether typing should start at the text end or not