APIdia Launch Partner
Top Description Fields Constructors Methods
java.awt

public Class Robot

extends Object
Class Inheritance
Imports
java.awt.event.InputEvent, .KeyEvent, java.awt.geom.AffineTransform, java.awt.image.BaseMultiResolutionImage, .BufferedImage, .DataBufferInt, .DirectColorModel, .MultiResolutionImage, .Raster, .WritableRaster, java.awt.peer.RobotPeer, sun.awt.ComponentFactory, .SunToolkit, sun.awt.image.SunWritableRaster, sun.java2d.SunGraphicsEnvironment
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.

API Note

When autoWaitForIdle() is enabled, mouse and key related methods cannot be called on the AWT EDT. This is because when autoWaitForIdle() is enabled, the mouse and key methods implicitly call waitForIdle() which will throw IllegalThreadStateException when called on the AWT EDT. In addition, screen capture operations can be lengthy and delay(long ms) clearly inserts a delay, so these also should not be called on the EDT. Taken together, this means that as much as possible, methods on this class should not be called on the EDT.

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.

Platforms and desktop environments may impose restrictions or limitations on the access required to implement all functionality in the Robot class. For example:

The Robot API specification requires that approvals for these be granted for full operation. If they are not granted, the API will be degraded as discussed here. Relevant specific API methods may document more specific limitations and requirements. Depending on the policies of the desktop environment, the approvals mentioned above may: When such approvals need to given interactively, it may impede the normal operation of the application until approved, and if approval is denied or not possible, or cannot be made persistent then it will degrade the functionality of this class and in turn any part of the operation of the application which is dependent on it.
Author
Robi Khan
Since
1.3

Field Summary

Modifier and TypeField and Description
private int
autoDelay

public static final int
DEFAULT_DELAY

Default delay in milliseconds for mouse glide, type, and click.

public static final int
DEFAULT_STEP_LENGTH

Default pixel step-length for mouse glide.

private boolean
isAutoWaitForIdle

private static final int
MAX_DELAY

private RobotPeer
peer

private DirectColorModel
screenCapCM

Constructor Summary

AccessConstructor and Description
public
Robot()

Constructs a Robot object in the coordinate system of the primary screen.

public
Robot(GraphicsDevice
A screen GraphicsDevice indicating the coordinate system the Robot will operate in.
screen)

Creates a Robot for the given screen device.

Method Summary

Modifier and TypeMethod and Description
private void
afterEvent()

private void
autoDelay()

private void
autoWaitForIdle()

private static void
checkButtonsArgument(int buttons)

private static void
checkDelayArgument(int ms)

private static void
checkHeadless()

Check for headless state and throw AWTException if headless.

private static void
checkIsScreenDevice(GraphicsDevice device)

private static void
checkKeycodeArgument(int keycode)

private static void
checkNotDispatchThread()

private static void
checkValidRect(Rectangle rect)

public void
click(int
The button mask; a combination of one or more mouse button masks.
buttons)

A convenience method that simulates clicking a mouse button by calling mousePress, mouseRelease and waitForIdle.

public void
click()

A convenience method that clicks mouse button 1.

private synchronized BufferedImage[]
createCompatibleImage(Rectangle screenRect, boolean isHiDPI)

public synchronized MultiResolutionImage

Returns:

The captured image
createMultiResolutionScreenCapture(Rectangle
Rect to capture in screen coordinates
screenRect)

Creates an image containing pixels read from the screen.

public synchronized BufferedImage

Returns:

The captured image
createScreenCapture(Rectangle
Rect to capture in screen coordinates
screenRect)

Creates an image containing pixels read from the screen.

public void
delay(int
time to sleep in milliseconds
ms)

Sleeps for the specified time.

public synchronized int

Returns:

the delay duration in milliseconds
getAutoDelay()

Returns the number of milliseconds this Robot sleeps after generating an event.

public synchronized Color

Returns:

Color of the pixel
getPixelColor(int
X position of pixel
x, int
Y position of pixel
y)

Returns the color of a pixel at the given screen coordinates.

