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