Module javafx.graphics
Package javafx.scene.robot

# Class Robot

java.lang.Object
javafx.scene.robot.Robot

public final class Robot extends Object
A `Robot` is used for simulating user interaction such as typing keys on the keyboard and using the mouse as well as capturing graphical information without requiring a `Scene` instance. Robot objects must be constructed and used on the JavaFX Application Thread.

Since:
  11

## Constructor Summary

Constructors
Constructor
Description
`Robot()`
Constructs a new `Robot` that can be used for simulating user interactions.

## Method Summary

Modifier and Type
Method
Description
`Point2D`
`getMousePosition()`
Returns the current mouse (x,y) screen coordinates as a `Point2D`.
`double`
`getMouseX()`
Returns the current mouse `x` position in screen coordinates.
`double`
`getMouseY()`
Returns the current mouse `y` position in screen coordinates.
`Color`
`getPixelColor(double x, double y)`
Returns the `Color` of the pixel at the screen coordinates relative to the primary screen specified by `location`.
`Color`
`getPixelColor(Point2D location)`
Returns the `Color` of the pixel at the screen coordinates relative to the primary screen specified by `location`.
`WritableImage`
`getScreenCapture(WritableImage image, double x, double y, double width, double height)`
Returns a `WritableImage` containing the specified rectangular area relative to the primary screen.
`WritableImage`
`getScreenCapture(WritableImage image, double x, double y, double width, double height, boolean scaleToFit)`
Returns a `WritableImage` containing the specified rectangular area relative to the primary screen.
`WritableImage`
`getScreenCapture(WritableImage image, Rectangle2D region)`
Returns a `WritableImage` containing the specified rectangular area relative to the primary screen.
`WritableImage`
`getScreenCapture(WritableImage image, Rectangle2D region, boolean scaleToFit)`
Returns a `WritableImage` containing the specified rectangular area relative to the primary screen.
`void`
`keyPress(KeyCode keyCode)`
Presses the specified `KeyCode` key.
`void`
`keyRelease(KeyCode keyCode)`
Releases the specified `KeyCode` key.
`void`
`keyType(KeyCode keyCode)`
Types the specified `KeyCode` key.
`void`
`mouseClick(MouseButton... buttons)`
Clicks the specified `MouseButton`s.
`void`
`mouseMove(double x, double y)`
Moves the mouse to the specified (x,y) screen coordinates relative to the primary screen.
`final void`
`mouseMove(Point2D location)`
Moves the mouse to the (x,y) screen coordinates, relative to the primary screen, specified by the given `location`.
`void`
`mousePress(MouseButton... buttons)`
Presses the specified `MouseButton`s.
`void`
`mouseRelease(MouseButton... buttons)`
Releases the specified `MouseButton`s.
`void`
`mouseWheel(int wheelAmt)`
Scrolls the mouse wheel by the specified amount of wheel clicks.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### Robot

public Robot()
Constructs a new `Robot` that can be used for simulating user interactions. If a security manager is present, the application must have the `FXPermission` `"createRobot"` permission in order to construct a `Robot` object.

Throws:
  `IllegalStateException` - if this object is constructed on a thread other than the JavaFX Application Thread.
  `SecurityException` - if a security manager exists and the application does not have the `FXPermission` `"createRobot"` permission.

## Method Details

### keyPress

public void keyPress(KeyCode keyCode)
Presses the specified `KeyCode` key.

Parameters:
  `keyCode` - the key to press
Throws:
  `IllegalStateException` - if this method is called on a thread other than the JavaFX Application Thread.
  `NullPointerException` - if keyCode is null.

### keyRelease

public void keyRelease(KeyCode keyCode)
Releases the specified `KeyCode` key.

Parameters:
  `keyCode` - the key to release
Throws:
  `IllegalStateException` - if this method is called on a thread other than the JavaFX Application Thread.
  `NullPointerException` - if keyCode is null.

### keyType

public void keyType(KeyCode keyCode)
Types the specified `KeyCode` key.

Implementation Requirements:
  This is a convenience method that is equivalent to calling `keyPress(KeyCode)` followed by `keyRelease(KeyCode)`.
Parameters:
  `keyCode` - the key to type
Throws:
  `IllegalStateException` - if this method is called on a thread other than the JavaFX Application Thread.
  `NullPointerException` - if keyCode is null.

### getMouseX

public double getMouseX()
Returns the current mouse `x` position in screen coordinates.

Returns:
  the current mouse `x` position
Throws:
  `IllegalStateException` - if this method is called on a thread other than the JavaFX Application Thread.

### getMouseY

