public class

Robot

extends Object
java.lang.Object
   ↳ java.awt.Robot

Class Overview

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.

Summary

Public Constructors
Robot()
Constructs a Robot object in the coordinate system of the primary screen.
Robot(GraphicsDevice screen)
Creates a Robot for the given screen device.
Public Methods
synchronized BufferedImage createScreenCapture(Rectangle screenRect)
Creates an image containing pixels read from the screen.
synchronized void delay(int ms)
Sleeps for the specified time.
synchronized int getAutoDelay()
Returns the number of milliseconds this Robot sleeps after generating an event.
synchronized Color getPixelColor(int x, int y)
Returns the color of a pixel at the given screen coordinates.
synchronized boolean isAutoWaitForIdle()
Returns whether this Robot automatically invokes waitForIdle after generating an event.
synchronized void keyPress(int keycode)
Presses a given key.
synchronized void keyRelease(int keycode)
Releases a given key.
synchronized void mouseMove(int x, int y)
Moves mouse pointer to given screen coordinates.
synchronized void mousePress(int buttons)
Presses one or more mouse buttons.
synchronized void mouseRelease(int buttons)
Releases one or more mouse buttons.
synchronized void mouseWheel(int wheelAmt)
Rotates the scroll wheel on wheel-equipped mice.
synchronized void setAutoDelay(int ms)
Sets the number of milliseconds this Robot sleeps after generating an event.
synchronized void setAutoWaitForIdle(boolean isOn)
Sets whether this Robot automatically invokes waitForIdle after generating an event.
synchronized String toString()
Returns a string representation of this Robot.
synchronized void waitForIdle()
Waits until all events currently on the event queue have been processed.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public Robot ()

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 if createRobot permission is not granted
See Also

public Robot (GraphicsDevice screen)

Creates a Robot for the given screen device. Coordinates passed to Robot method calls like mouseMove 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
This constructor is meant for the latter case.

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.
SecurityException if createRobot permission is not granted
See Also

Public Methods

public synchronized 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 if screenRect width and height are not greater than zero
SecurityException if readDisplayPixels permission is not granted
See Also

public synchronized void delay (int ms)

Sleeps for the specified time. To catch any InterruptedExceptions that occur, Thread.sleep() may be used instead.

Parameters
ms time to sleep in milliseconds
Throws
IllegalArgumentException if ms is not between 0 and 60,000 milliseconds inclusive
See Also

public synchronized int getAutoDelay ()

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

public synchronized 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

public synchronized boolean isAutoWaitForIdle ()

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

Returns
  • Whether waitForIdle is automatically called

public synchronized 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
See Also

public synchronized 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
See Also

public synchronized void mouseMove (int x, int y)

Moves mouse pointer to given screen coordinates.

Parameters
x X position
y Y position

public synchronized void mousePress (int buttons)

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

Parameters
buttons the Button mask; a combination of one or more of these flags:
  • InputEvent.BUTTON1_MASK
  • InputEvent.BUTTON2_MASK
  • InputEvent.BUTTON3_MASK
Throws
IllegalArgumentException if the button mask is not a valid combination
See Also

public synchronized void mouseRelease (int buttons)

Releases one or more mouse buttons.

Parameters
buttons the Button mask; a combination of one or more of these flags:
  • InputEvent.BUTTON1_MASK
  • InputEvent.BUTTON2_MASK
  • InputEvent.BUTTON3_MASK
Throws
IllegalArgumentException if the button mask is not a valid combination
See Also

public synchronized 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.

public synchronized void setAutoDelay (int ms)

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

Throws
IllegalArgumentException If ms is not between 0 and 60,000 milliseconds inclusive

public synchronized void setAutoWaitForIdle (boolean isOn)

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

Parameters
isOn Whether waitForIdle is automatically invoked

public synchronized String toString ()

Returns a string representation of this Robot.

Returns
  • the string representation.

public synchronized void waitForIdle ()

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

Throws
IllegalThreadStateException if called on the AWT event dispatching thread