Module javafx.graphics
Package javafx.scene.robot

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

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

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