Robot (Java 2 Platform SE v1.4.1_"07")

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

JavaTM 2 Platform
Std. Ed. v1.4.1_"07"

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | 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` | `mouseWheel(int wheelAmt)` Rotates the scroll wheel on wheel-equipped mice.
`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. This exception is always thrown when GraphicsEnvironment.isHeadless() returns true
  `SecurityException` - if `createRobot` permission is not granted
See Also:
  `GraphicsEnvironment.isHeadless()`, `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. This exception is always thrown when GraphicsEnvironment.isHeadless() returns true.
  `IllegalArgumentException` - if `screen` is not a screen GraphicsDevice.
  `SecurityException` - if `createRobot` permission is not granted
See Also:
  `GraphicsEnvironment.isHeadless()`, `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` - the Button mask; a combination of one or more of these flags:
    - `InputEvent.BUTTON1_MASK`
    - `InputEvent.BUTTON2_MASK`
    - `InputEvent.BUTTON3_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` - the Button mask; a combination of one or more of these flags:
    - `InputEvent.BUTTON1_MASK`
    - `InputEvent.BUTTON2_MASK`
    - `InputEvent.BUTTON3_MASK`
  Throws:
    `IllegalArgumentException` - if the button mask is not a valid combination

### mouseWheel

    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

    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.

  Throws:
    `IllegalArgumentException` - if `keycode` is not a valid key
  See Also:
    `KeyEvent`

### 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.

  Throws:
    `IllegalArgumentException` - if `keycode` is not a valid key
  See Also:
    `KeyEvent`

### 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. To catch any `InterruptedException`s that occur, `Thread.sleep()` may be used instead.

  Parameters:
    `ms` - time to sleep in milliseconds
  Throws:
    `IllegalArgumentException` - if `ms` is not between 0 and 60,000 milliseconds inclusive
  See Also:
    `Thread.sleep(long)`

### 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.4.1_"07"

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | 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.

Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.