java.awt
Class Robot

java.lang.Object sample code for java.lang.Object definition code for java.lang.Object 
  extended by java.awt.Robot

public class Robot
extends Object sample code for java.lang.Object definition code for java.lang.Object

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.

Since:
1.3

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

Constructor Detail

Robot sample code for java.awt.Robot() definition code for java.awt.Robot()

public Robot()
      throws AWTException sample code for java.awt.AWTException definition code for java.awt.AWTException 
Constructs a Robot object in the coordinate system of the primary screen.

Throws:
AWTException sample code for java.awt.AWTException definition code for java.awt.AWTException - if the platform configuration does not allow low-level input control. This exception is always thrown when GraphicsEnvironment.isHeadless() returns true
SecurityException sample code for java.lang.SecurityException definition code for java.lang.SecurityException - if createRobot permission is not granted
See Also:
GraphicsEnvironment.isHeadless() sample code for java.awt.GraphicsEnvironment.isHeadless() definition code for java.awt.GraphicsEnvironment.isHeadless() , SecurityManager.checkPermission(java.security.Permission) sample code for java.lang.SecurityManager.checkPermission(java.security.Permission) definition code for java.lang.SecurityManager.checkPermission(java.security.Permission) , AWTPermission sample code for java.awt.AWTPermission definition code for java.awt.AWTPermission

Robot sample code for java.awt.Robot(java.awt.GraphicsDevice) definition code for java.awt.Robot(java.awt.GraphicsDevice)

public Robot(GraphicsDevice sample code for java.awt.GraphicsDevice definition code for java.awt.GraphicsDevice  screen)
      throws AWTException sample code for java.awt.AWTException definition code for java.awt.AWTException 
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: 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 sample code for java.awt.AWTException definition code for java.awt.AWTException - if the platform configuration does not allow low-level input control. This exception is always thrown when GraphicsEnvironment.isHeadless() returns true.
IllegalArgumentException sample code for java.lang.IllegalArgumentException definition code for java.lang.IllegalArgumentException - if screen is not a screen GraphicsDevice.
SecurityException sample code for java.lang.SecurityException definition code for java.lang.SecurityException - if createRobot permission is not granted
See Also:
GraphicsEnvironment.isHeadless() sample code for java.awt.GraphicsEnvironment.isHeadless() definition code for java.awt.GraphicsEnvironment.isHeadless() , GraphicsDevice sample code for java.awt.GraphicsDevice definition code for java.awt.GraphicsDevice , SecurityManager.checkPermission(java.security.Permission) sample code for java.lang.SecurityManager.checkPermission(java.security.Permission) definition code for java.lang.SecurityManager.checkPermission(java.security.Permission) , AWTPermission sample code for java.awt.AWTPermission definition code for java.awt.AWTPermission
Method Detail

mouseMove sample code for java.awt.Robot.mouseMove(int, int) definition code for java.awt.Robot.mouseMove(int, int)

public void mouseMove(int x,
                      int y)
Moves mouse pointer to given screen coordinates.

Parameters:
x - X position
y - Y position

mousePress sample code for java.awt.Robot.mousePress(int) definition code for java.awt.Robot.mousePress(int)

public 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 sample code for java.lang.IllegalArgumentException definition code for java.lang.IllegalArgumentException - if the button mask is not a valid combination
See Also:
mouseRelease(int) sample code for java.awt.Robot.mouseRelease(int) definition code for java.awt.Robot.mouseRelease(int)

mouseRelease sample code for java.awt.Robot.mouseRelease(int) definition code for java.awt.Robot.mouseRelease(int)

public 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 sample code for java.lang.IllegalArgumentException definition code for java.lang.IllegalArgumentException - if the button mask is not a valid combination
See Also:
mousePress(int) sample code for java.awt.Robot.mousePress(int) definition code for java.awt.Robot.mousePress(int)

mouseWheel sample code for java.awt.Robot.mouseWheel(int) definition code for java.awt.Robot.mouseWheel(int)

public 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

keyPress sample code for java.awt.Robot.keyPress(int) definition code for java.awt.Robot.keyPress(int)

public 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 sample code for java.lang.IllegalArgumentException definition code for java.lang.IllegalArgumentException - if keycode is not a valid key
See Also:
keyRelease(int) sample code for java.awt.Robot.keyRelease(int) definition code for java.awt.Robot.keyRelease(int) , KeyEvent sample code for java.awt.event.KeyEvent definition code for java.awt.event.KeyEvent