public void
glide(int
Destination point x coordinate
x, int
Destination point y coordinate
y)

A convenience method that moves the mouse in multiple steps from its current location to the destination coordinates.

public void
glide(int
Source point x coordinate
srcX, int
Source point y coordinate
srcY, int
Destination point x coordinate
dstX, int
Destination point y coordinate
dstY)

A convenience method that moves the mouse in multiple steps from source coordinates to the destination coordinates.

public void
glide(int
Source point x coordinate
srcX, int
Source point y coordinate
srcY, int
Destination point x coordinate
destX, int
Destination point y coordinate
destY, int
Preferred length of one step in pixels
stepLength, int
Delay between steps in milliseconds
stepDelay)

A convenience method that moves the mouse in multiple steps from source point to the destination point with a given stepLength and stepDelay.

private void
init(GraphicsDevice screen)

private static synchronized void
initLegalButtonMask()

public synchronized boolean

Returns:

Whether waitForIdle is automatically called
isAutoWaitForIdle()

Returns whether this Robot automatically invokes waitForIdle after generating an event.

public synchronized void
keyPress(int
Key to press (e.g. KeyEvent.VK_A)
keycode)

Presses a given key.

public synchronized void
keyRelease(int
Key to release (e.g. KeyEvent.VK_A)
keycode)

Releases a given key.

public synchronized void
mouseMove(int
X position
x, int
Y position
y)

Moves mouse pointer to given screen coordinates.

public synchronized void
mousePress(int
the Button mask; a combination of one or more mouse button masks.

It is allowed to use only a combination of valid values as a buttons parameter. A valid combination consists of InputEvent.BUTTON1_DOWN_MASK, InputEvent.BUTTON2_DOWN_MASK, InputEvent.BUTTON3_DOWN_MASK and values returned by the InputEvent.getMaskForButton(button) method. The valid combination also depends on a Toolkit.areExtraMouseButtonsEnabled() value as follows:

  • If support for extended mouse buttons is disabled by Java then it is allowed to use only the following standard button masks: InputEvent.BUTTON1_DOWN_MASK, InputEvent.BUTTON2_DOWN_MASK, InputEvent.BUTTON3_DOWN_MASK.
  • If support for extended mouse buttons is enabled by Java then it is allowed to use the standard button masks and masks for existing extended mouse buttons, if the mouse has more then three buttons. In that way, it is allowed to use the button masks corresponding to the buttons in the range from 1 to MouseInfo.getNumberOfButtons().
    It is recommended to use the InputEvent.getMaskForButton(button) method to obtain the mask for any mouse button by its number.

The following standard button masks are also accepted:

  • InputEvent.BUTTON1_MASK
  • InputEvent.BUTTON2_MASK
  • InputEvent.BUTTON3_MASK
However, it is recommended to use InputEvent.BUTTON1_DOWN_MASK, InputEvent.BUTTON2_DOWN_MASK, InputEvent.BUTTON3_DOWN_MASK instead. Either extended _DOWN_MASK or old _MASK values should be used, but both those models should not be mixed.
buttons)

Presses one or more mouse buttons.

public synchronized void
mouseRelease(int
the Button mask; a combination of one or more mouse button masks.

It is allowed to use only a combination of valid values as a buttons parameter. A valid combination consists of InputEvent.BUTTON1_DOWN_MASK, InputEvent.BUTTON2_DOWN_MASK, InputEvent.BUTTON3_DOWN_MASK and values returned by the InputEvent.getMaskForButton(button) method. The valid combination also depends on a Toolkit.areExtraMouseButtonsEnabled() value as follows:

  • If the support for extended mouse buttons is disabled by Java then it is allowed to use only the following standard button masks: InputEvent.BUTTON1_DOWN_MASK, InputEvent.BUTTON2_DOWN_MASK, InputEvent.BUTTON3_DOWN_MASK.
  • If the support for extended mouse buttons is enabled by Java then it is allowed to use the standard button masks and masks for existing extended mouse buttons, if the mouse has more then three buttons. In that way, it is allowed to use the button masks corresponding to the buttons in the range from 1 to MouseInfo.getNumberOfButtons().
    It is recommended to use the InputEvent.getMaskForButton(button) method to obtain the mask for any mouse button by its number.

The following standard button masks are also accepted:

  • InputEvent.BUTTON1_MASK
  • InputEvent.BUTTON2_MASK
  • InputEvent.BUTTON3_MASK
However, it is recommended to use InputEvent.BUTTON1_DOWN_MASK, InputEvent.BUTTON2_DOWN_MASK, InputEvent.BUTTON3_DOWN_MASK instead. Either extended _DOWN_MASK or old _MASK values should be used, but both those models should not be mixed.
buttons)

