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.
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.
- Since:
- 1.3
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 |
---|---|---|
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. |
boolean | isAutoWaitForIdle() | Returns whether this Robot automatically invokes |
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 |
String | toString() | Returns a string representation of this Robot. |
void | waitForIdle() | Waits until all events currently on the event queue have been processed. |
Methods declared in class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
Constructor Detail
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 -
SecurityException
- ifcreateRobot
permission is not granted - See Also:
-
GraphicsEnvironment.isHeadless()
,SecurityManager.checkPermission(java.security.Permission)
,AWTPermission
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
- ifscreen
is not a screen GraphicsDevice. -
SecurityException
- ifcreateRobot
permission is not granted - See Also:
-
GraphicsEnvironment.isHeadless()
,GraphicsDevice
,SecurityManager.checkPermission(java.security.Permission)
,AWTPermission
Method Detail
mouseMove
public void mouseMove(int x, int y)
Moves mouse pointer to given screen coordinates.
- Parameters:
-
x
- X position -
y
- Y position
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 ofInputEvent.BUTTON1_DOWN_MASK
,InputEvent.BUTTON2_DOWN_MASK
,InputEvent.BUTTON3_DOWN_MASK
and values returned by theInputEvent.getMaskForButton(button)
method. The valid combination also depends on aToolkit.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 toMouseInfo.getNumberOfButtons()
.
It is recommended to use theInputEvent.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. - If support for extended mouse buttons is
- Throws:
-
IllegalArgumentException
- if thebuttons
mask contains the mask for extra mouse button and support for extended mouse buttons isdisabled
by Java -
IllegalArgumentException
- if thebuttons
mask contains the mask for extra mouse button that does not exist on the mouse and support for extended mouse buttons isenabled
by Java - See Also:
-
mouseRelease(int)
,InputEvent.getMaskForButton(int)
,Toolkit.areExtraMouseButtonsEnabled()
,MouseInfo.getNumberOfButtons()
,MouseEvent
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.It is allowed to use only a combination of valid values as a
buttons
parameter. A valid combination consists ofInputEvent.BUTTON1_DOWN_MASK
,InputEvent.BUTTON2_DOWN_MASK
,InputEvent.BUTTON3_DOWN_MASK
and values returned by theInputEvent.getMaskForButton(button)
method. The valid combination also depends on aToolkit.areExtraMouseButtonsEnabled()
value as follows:- 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 toMouseInfo.getNumberOfButtons()
.
It is recommended to use theInputEvent.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. - If the support for extended mouse buttons is
- Throws:
-
IllegalArgumentException
- if thebuttons
mask contains the mask for extra mouse button and support for extended mouse buttons isdisabled
by Java -
IllegalArgumentException
- if thebuttons
mask contains the mask for extra mouse button that does not exist on the mouse and support for extended mouse buttons isenabled
by Java - See Also:
-
mousePress(int)
,InputEvent.getMaskForButton(int)
,Toolkit.areExtraMouseButtonsEnabled()
,MouseInfo.getNumberOfButtons()
,MouseEvent
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. - 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
- ifkeycode
is not a valid key - See Also:
-
keyRelease(int)
,KeyEvent
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
- ifkeycode
is not a valid key - See Also:
-
keyPress(int)
,KeyEvent
getPixelColor
public Color getPixelColor(int x, int y)
Returns the color of a pixel at the given screen coordinates.
- Parameters:
-
x
- X position of pixel -
y
- Y position of pixel - Returns:
- Color of the pixel
createScreenCapture
public BufferedImage createScreenCapture(Rectangle screenRect)
Creates an image containing pixels read from the screen. This image does not include the mouse cursor.
- Parameters:
-
screenRect
- Rect to capture in screen coordinates - Returns:
- The captured image
- Throws:
-
IllegalArgumentException
- ifscreenRect
width and height are not greater than zero -
SecurityException
- ifreadDisplayPixels
permission is not granted - See Also:
-
SecurityManager.checkPermission(java.security.Permission)
,AWTPermission
createMultiResolutionScreenCapture
public MultiResolutionImage createMultiResolutionScreenCapture(Rectangle screenRect)
Creates an image containing pixels read from the screen. This image does not include the mouse cursor. 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); }
- Parameters:
-
screenRect
- Rect to capture in screen coordinates - Returns:
- The captured image
- Throws:
-
IllegalArgumentException
- ifscreenRect
width and height are not greater than zero -
SecurityException
- ifreadDisplayPixels
permission is not granted - Since:
- 9
- See Also:
-
SecurityManager.checkPermission(java.security.Permission)
,AWTPermission
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.
- Parameters:
-
isOn
- WhetherwaitForIdle
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
- Ifms
is not between 0 and 60,000 milliseconds inclusive
delay
public void delay(int ms)
Sleeps for the specified time. To catch any InterruptedException
s that occur, Thread.sleep()
may be used instead.
- Parameters:
-
ms
- time to sleep in milliseconds - Throws:
-
IllegalArgumentException
- ifms
is not between 0 and 60,000 milliseconds inclusive - See Also:
Thread.sleep(long)
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.