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