Releases one or more mouse buttons.

public synchronized void
mouseWheel(int
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.
wheelAmt)

Rotates the scroll wheel on wheel-equipped mice.

public synchronized void
setAutoDelay(int
the delay duration in milliseconds
ms)

Sets the number of milliseconds this Robot sleeps after generating an event.

public synchronized void
setAutoWaitForIdle(boolean
Whether waitForIdle is automatically invoked
isOn)

Sets whether this Robot automatically invokes waitForIdle after generating an event.

public synchronized String

Returns:

the string representation.
toString()

Overrides java.lang.Object.toString.

Returns a string representation of this Robot.

public synchronized void
type(int
Key to type (e.g. KeyEvent.VK_A)
keycode)

A convenience method that simulates typing a key by calling keyPress and keyRelease.

public synchronized void
type(char
Character to be typed (e.g. 'a')
c)

A convenience method that simulates typing a char by calling keyPress and keyRelease.

public synchronized void
waitForIdle()

Waits until all events currently on the event queue have been processed.

public void
waitForIdle(int
Additional delay length in milliseconds to wait until thread sync been completed
delayValue)

A convenience method that calls waitForIdle then waits an additional specified delayValue time in milliseconds.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

autoDelayback to summary
private int autoDelay
DEFAULT_DELAYback to summary
public static final int DEFAULT_DELAY

Default delay in milliseconds for mouse glide, type, and click.

DEFAULT_STEP_LENGTHback to summary
public static final int DEFAULT_STEP_LENGTH

Default pixel step-length for mouse glide.

isAutoWaitForIdleback to summary
private boolean isAutoWaitForIdle
MAX_DELAYback to summary
private static final int MAX_DELAY
peerback to summary
private RobotPeer peer
screenCapCMback to summary
private DirectColorModel screenCapCM

Constructor Detail

Robotback to summary
public Robot() throws AWTException

Constructs a Robot object in the coordinate system of the primary screen.

Exceptions
AWTException:
if the platform configuration does not allow low-level input control. This exception is always thrown when GraphicsEnvironment.isHeadless() returns true
See Also
java.awt.GraphicsEnvironment#isHeadless
Robotback to summary
public Robot(GraphicsDevice screen) throws AWTException

Creates a Robot for the given screen device. Coordinates passed to Robot method calls like mouseMove, getPixelColor 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

If screen devices are reconfigured such that the coordinate system is affected, the behavior of existing Robot objects is undefined.

Parameters
screen:GraphicsDevice

A screen GraphicsDevice indicating the coordinate system the Robot will operate in.

Exceptions
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.
See Also
java.awt.GraphicsEnvironment#isHeadless, GraphicsDevice

Method Detail

afterEventback to summary
private void afterEvent()
autoDelayback to summary
private void autoDelay()
autoWaitForIdleback to summary
private void autoWaitForIdle()
checkButtonsArgumentback to summary
private static void checkButtonsArgument(int buttons)
checkDelayArgumentback to summary
private static void checkDelayArgument(int ms)
checkHeadlessback to summary
private static void checkHeadless() throws AWTException

Check for headless state and throw AWTException if headless.

checkIsScreenDeviceback to summary
private static void checkIsScreenDevice(GraphicsDevice device)
checkKeycodeArgumentback to summary
private static void checkKeycodeArgument(int keycode)
checkNotDispatchThreadback to summary
private static void checkNotDispatchThread()
checkValidRectback to summary
private static void checkValidRect(Rectangle rect)
clickback to summary
public void click(int buttons)

