Whole document tree


www.fifi.org
    Documentation
        Manpages
        GNU Info
        Debian document tree
        Whole document tree
    Trigance web page
    Public services
    User info
    Mailing lists
    Secure server
    Multilingual usage
 

Copyright (C) 2000-2012
Philippe Troin
<webmaster@fifi.org>.

Validate HTML
Validate CSS

    

Whole document tree

Java 2 Platform SE v1.3.1: Class Robot
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
JavaTM 2 Platform
Std. Ed. v1.3.1
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD

java.awt
Class Robot

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

Constructor Detail

Robot

public Robot()
      throws AWTException
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
SecurityException - if createRobot permission is not granted
See Also:
SecurityManager.checkPermission(java.security.Permission), AWTPermission

Robot

public Robot(GraphicsDevice screen)
      throws 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:
  • 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
IllegalArgumentException - if screen is not a screen GraphicsDevice.
SecurityException - if createRobot permission is not granted
See Also:
GraphicsDevice, SecurityManager.checkPermission(java.security.Permission), AWTPermission
Method Detail

mouseMove

public void mouseMove(int x,
                      int y)
Moves mouse pointer to given screen coordinates.
Parameters:
x - X position
y - Y position

mousePress

public void mousePress(int buttons)
Presses one or more mouse buttons.
Parameters:
buttons - Button mask (combination of InputEvent.BUTTON1/2/3_MASK)
Throws:
IllegalArgumentException - if the button mask is not a valid combination

mouseRelease

public void mouseRelease(int buttons)
Releases one or more mouse buttons.
Parameters:
buttons - Button mask (combination of InputEvent.BUTTON1/2/3_MASK)
Throws:
IllegalArgumentException - if the button mask is not a valid combination

keyPress

public void keyPress(int keycode)
Presses 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 press (e.g. KeyEvent.VK_A)
Throws:
IllegalArgumentException - if keycode is not a valid key

keyRelease

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 - if keycode is not a valid key

getPixelColor

public 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

public BufferedImage createScreenCapture(Rectangle screenRect)
Creates an image containing pixels read from the screen.
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:
SecurityManager.checkPermission(java.security.Permission), AWTPermission

isAutoWaitForIdle

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

setAutoWaitForIdle

public void setAutoWaitForIdle(boolean isOn)
Sets whether this Robot automatically invokes waitForIdle after generating an event.
Parameters:
isOn - Whether waitForIdle is automatically invoked

getAutoDelay

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

setAutoDelay

public 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

delay

public void delay(int ms)
Sleeps for the specified time.
Parameters:
ms - Time to sleep in milliseconds
Throws:
IllegalArgumentException - If ms is not between 0 and 60,000 milliseconds inclusive

waitForIdle

public void waitForIdle()
Waits until all events currently on the event queue have been processed.
Throws:
IllegalThreadStateException - if called on the AWT event dispatching thread

toString

public String toString()
Returns a string representation of this Robot.
Overrides:
toString in class Object
Returns:
the string representation.
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
JavaTM 2 Platform
Std. Ed. v1.3.1
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD
Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Java, Java 2D, and JDBC are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2001 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.