Class Robot

java.lang.Object

java.awt.Robot

public class Robot extends Object

This class is used to generate native system input events for the purposes of test automation, self-running demos, and other applications where control of the mouse and keyboard is needed. The primary purpose of Robot is to facilitate automated testing of Java platform implementations.

Using the class to generate input events differs from posting events to the AWT event queue or AWT components in that the events are generated in the platform's native input queue. For example, Robot.mouseMove will actually move the mouse cursor instead of just generating mouse move events.

API Note:

When autoWaitForIdle() is enabled, mouse and key related methods cannot be called on the AWT EDT. This is because when autoWaitForIdle() is enabled, the mouse and key methods implicitly call waitForIdle() which will throw IllegalThreadStateException when called on the AWT EDT. In addition, screen capture operations can be lengthy and delay(long ms) clearly inserts a delay, so these also should not be called on the EDT. Taken together, this means that as much as possible, methods on this class should not be called on the EDT.

Note that some platforms require special privileges or extensions to access low-level input control. If the current platform configuration does not allow input control, an AWTException will be thrown when trying to construct Robot objects. For example, X-Window systems will throw the exception if the XTEST 2.2 standard extension is not supported (or not enabled) by the X server.

Applications that use Robot for purposes other than self-testing should handle these error conditions gracefully.

Platforms and desktop environments may impose restrictions or limitations on the access required to implement all functionality in the Robot class. For example:

preventing access to the contents of any part of a desktop or Window on the desktop that is not owned by the running application.
treating window decorations as non-owned content.
ignoring or limiting specific requests to manipulate windows.
ignoring or limiting specific requests for Robot generated (synthesized) events related to keyboard and mouse etc.
requiring specific or global permissions to any access to window contents, even application owned content,or to perform even limited synthesizing of events.

The Robot API specification requires that approvals for these be granted for full operation. If they are not granted, the API will be degraded as discussed here. Relevant specific API methods may document more specific limitations and requirements. Depending on the policies of the desktop environment, the approvals mentioned above may:

be required every time
or persistent for the lifetime of an application,
or persistent across multiple user desktop sessions
be fine-grained permissions
be associated with a specific binary application, or a class of binary applications.

When such approvals need to given interactively, it may impede the normal operation of the application until approved, and if approval is denied or not possible, or cannot be made persistent then it will degrade the functionality of this class and in turn any part of the operation of the application which is dependent on it.

Since:

1.3

Field Summary

Modifier and Type	Field	Description
`static final int`	`DEFAULT_DELAY`	Default delay in milliseconds for mouse `glide`, `type`, and `click`.
`static final int`	`DEFAULT_STEP_LENGTH`	Default pixel step-length for mouse `glide`.

Constructor Summary

Constructor	Description
`Robot()`	Constructs a Robot object in the coordinate system of the primary screen.
`Robot(GraphicsDevice screen)`	Creates a Robot for the given screen device.

Method Summary

Modifier and Type	Method	Description
`void`	`click()`	A convenience method that clicks mouse button 1.
`void`	`click(int buttons)`	A convenience method that simulates clicking a mouse button by calling `mousePress`, `mouseRelease` and `waitForIdle`.
`MultiResolutionImage`	`createMultiResolutionScreenCapture(Rectangle screenRect)`	Creates an image containing pixels read from the screen.
`BufferedImage`	`createScreenCapture(Rectangle screenRect)`	Creates an image containing pixels read from the screen.
`void`	`delay(int ms)`	Sleeps for the specified time.
`int`	`getAutoDelay()`	Returns the number of milliseconds this Robot sleeps after generating an event.
`Color`	`getPixelColor(int x, int y)`	Returns the color of a pixel at the given screen coordinates.
`void`	`glide(int x, int y)`	A convenience method that moves the mouse in multiple steps from its current location to the destination coordinates.
`void`	`glide(int srcX, int srcY, int dstX, int dstY)`	A convenience method that moves the mouse in multiple steps from source coordinates to the destination coordinates.
`void`	`glide(int srcX, int srcY, int destX, int destY, int stepLength, int stepDelay)`	A convenience method that moves the mouse in multiple steps from source point to the destination point with a given `stepLength` and `stepDelay`.
`boolean`	`isAutoWaitForIdle()`	Returns whether this Robot automatically invokes `waitForIdle` after generating an event.
`void`	`keyPress(int keycode)`	Presses a given key.
`void`	`keyRelease(int keycode)`	Releases a given key.
`void`	`mouseMove(int x, int y)`	Moves mouse pointer to given screen coordinates.
`void`	`mousePress(int buttons)`	Presses one or more mouse buttons.
`void`	`mouseRelease(int buttons)`	Releases one or more mouse buttons.
`void`	`mouseWheel(int wheelAmt)`	Rotates the scroll wheel on wheel-equipped mice.
`void`	`setAutoDelay(int ms)`	Sets the number of milliseconds this Robot sleeps after generating an event.
`void`	`setAutoWaitForIdle(boolean isOn)`	Sets whether this Robot automatically invokes `waitForIdle` after generating an event.
`String`	`toString()`	Returns a string representation of this Robot.
`void`	`type(char c)`	A convenience method that simulates typing a char by calling `keyPress` and `keyRelease`.
`void`	`type(int keycode)`	A convenience method that simulates typing a key by calling `keyPress` and `keyRelease`.
`void`	`waitForIdle()`	Waits until all events currently on the event queue have been processed.
`void`	`waitForIdle(int delayValue)`	A convenience method that calls `waitForIdle` then waits an additional specified `delayValue` time in milliseconds.