A convenience method that simulates clicking a mouse button by calling mousePress, mouseRelease and waitForIdle. Invokes waitForIdle with a default delay of 20 milliseconds after mousePress and mouseRelease calls. For specifics on valid inputs see java.awt.Robot#mousePress(int).

Parameters
buttons:int

The button mask; a combination of one or more mouse button masks.

Exceptions
IllegalArgumentException:
  • if the buttons mask contains the mask for extra mouse button and support for extended mouse buttons is disabled by Java
  • if the buttons mask contains the mask for extra mouse button that does not exist on the mouse and support for extended mouse buttons is enabled by Java
IllegalThreadStateException:
if called on the AWT event dispatching thread
Since
26
See Also
DEFAULT_DELAY, mousePress(int), mouseRelease(int), InputEvent#getMaskForButton(int), Toolkit#areExtraMouseButtonsEnabled(), java.awt.event.MouseEvent
clickback to summary
public void click()

A convenience method that clicks mouse button 1.

Exceptions
IllegalThreadStateException:
if called on the AWT event dispatching thread
Since
26
See Also
click(int)
createCompatibleImageback to summary
private synchronized BufferedImage[] createCompatibleImage(Rectangle screenRect, boolean isHiDPI)
createMultiResolutionScreenCaptureback to summary
public synchronized MultiResolutionImage createMultiResolutionScreenCapture(Rectangle screenRect)

Creates an image containing pixels read from the screen. This method can be used in case there is a scaling transform from user space to screen (device) space. Typically this means that the display is a high resolution screen, although strictly it means any case in which there is such a transform. Returns a java.awt.image.MultiResolutionImage.

For a non-scaled display, the MultiResolutionImage will have one image variant:

  • Base Image with user specified size.

For a high resolution display where there is a scaling transform, the MultiResolutionImage will have two image variants:

  • Base Image with user specified size. This is scaled from the screen.
  • Native device resolution image with device size pixels.

Example: 

Image nativeResImage;
     MultiResolutionImage mrImage = robot.createMultiResolutionScreenCapture(frame.getBounds());
     List<Image> resolutionVariants = mrImage.getResolutionVariants();
     if (resolutionVariants.size() > 1) {
         nativeResImage = resolutionVariants.get(1);
     } else {
         nativeResImage = resolutionVariants.get(0);
     }

API Note

It is recommended to avoid calling this method on the AWT Event Dispatch Thread since screen capture may be a lengthy operation, particularly if acquiring permissions is needed and involves user interaction.

Parameters
screenRect:Rectangle

Rect to capture in screen coordinates

Returns:MultiResolutionImage

The captured image

Exceptions
IllegalArgumentException:
if screenRect width and height are not greater than zero
SecurityException:
if access to the screen is denied by the desktop environment
Since
9
createScreenCaptureback to summary
public synchronized BufferedImage createScreenCapture(Rectangle screenRect)

Creates an image containing pixels read from the screen.

If the desktop environment requires that permissions be granted to capture screen content, and the required permissions are not granted, then a SecurityException may be thrown, or the contents of the returned BufferedImage are undefined.

API Note

It is recommended to avoid calling this method on the AWT Event Dispatch Thread since screen capture may be a lengthy operation, particularly if acquiring permissions is needed and involves user interaction.

Parameters
screenRect:Rectangle

Rect to capture in screen coordinates

Returns:BufferedImage

The captured image

Exceptions
IllegalArgumentException:
if screenRect width and height are not greater than zero
SecurityException:
if access to the screen is denied by the desktop environment
delayback to summary
public void delay(int ms)

Sleeps for the specified time.

If the invoking thread is interrupted while waiting, then it will return immediately with the interrupted status set. If the interrupted status is already set, this method returns immediately with the interrupted status set.

API Note

It is recommended to avoid calling this method on the AWT Event Dispatch Thread since delay may be a lengthy operation.

