Robot (JavaFX 17)

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

    All Methods Instance Methods Concrete Methods
    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 declared in class java.lang.Object

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

- - ### Constructor Detail

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

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