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:
- 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.
- 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.
- Since:
- 1.3
- 
Constructor SummaryConstructorsConstructorDescriptionRobot()Constructs a Robot object in the coordinate system of the primary screen.Robot(GraphicsDevice screen) Creates a Robot for the given screen device.
- 
Method SummaryModifier and TypeMethodDescriptioncreateMultiResolutionScreenCapture(Rectangle screenRect) Creates an image containing pixels read from the screen.createScreenCapture(Rectangle screenRect) Creates an image containing pixels read from the screen.voiddelay(int ms) Sleeps for the specified time.intReturns the number of milliseconds this Robot sleeps after generating an event.getPixelColor(int x, int y) Returns the color of a pixel at the given screen coordinates.booleanReturns whether this Robot automatically invokeswaitForIdleafter generating an event.voidkeyPress(int keycode) Presses a given key.voidkeyRelease(int keycode) Releases a given key.voidmouseMove(int x, int y) Moves mouse pointer to given screen coordinates.voidmousePress(int buttons) Presses one or more mouse buttons.voidmouseRelease(int buttons) Releases one or more mouse buttons.voidmouseWheel(int wheelAmt) Rotates the scroll wheel on wheel-equipped mice.voidsetAutoDelay(int ms) Sets the number of milliseconds this Robot sleeps after generating an event.voidsetAutoWaitForIdle(boolean isOn) Sets whether this Robot automatically invokeswaitForIdleafter generating an event.toString()Returns a string representation of this Robot.voidWaits until all events currently on the event queue have been processed.
- 
Constructor Details- 
RobotConstructs 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- if- createRobotpermission is not granted
- See Also:
 
- 
RobotCreates 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- screenis not a screen GraphicsDevice.
- SecurityException- if- createRobotpermission is not granted
- See Also:
 
 
- 
- 
Method Details- 
mouseMovepublic 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
 
- 
mousePresspublic void mousePress(int buttons) Presses one or more mouse buttons. The mouse buttons should be released using themouseRelease(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 - buttonsparameter. A valid combination consists of- InputEvent.BUTTON1_DOWN_MASK,- InputEvent.BUTTON2_DOWN_MASK,- InputEvent.BUTTON3_DOWN_MASKand 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
 disabledby 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
 enabledby 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_MASKinstead. Either extended- _DOWN_MASKor old- _MASKvalues should be used, but both those models should not be mixed.
-  If support for extended mouse buttons is
 
- Throws:
- IllegalArgumentException- if the- buttonsmask contains the mask for extra mouse button and support for extended mouse buttons is- disabledby Java
- IllegalArgumentException- if the- buttonsmask contains the mask for extra mouse button that does not exist on the mouse and support for extended mouse buttons is- enabledby Java
- See Also:
 
- 
mouseReleasepublic 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 - buttonsparameter. A valid combination consists of- InputEvent.BUTTON1_DOWN_MASK,- InputEvent.BUTTON2_DOWN_MASK,- InputEvent.BUTTON3_DOWN_MASKand values returned by the- InputEvent.getMaskForButton(button)method. The valid combination also depends on a- Toolkit.areExtraMouseButtonsEnabled()value as follows:-  If the support for extended mouse buttons is
 disabledby 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
 enabledby 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_MASKinstead. Either extended- _DOWN_MASKor old- _MASKvalues should be used, but both those models should not be mixed.
-  If the support for extended mouse buttons is
 
- Throws:
- IllegalArgumentException- if the- buttonsmask contains the mask for extra mouse button and support for extended mouse buttons is- disabledby Java
- IllegalArgumentException- if the- buttonsmask contains the mask for extra mouse button that does not exist on the mouse and support for extended mouse buttons is- enabledby Java
- See Also:
 
- 
mouseWheelpublic 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
 
- 
keyPresspublic void keyPress(int keycode) Presses a given key. The key should be released using thekeyReleasemethod.Key codes that have more than one physical key associated with them (e.g. KeyEvent.VK_SHIFTcould 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- keycodeis not a valid key
- See Also:
 
- 
keyReleasepublic void keyRelease(int keycode) Releases a given key.Key codes that have more than one physical key associated with them (e.g. KeyEvent.VK_SHIFTcould 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- keycodeis not a valid key
- See Also:
 
- 
getPixelColorReturns 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 SecurityExceptionmay be thrown, or the content of the returnedColoris 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- readDisplayPixelspermission is not granted, or access to the screen is denied by the desktop environment
 
- 
createScreenCaptureCreates an image containing pixels read from the screen.If the desktop environment requires that permissions be granted to capture screen content, and the required permissions are not granted, then a SecurityExceptionmay be thrown, or the contents of the returnedBufferedImageare 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:
- screenRect- Rect to capture in screen coordinates
- Returns:
- The captured image
- Throws:
- IllegalArgumentException- if- screenRectwidth and height are not greater than zero
- SecurityException- if- readDisplayPixelspermission is not granted, or access to the screen is denied by the desktop environment
- See Also:
 
- 
createMultiResolutionScreenCaptureCreates 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 aMultiResolutionImage.For a non-scaled display, the MultiResolutionImagewill have one image variant:- Base Image with user specified size.
 For a high resolution display where there is a scaling transform, the MultiResolutionImagewill 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- if- screenRectwidth and height are not greater than zero
- SecurityException- if- readDisplayPixelspermission is not granted, or access to the screen is denied by the desktop environment
- Since:
- 9
- See Also:
 
- 
isAutoWaitForIdlepublic boolean isAutoWaitForIdle()Returns whether this Robot automatically invokeswaitForIdleafter generating an event.- Returns:
- Whether waitForIdleis automatically called
 
- 
setAutoWaitForIdlepublic void setAutoWaitForIdle(boolean isOn) Sets whether this Robot automatically invokeswaitForIdleafter generating an event.- Parameters:
- isOn- Whether- waitForIdleis automatically invoked
 
- 
getAutoDelaypublic int getAutoDelay()Returns the number of milliseconds this Robot sleeps after generating an event.- Returns:
- the delay duration in milliseconds
 
- 
setAutoDelaypublic 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- msis not between 0 and 60,000 milliseconds inclusive
 
- 
delaypublic void delay(int ms) Sleeps for the specified time.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. - Parameters:
- ms- time to sleep in milliseconds
- Throws:
- IllegalArgumentException- if- msis not between- 0and- 60,000milliseconds inclusive
 
- 
waitForIdlepublic void waitForIdle()Waits until all events currently on the event queue have been processed.- Throws:
- IllegalThreadStateException- if called on the AWT event dispatching thread
 
- 
toStringReturns a string representation of this Robot.
 
-