Parameters
ms:int

time to sleep in milliseconds

Exceptions
IllegalArgumentException:
if ms is not between 0 and 60,000 milliseconds inclusive
getAutoDelayback to summary
public synchronized int getAutoDelay()

Returns the number of milliseconds this Robot sleeps after generating an event.

Returns:int

the delay duration in milliseconds

getPixelColorback to summary
public synchronized Color getPixelColor(int x, int y)

Returns the color of a pixel at the given screen coordinates.

If the desktop environment requires that permissions be granted to capture screen content, and the required permissions are not granted, then a SecurityException may be thrown, or the content of the returned Color is undefined.

API Note

It is recommended to avoid calling this method on the AWT Event Dispatch Thread since screen capture may be a lengthy operation, particularly if acquiring permissions is needed and involves user interaction.

Parameters
x:int

X position of pixel

y:int

Y position of pixel

Returns:Color

Color of the pixel

Exceptions
SecurityException:
if access to the screen is denied by the desktop environment
glideback to summary
public void glide(int x, int y)

A convenience method that moves the mouse in multiple steps from its current location to the destination coordinates.

Implementation Specification

Invokes mouseMove with a step-length of 2 and a step-delay of 20.

Parameters
x:int

Destination point x coordinate

y:int

Destination point y coordinate

Exceptions
IllegalThreadStateException:
if called on the AWT event dispatching thread and isAutoWaitForIdle would return true
Since
26
See Also
DEFAULT_STEP_LENGTH, DEFAULT_DELAY, glide(int, int, int, int, int, int)
glideback to summary
public void glide(int srcX, int srcY, int dstX, int dstY)

A convenience method that moves the mouse in multiple steps from source coordinates to the destination coordinates.

Implementation Specification

Invokes mouseMove with a step-length of 2 and a step-delay of 20.

Parameters
srcX:int

Source point x coordinate

srcY:int

Source point y coordinate

dstX:int

Destination point x coordinate

dstY:int

Destination point y coordinate

Exceptions
IllegalThreadStateException:
if called on the AWT event dispatching thread and isAutoWaitForIdle would return true
Since
26
See Also
DEFAULT_STEP_LENGTH, DEFAULT_DELAY, glide(int, int, int, int, int, int)
glideback to summary
public void glide(int srcX, int srcY, int destX, int destY, int stepLength, int stepDelay)

A convenience method that moves the mouse in multiple steps from source point to the destination point with a given stepLength and stepDelay.

Parameters
srcX:int

Source point x coordinate

srcY:int

Source point y coordinate

destX:int

Destination point x coordinate

destY:int

Destination point y coordinate

stepLength:int

Preferred length of one step in pixels

stepDelay:int

Delay between steps in milliseconds

Exceptions
IllegalArgumentException:
  • if stepLength is not greater than zero
  • if stepDelay is not between 0 and 60,000 milliseconds inclusive
IllegalThreadStateException:
if called on the AWT event dispatching thread and isAutoWaitForIdle would return true
Since
26
See Also
mouseMove(int, int), delay(int)
initback to summary
private void init(GraphicsDevice screen) throws AWTException
initLegalButtonMaskback to summary
private static synchronized void initLegalButtonMask()
Annotations
@SuppressWarnings:deprecation
isAutoWaitForIdleback to summary
public synchronized boolean isAutoWaitForIdle()

Returns whether this Robot automatically invokes waitForIdle after generating an event.

Returns:boolean

Whether waitForIdle is automatically called

keyPressback to summary
public synchronized 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:int

Key to press (e.g. KeyEvent.VK_A)

Exceptions
IllegalArgumentException:
if keycode is not a valid key
IllegalThreadStateException:
if called on the AWT event dispatching thread and isAutoWaitForIdle would return true
See Also
keyRelease(int), java.awt.event.KeyEvent
keyReleaseback to summary
public synchronized 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:int

Key to release (e.g. KeyEvent.VK_A)