Methods declared in class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Modifier and Type	Method	Description
`protected Object`	`clone()`	Creates and returns a copy of this object.
`boolean`	`equals(Object obj)`	Indicates whether some other object is "equal to" this one.
`protected void`	`finalize()`	Deprecated, for removal: This API element is subject to removal in a future version. Finalization is deprecated and subject to removal in a future release.
`final Class<?>`	`getClass()`	Returns the runtime class of this `Object`.
`int`	`hashCode()`	Returns a hash code value for this object.
`final void`	`notify()`	Wakes up a single thread that is waiting on this object's monitor.
`final void`	`notifyAll()`	Wakes up all threads that are waiting on this object's monitor.
`final void`	`wait()`	Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
`final void`	`wait(long timeoutMillis)`	Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait(long timeoutMillis, int nanos)`	Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

Field Details

DEFAULT_DELAY

public static final int DEFAULT_DELAY

Default delay in milliseconds for mouse glide, type, and click.

See Also:

DEFAULT_STEP_LENGTH

public static final int DEFAULT_STEP_LENGTH

Default pixel step-length for mouse glide.

See Also:

Constructor Details

Robot

public Robot() throws AWTException

Constructs a Robot object in the coordinate system of the primary screen.

Throws:

AWTException - if the platform configuration does not allow low-level input control. This exception is always thrown when GraphicsEnvironment.isHeadless() returns true

See Also:

Robot

public Robot(GraphicsDevice screen) throws AWTException

Creates a Robot for the given screen device. Coordinates passed to Robot method calls like mouseMove, getPixelColor and createScreenCapture will be interpreted as being in the same coordinate system as the specified screen. Note that depending on the platform configuration, multiple screens may either:

share the same coordinate system to form a combined virtual screen
use different coordinate systems to act as independent screens

If screen devices are reconfigured such that the coordinate system is affected, the behavior of existing Robot objects is undefined.

Parameters:

screen - A screen GraphicsDevice indicating the coordinate system the Robot will operate in.

Throws:

AWTException - if the platform configuration does not allow low-level input control. This exception is always thrown when GraphicsEnvironment.isHeadless() returns true.

IllegalArgumentException - if screen is not a screen GraphicsDevice.

See Also:

Method Details

mouseMove

public void mouseMove(int x, int y)

Moves mouse pointer to given screen coordinates.

The mouse pointer may not visually move on some platforms, while the subsequent mousePress and mouseRelease can be delivered to the correct location

Parameters:: x - X position; y - Y position
Throws:: IllegalThreadStateException - if called on the AWT event dispatching thread and isAutoWaitForIdle would return true

mousePress

public void mousePress(int buttons)

Presses one or more mouse buttons. The mouse buttons should be released using the mouseRelease(int) method.

Parameters:

buttons - the Button mask; a combination of one or more mouse button masks.

It is allowed to use only a combination of valid values as a buttons parameter. A valid combination consists of InputEvent.BUTTON1_DOWN_MASK, InputEvent.BUTTON2_DOWN_MASK, InputEvent.BUTTON3_DOWN_MASK and values returned by the InputEvent.getMaskForButton(button) method. The valid combination also depends on a Toolkit.areExtraMouseButtonsEnabled() value as follows:

If support for extended mouse buttons is disabled by Java then it is allowed to use only the following standard button masks: InputEvent.BUTTON1_DOWN_MASK, InputEvent.BUTTON2_DOWN_MASK, InputEvent.BUTTON3_DOWN_MASK.
If support for extended mouse buttons is enabled by Java then it is allowed to use the standard button masks and masks for existing extended mouse buttons, if the mouse has more then three buttons. In that way, it is allowed to use the button masks corresponding to the buttons in the range from 1 to MouseInfo.getNumberOfButtons().
It is recommended to use the InputEvent.getMaskForButton(button) method to obtain the mask for any mouse button by its number.

The following standard button masks are also accepted:

InputEvent.BUTTON1_MASK
InputEvent.BUTTON2_MASK
InputEvent.BUTTON3_MASK

However, it is recommended to use InputEvent.BUTTON1_DOWN_MASK, InputEvent.BUTTON2_DOWN_MASK, InputEvent.BUTTON3_DOWN_MASK instead. Either extended _DOWN_MASK or old _MASK values should be used, but both those models should not be mixed.

Throws:

IllegalArgumentException - if the buttons mask contains the mask for extra mouse button and support for extended mouse buttons is disabled by Java

IllegalArgumentException - if the buttons mask contains the mask for extra mouse button that does not exist on the mouse and support for extended mouse buttons is enabled by Java

IllegalThreadStateException - if called on the AWT event dispatching thread and isAutoWaitForIdle would return true

See Also:

mouseRelease

public void mouseRelease(int buttons)

Releases one or more mouse buttons.

Parameters:

buttons - the Button mask; a combination of one or more mouse button masks.

If the support for extended mouse buttons is disabled by Java then it is allowed to use only the following standard button masks: InputEvent.BUTTON1_DOWN_MASK, InputEvent.BUTTON2_DOWN_MASK, InputEvent.BUTTON3_DOWN_MASK.
If the support for extended mouse buttons is enabled by Java then it is allowed to use the standard button masks and masks for existing extended mouse buttons, if the mouse has more then three buttons. In that way, it is allowed to use the button masks corresponding to the buttons in the range from 1 to MouseInfo.getNumberOfButtons().
It is recommended to use the InputEvent.getMaskForButton(button) method to obtain the mask for any mouse button by its number.

The following standard button masks are also accepted:

InputEvent.BUTTON1_MASK
InputEvent.BUTTON2_MASK
InputEvent.BUTTON3_MASK

Throws:

IllegalArgumentException - if the buttons mask contains the mask for extra mouse button and support for extended mouse buttons is disabled by Java

IllegalArgumentException - if the buttons mask contains the mask for extra mouse button that does not exist on the mouse and support for extended mouse buttons is enabled by Java

IllegalThreadStateException - if called on the AWT event dispatching thread and isAutoWaitForIdle would return true

See Also:

mouseWheel

public void mouseWheel(int wheelAmt)

Rotates the scroll wheel on wheel-equipped mice.

Parameters:: wheelAmt - number of "notches" to move the mouse wheel Negative values indicate movement up/away from the user, positive values indicate movement down/towards the user.
Throws:: IllegalThreadStateException - if called on the AWT event dispatching thread and isAutoWaitForIdle would return true
Since:: 1.4

keyPress

public void keyPress(int keycode)

Presses a given key. The key should be released using the keyRelease method.

Key codes that have more than one physical key associated with them (e.g. KeyEvent.VK_SHIFT could mean either the left or right shift key) will map to the left key.

Parameters:

keycode - Key to press (e.g. KeyEvent.VK_A)

Throws:

IllegalArgumentException - if keycode is not a valid key

IllegalThreadStateException - if called on the AWT event dispatching thread and isAutoWaitForIdle would return true

See Also:

keyRelease

public void keyRelease(int keycode)

Releases a given key.

Key codes that have more than one physical key associated with them (e.g. KeyEvent.VK_SHIFT could mean either the left or right shift key) will map to the left key.

Parameters:

keycode - Key to release (e.g. KeyEvent.VK_A)

Throws:

IllegalArgumentException - if keycode is not a valid key

IllegalThreadStateException - if called on the AWT event dispatching thread and isAutoWaitForIdle would return true

See Also:

getPixelColor

public Color getPixelColor(int x, int y)

Returns the color of a pixel at the given screen coordinates.

If the desktop environment requires that permissions be granted to capture screen content, and the required permissions are not granted, then a SecurityException may be thrown, or the content of the returned Color is undefined.

API Note:: It is recommended to avoid calling this method on the AWT Event Dispatch Thread since screen capture may be a lengthy operation, particularly if acquiring permissions is needed and involves user interaction.
Parameters:: x - X position of pixel; y - Y position of pixel
Returns:: Color of the pixel
Throws:: SecurityException - if access to the screen is denied by the desktop environment

createScreenCapture

public BufferedImage createScreenCapture(Rectangle screenRect)

Creates an image containing pixels read from the screen.

API Note:: It is recommended to avoid calling this method on the AWT Event Dispatch Thread since screen capture may be a lengthy operation, particularly if acquiring permissions is needed and involves user interaction.
Parameters:: screenRect - Rect to capture in screen coordinates
Returns:: The captured image
Throws:: IllegalArgumentException - if screenRect width and height are not greater than zero; SecurityException - if access to the screen is denied by the desktop environment

createMultiResolutionScreenCapture

public MultiResolutionImage createMultiResolutionScreenCapture(Rectangle screenRect)

Creates an image containing pixels read from the screen. This method can be used in case there is a scaling transform from user space to screen (device) space. Typically this means that the display is a high resolution screen, although strictly it means any case in which there is such a transform. Returns a MultiResolutionImage.

For a non-scaled display, the MultiResolutionImage will have one image variant:

Base Image with user specified size.

For a high resolution display where there is a scaling transform, the MultiResolutionImage will have two image variants:

Base Image with user specified size. This is scaled from the screen.
Native device resolution image with device size pixels.

Example:

     Image nativeResImage;
     MultiResolutionImage mrImage = robot.createMultiResolutionScreenCapture(frame.getBounds());
     List<Image> resolutionVariants = mrImage.getResolutionVariants();
     if (resolutionVariants.size() > 1) {
         nativeResImage = resolutionVariants.get(1);
     } else {
         nativeResImage = resolutionVariants.get(0);
     }

API Note:: It is recommended to avoid calling this method on the AWT Event Dispatch Thread since screen capture may be a lengthy operation, particularly if acquiring permissions is needed and involves user interaction.
Parameters:: screenRect - Rect to capture in screen coordinates
Returns:: The captured image
Throws:: IllegalArgumentException - if screenRect width and height are not greater than zero; SecurityException - if access to the screen is denied by the desktop environment
Since:: 9

isAutoWaitForIdle

public boolean isAutoWaitForIdle()

Returns whether this Robot automatically invokes waitForIdle after generating an event.

Returns:: Whether waitForIdle is automatically called

setAutoWaitForIdle

public void setAutoWaitForIdle(boolean isOn)

Sets whether this Robot automatically invokes waitForIdle after generating an event.

API Note:: Setting this to true means you cannot call mouse and key-controlling events on the AWT Event Dispatching Thread
Parameters:: isOn - Whether waitForIdle is automatically invoked

getAutoDelay

public int getAutoDelay()

Returns the number of milliseconds this Robot sleeps after generating an event.

Returns:: the delay duration in milliseconds

setAutoDelay

public void setAutoDelay(int ms)

Sets the number of milliseconds this Robot sleeps after generating an event.

Parameters:: ms - the delay duration in milliseconds
Throws:: IllegalArgumentException - If ms is not between 0 and 60,000 milliseconds inclusive

delay

public void delay(int ms)

Sleeps for the specified time.

If the invoking thread is interrupted while waiting, then it will return immediately with the interrupted status set. If the interrupted status is already set, this method returns immediately with the interrupted status set.

API Note:: It is recommended to avoid calling this method on the AWT Event Dispatch Thread since delay may be a lengthy operation.
Parameters:: ms - time to sleep in milliseconds
Throws:: IllegalArgumentException - if ms is not between 0 and 60,000 milliseconds inclusive

waitForIdle

public void waitForIdle()

Waits until all events currently on the event queue have been processed.

Throws:: IllegalThreadStateException - if called on the AWT event dispatching thread

toString

public String toString()

Returns a string representation of this Robot.

Overrides:: toString in class Object
Returns:: the string representation.

click

public void click(int buttons)

A convenience method that simulates clicking a mouse button by calling mousePress, mouseRelease and waitForIdle. Invokes waitForIdle with a default delay of 20 milliseconds after mousePress and mouseRelease calls. For specifics on valid inputs see mousePress(int).

Parameters:

buttons - The button mask; a combination of one or more mouse button masks.

Throws:

IllegalArgumentException - if the buttons mask contains the mask for extra mouse button and support for extended mouse buttons is disabled by Java

IllegalArgumentException - if the buttons mask contains the mask for extra mouse button that does not exist on the mouse and support for extended mouse buttons is enabled by Java

IllegalThreadStateException - if called on the AWT event dispatching thread

Since:

See Also:

click

public void click()

A convenience method that clicks mouse button 1.

Throws:

IllegalThreadStateException - if called on the AWT event dispatching thread

Since:

See Also:

waitForIdle

public void waitForIdle(int delayValue)

A convenience method that calls waitForIdle then waits an additional specified delayValue time in milliseconds.

Parameters:: delayValue - Additional delay length in milliseconds to wait until thread sync been completed
Throws:: IllegalThreadStateException - if called on the AWT event dispatching thread; IllegalArgumentException - if delayValue is not between 0 and 60,000 milliseconds inclusive
Since:: 26

glide

public void glide(int x, int y)

A convenience method that moves the mouse in multiple steps from its current location to the destination coordinates.

Implementation Requirements:

Invokes mouseMove with a step-length of 2 and a step-delay of 20.

Parameters:

x - Destination point x coordinate

y - Destination point y coordinate

Throws:

IllegalThreadStateException - if called on the AWT event dispatching thread and isAutoWaitForIdle would return true

Since:

See Also:

glide

public void glide(int srcX, int srcY, int dstX, int dstY)

A convenience method that moves the mouse in multiple steps from source coordinates to the destination coordinates.

Implementation Requirements:

Invokes mouseMove with a step-length of 2 and a step-delay of 20.

Parameters:

srcX - Source point x coordinate

srcY - Source point y coordinate

dstX - Destination point x coordinate

dstY - Destination point y coordinate

Throws:

IllegalThreadStateException - if called on the AWT event dispatching thread and isAutoWaitForIdle would return true

Since:

See Also:

glide

public void glide(int srcX, int srcY, int destX, int destY, int stepLength, int stepDelay)

A convenience method that moves the mouse in multiple steps from source point to the destination point with a given stepLength and stepDelay.

Parameters:

srcX - Source point x coordinate

srcY - Source point y coordinate

destX - Destination point x coordinate

destY - Destination point y coordinate

stepLength - Preferred length of one step in pixels

stepDelay - Delay between steps in milliseconds

Throws:

IllegalArgumentException - if stepLength is not greater than zero

IllegalArgumentException - if stepDelay is not between 0 and 60,000 milliseconds inclusive

IllegalThreadStateException - if called on the AWT event dispatching thread and isAutoWaitForIdle would return true

Since:

See Also:

type

public void type(int keycode)

A convenience method that simulates typing a key by calling keyPress and keyRelease. Invokes waitForIdle with a delay of 20 milliseconds after keyPress and keyRelease calls.

Key codes that have more than one physical key associated with them (e.g. KeyEvent.VK_SHIFT could mean either the left or right shift key) will map to the left key.

Parameters:

keycode - Key to type (e.g. KeyEvent.VK_A)

Throws:

IllegalArgumentException - if keycode is not a valid key

IllegalThreadStateException - if called on the AWT event dispatching thread

Since:

See Also:

type

public void type(char c)

A convenience method that simulates typing a char by calling keyPress and keyRelease. Gets the ExtendedKeyCode for the char and calls type(int keycode).

Parameters:

c - Character to be typed (e.g. 'a')

Throws:

IllegalArgumentException - if keycode is not a valid key

IllegalThreadStateException - if called on the AWT event dispatching thread

Since:

See Also:

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.