public double getMouseY()
Returns the current mouse `y` position in screen coordinates.

Returns:
  the current mouse `y` position
Throws:
  `IllegalStateException` - if this method is called on a thread other than the JavaFX Application Thread.

### getMousePosition

public Point2D getMousePosition()
Returns the current mouse (x,y) screen coordinates as a `Point2D`.

Returns:
  the current mouse (x,y) screen coordinates
Throws:
  `IllegalStateException` - if this method is called on a thread other than the JavaFX Application Thread.

### mouseMove

public void mouseMove(double x, double y)
Moves the mouse to the specified (x,y) screen coordinates relative to the primary screen.

Parameters:
  `x` - screen coordinate x to move the mouse to
  `y` - screen coordinate y to move the mouse to
Throws:
  `IllegalStateException` - if this method is called on a thread other than the JavaFX Application Thread.

### mouseMove

public final void mouseMove(Point2D location)
Moves the mouse to the (x,y) screen coordinates, relative to the primary screen, specified by the given `location`.

Parameters:
  `location` - the (x,y) coordinates to move the mouse to
Throws:
  `IllegalStateException` - if this method is called on a thread other than the JavaFX Application Thread.
  `NullPointerException` - if location is null.

### mousePress

public void mousePress(MouseButton... buttons)
Presses the specified `MouseButton`s.

Parameters:
  `buttons` - the mouse buttons to press
Throws:
  `IllegalStateException` - if this method is called on a thread other than the JavaFX Application Thread.
  `NullPointerException` - if buttons is null.

### mouseRelease

public void mouseRelease(MouseButton... buttons)
Releases the specified `MouseButton`s.

Parameters:
  `buttons` - the mouse buttons to release
Throws:
  `IllegalStateException` - if this method is called on a thread other than the JavaFX Application Thread.
  `NullPointerException` - if buttons is null.

### mouseClick

public void mouseClick(MouseButton... buttons)
Clicks the specified `MouseButton`s.

Implementation Requirements:
  This is a convenience method that is equivalent to calling `mousePress(MouseButton...)` followed by `mouseRelease(MouseButton...)`.
Parameters:
  `buttons` - the mouse buttons to click
Throws:
  `IllegalStateException` - if this method is called on a thread other than the JavaFX Application Thread.
  `NullPointerException` - if buttons is null.

### mouseWheel

public void mouseWheel(int wheelAmt)
Scrolls the mouse wheel by the specified amount of wheel clicks. A positive `wheelAmt` scrolls the wheel towards the user (down) whereas negative amounts scrolls the wheel away from the user (up).

Parameters:
  `wheelAmt` - the (signed) amount of clicks to scroll the wheel
Throws:
  `IllegalStateException` - if this method is called on a thread other than the JavaFX Application Thread.

### getPixelColor

public Color getPixelColor(double x, double y)
Returns the `Color` of the pixel at the screen coordinates relative to the primary screen specified by `location`. Regardless of the scale of the screen (`Screen.getOutputScaleX()`, `Screen.getOutputScaleY()`), this method only samples a single pixel. For example, on a HiDPI screen with output scale 2, the screen unit at the point (x,y) may have 4 pixels. In this case the color returned is the color of the top, left pixel. Color values are not averaged when a screen unit is made up of more than one pixel.

Parameters:
  `x` - the x coordinate to get the pixel color from
  `y` - the y coordinate to get the pixel color from
Returns:
  the pixel color at the specified screen coordinates
Throws:
  `IllegalStateException` - if this method is called on a thread other than the JavaFX Application Thread.

### getPixelColor

public Color getPixelColor(Point2D location)
Returns the `Color` of the pixel at the screen coordinates relative to the primary screen specified by `location`. Regardless of the scale of the screen (`Screen.getOutputScaleX()`, `Screen.getOutputScaleY()`), this method only samples a single pixel. For example, on a HiDPI screen with output scale 2, the screen unit at the point (x,y) may have 4 pixels. In this case the color returned is the color of the top, left pixel. Color values are not averaged when a screen unit is made up of more than one pixel.

Parameters:
  `location` - the (x,y) coordinates to get the pixel color from
Returns:
  the pixel color at the specified screen coordinates
Throws:
  `NullPointerException` - if the given `location` is null
  `IllegalStateException` - if this method is called on a thread other than the JavaFX Application Thread.

### getScreenCapture

public WritableImage getScreenCapture(WritableImage image, double x, double y, double width, double height, boolean scaleToFit)
Returns a `WritableImage` containing the specified rectangular area relative to the primary screen. If the given `image` is null, or if the given `image` is not the required size, a new `WritableImage` will be created and returned. Otherwise, the given `image` is re-used.

