public class Robot extends Object
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.
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:
Constructor | Description |
---|---|
Robot() |
Constructs a Robot object in the coordinate system of the primary screen. |
Robot |
Creates a Robot for the given screen device. |
Modifier and Type | Method | Description |
---|---|---|
MultiResolutionImage |
createMultiResolutionScreenCapture |
Creates an image containing pixels read from the screen. |
BufferedImage |
createScreenCapture |
Creates an image containing pixels read from the screen. |
void |
delay |
Sleeps for the specified time. |
int |
getAutoDelay() |
Returns the number of milliseconds this Robot sleeps after generating an event. |
Color |
getPixelColor |
Returns the color of a pixel at the given screen coordinates. |
boolean |
isAutoWaitForIdle() |
Returns whether this Robot automatically invokes waitForIdle after generating an event. |
void |
keyPress |
Presses a given key. |
void |
keyRelease |
Releases a given key. |
void |
mouseMove |
Moves mouse pointer to given screen coordinates. |
void |
mousePress |
Presses one or more mouse buttons. |
void |
mouseRelease |
Releases one or more mouse buttons. |
void |
mouseWheel |
Rotates the scroll wheel on wheel-equipped mice. |
void |
setAutoDelay |
Sets the number of milliseconds this Robot sleeps after generating an event. |
void |
setAutoWaitForIdle |
Sets whether this Robot automatically invokes waitForIdle after generating an event. |
String |
toString() |
Returns a string representation of this Robot. |
void |
waitForIdle() |
Waits until all events currently on the event queue have been processed. |
public Robot() throws AWTException
AWTException
- if the platform configuration does not allow low-level input control. This exception is always thrown when GraphicsEnvironment.isHeadless() returns trueSecurityException
- if createRobot
permission is not grantedpublic Robot(GraphicsDevice screen) throws AWTException
If screen devices are reconfigured such that the coordinate system is affected, the behavior of existing Robot objects is undefined.
screen
- A screen GraphicsDevice indicating the coordinate system the Robot will operate in.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.SecurityException
- if createRobot
permission is not grantedpublic void mouseMove(int x, int y)
The mouse pointer may not visually move on some platforms, while the subsequent mousePress and mouseRelease can be delivered to the correct location
x
- X positiony
- Y positionpublic void mousePress(int buttons)
mouseRelease(int)
method.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:
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
. 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()
. 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
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.IllegalArgumentException
- if the buttons
mask contains the mask for extra mouse button and support for extended mouse buttons is disabled
by JavaIllegalArgumentException
- 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 Javapublic void mouseRelease(int buttons)
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:
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
. 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()
. 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
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.IllegalArgumentException
- if the buttons
mask contains the mask for extra mouse button and support for extended mouse buttons is disabled
by JavaIllegalArgumentException
- 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 Javapublic void mouseWheel(int wheelAmt)
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.public void keyPress(int keycode)
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.
keycode
- Key to press (e.g. KeyEvent.VK_A
)IllegalArgumentException
- if keycode
is not a valid keypublic void keyRelease(int keycode)
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.
keycode
- Key to release (e.g. KeyEvent.VK_A
)IllegalArgumentException
- if keycode
is not a valid keypublic Color getPixelColor(int x, int y)
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.
x
- X position of pixely
- Y position of pixelSecurityException
- if readDisplayPixels
permission is not granted, or access to the screen is denied by the desktop environmentpublic BufferedImage createScreenCapture(Rectangle screenRect)
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 contents of the returned BufferedImage
are undefined.
screenRect
- Rect to capture in screen coordinatesIllegalArgumentException
- if screenRect
width and height are not greater than zeroSecurityException
- if readDisplayPixels
permission is not granted, or access to the screen is denied by the desktop environmentpublic MultiResolutionImage createMultiResolutionScreenCapture(Rectangle screenRect)
MultiResolutionImage
. For a non-scaled display, the MultiResolutionImage
will have one image variant:
For a high resolution display where there is a scaling transform, the MultiResolutionImage
will have two image variants:
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);
}
screenRect
- Rect to capture in screen coordinatesIllegalArgumentException
- if screenRect
width and height are not greater than zeroSecurityException
- if readDisplayPixels
permission is not granted, or access to the screen is denied by the desktop environmentpublic boolean isAutoWaitForIdle()
waitForIdle
after generating an event.waitForIdle
is automatically calledpublic void setAutoWaitForIdle(boolean isOn)
waitForIdle
after generating an event.isOn
- Whether waitForIdle
is automatically invokedpublic int getAutoDelay()
public void setAutoDelay(int ms)
ms
- the delay duration in millisecondsIllegalArgumentException
- If ms
is not between 0 and 60,000 milliseconds inclusivepublic void delay(int ms)
If the invoking thread is interrupted while waiting, then it will return immediately with the interrupt status set. If the interrupted status is already set, this method returns immediately with the interrupt status set.
ms
- time to sleep in millisecondsIllegalArgumentException
- if ms
is not between 0
and 60,000
milliseconds inclusivepublic void waitForIdle()
IllegalThreadStateException
- if called on the AWT event dispatching threadpublic String toString()
© 1993, 2023, 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.
https://docs.oracle.com/en/java/javase/21/docs/api/java.desktop/java/awt/Robot.html