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 declared in 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.