Exceptions
IllegalArgumentException:
if keycode is not a valid key
IllegalThreadStateException:
if called on the AWT event dispatching thread and isAutoWaitForIdle would return true
See Also
keyPress(int), java.awt.event.KeyEvent
mouseMoveback to summary
public synchronized void mouseMove(int x, int y)

Moves mouse pointer to given screen coordinates.

The mouse pointer may not visually move on some platforms, while the subsequent mousePress and mouseRelease can be delivered to the correct location

Parameters
x:int

X position

y:int

Y position

Exceptions
IllegalThreadStateException:
if called on the AWT event dispatching thread and isAutoWaitForIdle would return true
mousePressback to summary
public synchronized void mousePress(int buttons)

Presses one or more mouse buttons. The mouse buttons should be released using the mouseRelease(int) method.

Parameters
buttons:int

the Button mask; a combination of one or more mouse button masks.

It is allowed to use only a combination of valid values as a buttons parameter. A valid combination consists of InputEvent.BUTTON1_DOWN_MASK, InputEvent.BUTTON2_DOWN_MASK, InputEvent.BUTTON3_DOWN_MASK and values returned by the InputEvent.getMaskForButton(button) method. The valid combination also depends on a Toolkit.areExtraMouseButtonsEnabled() value as follows:

  • If support for extended mouse buttons is disabled by Java then it is allowed to use only the following standard button masks: InputEvent.BUTTON1_DOWN_MASK, InputEvent.BUTTON2_DOWN_MASK, InputEvent.BUTTON3_DOWN_MASK.
  • If support for extended mouse buttons is enabled by Java then it is allowed to use the standard button masks and masks for existing extended mouse buttons, if the mouse has more then three buttons. In that way, it is allowed to use the button masks corresponding to the buttons in the range from 1 to MouseInfo.getNumberOfButtons().
    It is recommended to use the InputEvent.getMaskForButton(button) method to obtain the mask for any mouse button by its number.

The following standard button masks are also accepted:

  • InputEvent.BUTTON1_MASK
  • InputEvent.BUTTON2_MASK
  • InputEvent.BUTTON3_MASK
However, it is recommended to use InputEvent.BUTTON1_DOWN_MASK, InputEvent.BUTTON2_DOWN_MASK, InputEvent.BUTTON3_DOWN_MASK instead. Either extended _DOWN_MASK or old _MASK values should be used, but both those models should not be mixed.
Exceptions
IllegalArgumentException:
  • if the buttons mask contains the mask for extra mouse button and support for extended mouse buttons is disabled by Java
  • if the buttons mask contains the mask for extra mouse button that does not exist on the mouse and support for extended mouse buttons is enabled by Java
IllegalThreadStateException:
if called on the AWT event dispatching thread and isAutoWaitForIdle would return true
See Also
mouseRelease(int), InputEvent#getMaskForButton(int), Toolkit#areExtraMouseButtonsEnabled(), java.awt.MouseInfo#getNumberOfButtons(), java.awt.event.MouseEvent
mouseReleaseback to summary
public synchronized void mouseRelease(int buttons)

Releases one or more mouse buttons.

Parameters
buttons:int

the Button mask; a combination of one or more mouse button masks.

It is allowed to use only a combination of valid values as a buttons parameter. A valid combination consists of InputEvent.BUTTON1_DOWN_MASK, InputEvent.BUTTON2_DOWN_MASK, InputEvent.BUTTON3_DOWN_MASK and values returned by the InputEvent.getMaskForButton(button) method. The valid combination also depends on a Toolkit.areExtraMouseButtonsEnabled() value as follows:

  • If the support for extended mouse buttons is disabled by Java then it is allowed to use only the following standard button masks: InputEvent.BUTTON1_DOWN_MASK, InputEvent.BUTTON2_DOWN_MASK, InputEvent.BUTTON3_DOWN_MASK.
  • If the support for extended mouse buttons is enabled by Java then it is allowed to use the standard button masks and masks for existing extended mouse buttons, if the mouse has more then three buttons. In that way, it is allowed to use the button masks corresponding to the buttons in the range from 1 to MouseInfo.getNumberOfButtons().
    It is recommended to use the InputEvent.getMaskForButton(button) method to obtain the mask for any mouse button by its number.

