java.awt

Class 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 {@link AWTEvent}s 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
	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
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 {@link #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 {@link #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.

Constructor Detail

Robot

public Robot()

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)

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

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

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

getAutoDelay

public int getAutoDelay()

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

Returns: the length of time in milliseconds

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)

isAutoWaitForIdle

public boolean isAutoWaitForIdle()

Check if this Robot automatically calls {@link #waitForIdle()} after generating an event.

Returns: true if waitForIdle is automatically called

keyPress

public void keyPress(int keycode)

Press a key.

Parameters: keycode key to press, a {@link java.awt.event.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 {@link java.awt.event.KeyEvent} VK_ constant

Throws: IllegalArgumentException if keycode is not a valid key

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 {@link 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 {@link 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

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

setAutoWaitForIdle

public void setAutoWaitForIdle(boolean isOn)

Set whether or not this Robot automatically calls {@link #waitForIdle()} after generating an event.

Parameters: isOn true if waitForIdle should be called automatically

toString

public String toString()

Return a string representation of this Robot.

Returns: a string representation

waitForIdle

public void waitForIdle()

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