keyRelease sample code for java.awt.Robot.keyRelease(int) definition code for java.awt.Robot.keyRelease(int)

public 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 sample code for java.lang.IllegalArgumentException definition code for java.lang.IllegalArgumentException - if keycode is not a valid key
See Also:
keyPress(int) sample code for java.awt.Robot.keyPress(int) definition code for java.awt.Robot.keyPress(int) , KeyEvent sample code for java.awt.event.KeyEvent definition code for java.awt.event.KeyEvent

getPixelColor sample code for java.awt.Robot.getPixelColor(int, int) definition code for java.awt.Robot.getPixelColor(int, int)

public Color sample code for java.awt.Color definition code for java.awt.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

createScreenCapture sample code for java.awt.Robot.createScreenCapture(java.awt.Rectangle) definition code for java.awt.Robot.createScreenCapture(java.awt.Rectangle)

public BufferedImage sample code for java.awt.image.BufferedImage definition code for java.awt.image.BufferedImage  createScreenCapture(Rectangle sample code for java.awt.Rectangle definition code for java.awt.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 sample code for java.lang.IllegalArgumentException definition code for java.lang.IllegalArgumentException - if screenRect width and height are not greater than zero
SecurityException sample code for java.lang.SecurityException definition code for java.lang.SecurityException - if readDisplayPixels permission is not granted
See Also:
SecurityManager.checkPermission(java.security.Permission) sample code for java.lang.SecurityManager.checkPermission(java.security.Permission) definition code for java.lang.SecurityManager.checkPermission(java.security.Permission) , AWTPermission sample code for java.awt.AWTPermission definition code for java.awt.AWTPermission

isAutoWaitForIdle sample code for java.awt.Robot.isAutoWaitForIdle() definition code for java.awt.Robot.isAutoWaitForIdle()

public boolean isAutoWaitForIdle()
Returns whether this Robot automatically invokes waitForIdle after generating an event.

Returns:
Whether waitForIdle is automatically called

setAutoWaitForIdle sample code for java.awt.Robot.setAutoWaitForIdle(boolean) definition code for java.awt.Robot.setAutoWaitForIdle(boolean)

public void setAutoWaitForIdle(boolean isOn)
Sets whether this Robot automatically invokes waitForIdle after generating an event.

Parameters:
isOn - Whether waitForIdle is automatically invoked

getAutoDelay sample code for java.awt.Robot.getAutoDelay() definition code for java.awt.Robot.getAutoDelay()

public int getAutoDelay()
Returns the number of milliseconds this Robot sleeps after generating an event.


setAutoDelay sample code for java.awt.Robot.setAutoDelay(int) definition code for java.awt.Robot.setAutoDelay(int)

public void setAutoDelay(int ms)
Sets the number of milliseconds this Robot sleeps after generating an event.

Throws:
IllegalArgumentException sample code for java.lang.IllegalArgumentException definition code for java.lang.IllegalArgumentException - If ms is not between 0 and 60,000 milliseconds inclusive

delay sample code for java.awt.Robot.delay(int) definition code for java.awt.Robot.delay(int)

public 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 sample code for java.lang.IllegalArgumentException definition code for java.lang.IllegalArgumentException - if ms is not between 0 and 60,000 milliseconds inclusive
See Also:
Thread.sleep(long) sample code for java.lang.Thread.sleep(long) definition code for java.lang.Thread.sleep(long)

waitForIdle sample code for java.awt.Robot.waitForIdle() definition code for java.awt.Robot.waitForIdle()

public void waitForIdle()
Waits until all events currently on the event queue have been processed.

Throws:
IllegalThreadStateException sample code for java.lang.IllegalThreadStateException definition code for java.lang.IllegalThreadStateException - if called on the AWT event dispatching thread

toString sample code for java.awt.Robot.toString() definition code for java.awt.Robot.toString()

public String sample code for java.lang.String definition code for java.lang.String  toString()
Returns a string representation of this Robot.

Overrides:
toString sample code for java.lang.Object.toString() definition code for java.lang.Object.toString() in class Object sample code for java.lang.Object definition code for java.lang.Object
Returns:
the string representation.