If the `scaleToFit` argument is false, the returned `Image` object dimensions may differ from the requested `width` and `height` depending on how many physical pixels the area occupies on the screen. For example, in HiDPI mode on the Mac (aka Retina display) the pixels are doubled, and thus a screen capture of an area of size (10x10) pixels will result in an `Image` with dimensions (20x20). Calling code should use the returned images's `Image.getWidth()` and `Image.getHeight()` methods to determine the actual image size.

If `scaleToFit` is true, the returned `Image` is of the requested size. Note that in this case the image will be scaled in order to fit to the requested dimensions if necessary, such as when running on a HiDPI display.

Parameters:
  `image` - either null or a `WritableImage` that will be used to place the screen capture in
  `x` - the starting x-position of the rectangular area to capture
  `y` - the starting y-position of the rectangular area to capture
  `width` - the width of the rectangular area to capture
  `height` - the height of the rectangular area to capture
  `scaleToFit` - If true, the returned `Image` will be scaled to fit the request dimensions (if necessary). Otherwise, the size of the returned image will depend on the output scale (DPI) of the primary screen.
Returns:
  the screen capture of the specified `region` as a `WritableImage`
Throws:
  `IllegalStateException` - if this method is called on a thread other than the JavaFX Application Thread.

### getScreenCapture

public WritableImage getScreenCapture(WritableImage image, double x, double y, double width, double height)
Returns a `WritableImage` containing the specified rectangular area relative to the primary screen. If the given `image` is null, or if the given `image` is not the required size, a new `WritableImage` will be created and returned. Otherwise, the given `image` is re-used.

Implementation Requirements:
  This method is equivalent to calling `getScreenCapture(x, y, width, height, true)`, that is, this method scales the image to fit the requested size.
Parameters:
  `image` - either null or a `WritableImage` that will be used to place the screen capture in
  `x` - the starting x-position of the rectangular area to capture
  `y` - the starting y-position of the rectangular area to capture
  `width` - the width of the rectangular area to capture
  `height` - the height of the rectangular area to capture
Returns:
  the screen capture of the specified `region` as a `WritableImage`
Throws:
  `IllegalStateException` - if this method is called on a thread other than the JavaFX Application Thread.

### getScreenCapture

public WritableImage getScreenCapture(WritableImage image, Rectangle2D region)
Returns a `WritableImage` containing the specified rectangular area relative to the primary screen. If the given `image` is null, or if the given `image` is not the required size, a new `WritableImage` will be created and returned. Otherwise, the given `image` is re-used.

Implementation Requirements:
  This method is equivalent to calling `getScreenCapture(image, region, true)`, that is, this method scales the image to fit the requested size.
Parameters:
  `image` - either null or a `WritableImage` that will be used to place the screen capture in
  `region` - the rectangular area of the screen to capture
Returns:
  the screen capture of the specified `region` as a `WritableImage`
Throws:
  `IllegalStateException` - if this method is called on a thread other than the JavaFX Application Thread.
  `NullPointerException` - if region is null.

### getScreenCapture

public WritableImage getScreenCapture(WritableImage image, Rectangle2D region, boolean scaleToFit)
Returns a `WritableImage` containing the specified rectangular area relative to the primary screen. If the given `image` is null, or if the given `image` is not the required size, a new `WritableImage` will be created and returned. Otherwise, the given `image` is re-used.

If the `scaleToFit` argument is false, the returned `Image` object dimensions may differ from the requested `width` and `height` depending on how many physical pixels the area occupies on the screen. For example, in HiDPI mode on the Mac (aka Retina display) the pixels are doubled, and thus a screen capture of an area of size (10x10) pixels will result in an `Image` with dimensions (20x20). Calling code should use the returned images's `Image.getWidth()` and `Image.getHeight()` methods to determine the actual image size.

If `scaleToFit` is true, the returned `Image` is of the requested size. Note that in this case the image will be scaled in order to fit to the requested dimensions if necessary, such as when running on a HiDPI display.

Parameters:
  `image` - either null or a `WritableImage` that will be used to place the screen capture in
  `region` - the rectangular area of the screen to capture
  `scaleToFit` - if true, the returned `Image` will be scaled to fit the request dimensions (if necessary). Otherwise, the size of the returned image will depend on the output scale (DPI) of the primary screen.
Returns:
  the screen capture of the specified `region` as a `WritableImage`
Throws:
  `IllegalStateException` - if this method is called on a thread other than the JavaFX Application Thread.
  `NullPointerException` - if region is null.