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 MouseButtons.
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 MouseButtons.
void	mouseRelease(MouseButton... buttons)	Releases the specified MouseButtons.
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 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.