The following standard button masks are also accepted:

  • InputEvent.BUTTON1_MASK
  • InputEvent.BUTTON2_MASK
  • InputEvent.BUTTON3_MASK
However, it is recommended to use InputEvent.BUTTON1_DOWN_MASK, InputEvent.BUTTON2_DOWN_MASK, InputEvent.BUTTON3_DOWN_MASK instead. Either extended _DOWN_MASK or old _MASK values should be used, but both those models should not be mixed.
Exceptions
IllegalArgumentException:
  • if the buttons mask contains the mask for extra mouse button and support for extended mouse buttons is disabled by Java
  • if the buttons mask contains the mask for extra mouse button that does not exist on the mouse and support for extended mouse buttons is enabled by Java
IllegalThreadStateException:
if called on the AWT event dispatching thread and isAutoWaitForIdle would return true
See Also
mousePress(int), InputEvent#getMaskForButton(int), Toolkit#areExtraMouseButtonsEnabled(), java.awt.MouseInfo#getNumberOfButtons(), java.awt.event.MouseEvent
mouseWheelback to summary
public synchronized void mouseWheel(int wheelAmt)

Rotates the scroll wheel on wheel-equipped mice.

Parameters
wheelAmt:int

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.

Exceptions
IllegalThreadStateException:
if called on the AWT event dispatching thread and isAutoWaitForIdle would return true
Since
1.4
setAutoDelayback to summary
public synchronized void setAutoDelay(int ms)

Sets the number of milliseconds this Robot sleeps after generating an event.

Parameters
ms:int

the delay duration in milliseconds

Exceptions
IllegalArgumentException:
If ms is not between 0 and 60,000 milliseconds inclusive
setAutoWaitForIdleback to summary
public synchronized void setAutoWaitForIdle(boolean isOn)

Sets whether this Robot automatically invokes waitForIdle after generating an event.

API Note

Setting this to true means you cannot call mouse and key-controlling events on the AWT Event Dispatching Thread

Parameters
isOn:boolean

Whether waitForIdle is automatically invoked

toStringback to summary
public synchronized String toString()

Overrides java.lang.Object.toString.

Returns a string representation of this Robot.

Returns:String

the string representation.

Annotations
@Override
typeback to summary
public synchronized void type(int keycode)

A convenience method that simulates typing a key by calling keyPress and keyRelease. Invokes waitForIdle with a delay of 20 milliseconds after keyPress and keyRelease calls.

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:int

Key to type (e.g. KeyEvent.VK_A)

Exceptions
IllegalArgumentException:
if keycode is not a valid key
IllegalThreadStateException:
if called on the AWT event dispatching thread
Since
26
See Also
DEFAULT_DELAY, keyPress(int), keyRelease(int), java.awt.event.KeyEvent
typeback to summary
public synchronized void type(char c)

A convenience method that simulates typing a char by calling keyPress and keyRelease. Gets the ExtendedKeyCode for the char and calls type(int keycode).

Parameters
c:char

Character to be typed (e.g. 'a')

Exceptions
IllegalArgumentException:
if keycode is not a valid key
IllegalThreadStateException:
if called on the AWT event dispatching thread
Since
26
See Also
type(int), keyPress(int), keyRelease(int), java.awt.event.KeyEvent
waitForIdleback to summary
public synchronized void waitForIdle()

Waits until all events currently on the event queue have been processed.

Exceptions
IllegalThreadStateException:
if called on the AWT event dispatching thread
waitForIdleback to summary
public void waitForIdle(int delayValue)

A convenience method that calls waitForIdle then waits an additional specified delayValue time in milliseconds.

Parameters
delayValue:int

Additional delay length in milliseconds to wait until thread sync been completed

Exceptions
IllegalThreadStateException:
if called on the AWT event dispatching thread
IllegalArgumentException:
if delayValue is not between 0 and 60,000 milliseconds inclusive
Since
26