java.awt
Class Robot

java.lang.Object
  extended by 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
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 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)