java.awt

Class Robot

java.lang.Object

java.awt.Robot

public class Robot
extends Object

The Robot class is used to simulate user interaction with graphical programs. It can generate native windowing system input events and retrieve image data from the current screen. Robot is used to test the AWT and Swing library implementations; it can also be used to create self-running demo programs. Since Robot generates native windowing system events, rather than simply inserting AWTEvents on the AWT event queue, its use is not restricted to Java programs. It can be used to programatically drive any graphical application. This implementation requires an X server that supports the XTest extension.

Since:

1.3

Constructor Summary

Constructors

Constructor and Description
Robot() Construct a Robot object that operates on the default screen.
Robot(GraphicsDevice screen) Construct a Robot object that operates on the specified screen.

Method Summary

Methods

Modifier and Type	Method and Description
BufferedImage	createScreenCapture(Rectangle screenRect) Create an image containing pixels read from the screen.
void	delay(int ms) Sleep for a specified length of time.
int	getAutoDelay() Retrieve the length of time this Robot sleeps after generating an event.
Color	getPixelColor(int x, int y) Return the color of the pixel at the given screen coordinates.
boolean	isAutoWaitForIdle() Check if this Robot automatically calls waitForIdle() after generating an event.
void	keyPress(int keycode) Press a key.
void	keyRelease(int keycode) Release a key.
void	mouseMove(int x, int y) Move the mouse pointer to absolute coordinates (x, y).
void	mousePress(int buttons) Press one or more mouse buttons.
void	mouseRelease(int buttons) Release one or more mouse buttons.
void	mouseWheel(int wheelAmt) Rotate the mouse scroll wheel.
void	setAutoDelay(int ms) Set the length of time this Robot sleeps after generating an event.
void	setAutoWaitForIdle(boolean isOn) Set whether or not this Robot automatically calls waitForIdle() after generating an event.
String	toString() Return a string representation of this Robot.
void	waitForIdle() Wait until all events currently on the event queue have been dispatched.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Robot

public Robot()
      throws AWTException

Construct a Robot object that operates on the default screen.

Throws:

AWTException - if GraphicsEnvironment.isHeadless() returns true or if the X server does not support the XTest extension

SecurityException - if createRobot permission is not granted

Robot

public Robot(GraphicsDevice screen)
      throws AWTException

Construct a Robot object that operates on the specified screen.

Throws:

AWTException - if GraphicsEnvironment.isHeadless() returns true or if the X server does not support the XTest extension

IllegalArgumentException - if screen is not a screen GraphicsDevice

SecurityException - if createRobot permission is not granted

Method Detail

mouseMove

public void mouseMove(int x,
             int y)

Move the mouse pointer to absolute coordinates (x, y).

Parameters:

x - the destination x coordinate

y - the destination y coordinate

mousePress

public void mousePress(int buttons)

Press one or more mouse buttons.

Parameters:

buttons - the buttons to press; a bitmask of one or more of these InputEvent fields:

• BUTTON1_MASK
• BUTTON2_MASK
• BUTTON3_MASK

Throws:

IllegalArgumentException - if the button mask is invalid

mouseRelease

public void mouseRelease(int buttons)

Release one or more mouse buttons.

Parameters:

buttons - the buttons to release; a bitmask of one or more of these InputEvent fields:

• BUTTON1_MASK
• BUTTON2_MASK
• BUTTON3_MASK

Throws:

IllegalArgumentException - if the button mask is invalid

mouseWheel

public void mouseWheel(int wheelAmt)

Rotate the mouse scroll wheel.

Parameters:

wheelAmt - number of steps to rotate mouse wheel. negative to rotate wheel up (away from the user), positive to rotate wheel down (toward the user).

Since:

1.4

keyPress

public void keyPress(int keycode)

Press a key.

Parameters:

keycode - key to press, a KeyEvent VK_ constant

Throws:

IllegalArgumentException - if keycode is not a valid key

keyRelease

public void keyRelease(int keycode)

Release a key.

Parameters:

keycode - key to release, a KeyEvent VK_ constant

Throws:

IllegalArgumentException - if keycode is not a valid key

getPixelColor

public Color getPixelColor(int x,
                  int y)

Return the color of the pixel at the given screen coordinates.

Parameters:

x - the x coordinate of the pixel

y - the y coordinate of the pixel

Returns:

the Color of the pixel at screen coodinates (x, y)

createScreenCapture

public BufferedImage createScreenCapture(Rectangle screenRect)

Create an image containing pixels read from the screen. The image does not include the mouse pointer.

Parameters:

screenRect - the rectangle of pixels to capture, in screen coordinates

Returns:

a BufferedImage containing the requested pixels

Throws:

IllegalArgumentException - if requested width and height are not both greater than zero

SecurityException - if readDisplayPixels permission is not granted

isAutoWaitForIdle

public boolean isAutoWaitForIdle()

Check if this Robot automatically calls waitForIdle() after generating an event.

Returns:

true if waitForIdle is automatically called

setAutoWaitForIdle

public void setAutoWaitForIdle(boolean isOn)

Set whether or not this Robot automatically calls waitForIdle() after generating an event.

Parameters:

isOn - true if waitForIdle should be called automatically

getAutoDelay

public int getAutoDelay()

Retrieve the length of time this Robot sleeps after generating an event.

Returns:

the length of time in milliseconds

setAutoDelay

public void setAutoDelay(int ms)

Set the length of time this Robot sleeps after generating an event.

Parameters:

ms - the length of time in milliseconds

Throws:

IllegalArgumentException - if ms is not between 0 and 60,000 milliseconds inclusive

delay

public void delay(int ms)

Sleep for a specified length of time.

Parameters:

ms - the length of time in milliseconds

Throws:

IllegalArgumentException - if ms is not between 0 and 60,000 milliseconds inclusive

waitForIdle

public void waitForIdle()

Wait until all events currently on the event queue have been dispatched.

toString

public String toString()

Return a string representation of this Robot.

Overrides:

toString in class Object

Returns:

a string representation

See Also:

Object.getClass(), Object.hashCode(), Class.getName(), Integer.toHexString(int)