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.
Constructor and 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.
|
Modifier and Type | Method and Description |
---|---|
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.
|
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 |
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 grantedGraphicsEnvironment.isHeadless()
,
SecurityManager.checkPermission(java.security.Permission)
,
AWTPermission
public 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 grantedGraphicsEnvironment.isHeadless()
,
GraphicsDevice
,
SecurityManager.checkPermission(java.security.Permission)
,
AWTPermission
public void mouseMove(int x, int y)
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 JavamouseRelease(int)
,
InputEvent.getMaskForButton(int)
,
Toolkit.areExtraMouseButtonsEnabled()
,
MouseInfo.getNumberOfButtons()
,
MouseEvent
public 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 JavamousePress(int)
,
InputEvent.getMaskForButton(int)
,
Toolkit.areExtraMouseButtonsEnabled()
,
MouseInfo.getNumberOfButtons()
,
MouseEvent
public 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 keykeyRelease(int)
,
KeyEvent
public 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 keykeyPress(int)
,
KeyEvent
public Color getPixelColor(int x, int y)
x
- X position of pixely
- Y position of pixelpublic BufferedImage createScreenCapture(Rectangle screenRect)
screenRect
- Rect to capture in screen coordinatesIllegalArgumentException
- if screenRect
width and height are not greater than zeroSecurityException
- if readDisplayPixels
permission is not grantedSecurityManager.checkPermission(java.security.Permission)
,
AWTPermission
public 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)
IllegalArgumentException
- If ms
is not between 0 and 60,000 milliseconds inclusivepublic void delay(int ms)
InterruptedException
s that occur,
Thread.sleep()
may be used instead.ms
- time to sleep in millisecondsIllegalArgumentException
- if ms
is not between 0 and 60,000 milliseconds inclusiveThread.sleep(long)
public void waitForIdle()
IllegalThreadStateException
- if called on the AWT event dispatching thread Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2020, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.
Scripting on this page tracks web page traffic, but does not change the content in any way.