com.tplan.robot.util

Class ScreenUtils

java.lang.Object

com.tplan.robot.util.ScreenUtils

All Implemented Interfaces:

ImageObserver, Comparator<com.tplan.robot.util.ScreenUtils.ScreenEntry>

public class ScreenUtils
extends Object
implements ImageObserver, Comparator<com.tplan.robot.util.ScreenUtils.ScreenEntry>

Screen and screen image methods.

Since:

4.1

T-Plan Robot Enterprise, (C) 2009-2022 T-Plan Limited. All rights reserved.

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	debug

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Method Summary

Modifier and Type	Method and Description
static void	addChangeListener(ChangeListener l) Add a change listener to be notified of the screen layout changes.
int	compare(com.tplan.robot.util.ScreenUtils.ScreenEntry o1, com.tplan.robot.util.ScreenUtils.ScreenEntry o2)
static BufferedImage	createCompatibleCopy(Image image, boolean copyPixels) Create a copy of the image compatible with the Robot's image comparison and display requirements.
static Robot	getDefaultRobot() Get the default java.awt.Robot instance associated with the primary display.
static Rectangle	getDisplayRectForPoint(int screenX, int screenY) Get rectangle of a display containing the specified coordinates.
static Rectangle	getDisplayRectForRect(Rectangle rect) Get rectangle of a display containing the specified rectangle or its largest part if it spans across multiple displays.
static Color	getEmptySpaceColor() Get the transparent color used to pad empty areas of a virtual screen image returned by getScreenImage().
static Robot	getRobot(Point source, Point converted) Get the java.awt.Robot instance associated with the display at the given coordinates.
static int	getScreenCount()
static GraphicsDevice	getScreenDevice(int screen)
static BufferedImage	getScreenImage() Get the virtual screen image of the local OS.
static BufferedImage	getScreenImage(int screenNo)
static BufferedImage	getScreenImage(Integer screenNo, Rectangle bounds, boolean boundsAreInRobotCoordSystem) Get a screen shot of the specified area.
static Rectangle	getScreenRect() Get the screen rectangle in the local OS coordinates.
static Rectangle	getScreenRect(int screenNo)
static int	getScreenRows()
static List<Integer>	getScreensForRect(Rectangle rect)
static GraphicsDevice	getTopLeftScreen(Rectangle r) Get the top left graphics device.
boolean	imageUpdate(Image img, int infoflags, int x, int y, int width, int height) Implementation of the ImageObserver interface allowing the class to act as a dummy image observer when performing buffered image operations.
static boolean	isFullScreenCaptureSupported() Find out if capture on the live screen is supported on the local environment.
static boolean	isScaled() Find out if there's at least one scaled display.
static boolean	isScaled(int screenNo) Find out if the specified display is scaled.
static void	removeChangeListener(ChangeListener l) Remove a change listener.
static boolean	setFullScreenWindow(Window w) Set the full screen window.
static int	toRobotX(int screenX) Convert a local OS screen X-coordinate to the one compatible with the Robot's coordinate system.
static int	toRobotY(int screenY) Convert a local OS screen Y-coordinate to the one compatible with the Robot's coordinate system.
static int	toScreenX(int robotX) Convert a Robot screen X-coordinate to the one compatible with the local OS screen coordinate system.
static int	toScreenY(int robotY) Convert a Robot screen Y-coordinate to the one compatible with the local OS screen coordinate system.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.util.Comparator

comparing, comparing, comparingDouble, comparingInt, comparingLong, equals, naturalOrder, nullsFirst, nullsLast, reversed, reverseOrder, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong

Field Detail

debug

public static final boolean debug

Method Detail

getEmptySpaceColor

public static Color getEmptySpaceColor()

Get the transparent color used to pad empty areas of a virtual screen image returned by getScreenImage().

Returns:

the transparent fill color.

getDefaultRobot

public static Robot getDefaultRobot()

Get the default java.awt.Robot instance associated with the primary display.

Returns:

the default Robot instance.

getRobot

public static Robot getRobot(Point source,
                             Point converted)

Get the java.awt.Robot instance associated with the display at the given coordinates.

Parameters:

source - coordinates used to identify the target screen.

converted - when not null it will be populated with the coordinates converted to the target java.awt.Robot coordinates.

Returns:

the java.awt.Robot instance for the display at the specified coordinates.

getScreenCount

public static int getScreenCount()

getScreenRows

public static int getScreenRows()

getScreenDevice

public static GraphicsDevice getScreenDevice(int screen)

getScreenImage

public static BufferedImage getScreenImage(int screenNo)

isScaled

public static boolean isScaled()

Find out if there's at least one scaled display.

Returns:

true if desktop scaling is on for at least one display or false otherwise.

Since:

4.4.4

isScaled

public static boolean isScaled(int screenNo)

Find out if the specified display is scaled.

Parameters:

screenNo - the display number.

Returns:

true if the desktop scaling is on for the specified display or false otherwise.

Since:

4.4.4

getScreenImage

public static BufferedImage getScreenImage()

Get the virtual screen image of the local OS. If the system has just a single display it will be a classic screen shot. If there are multiple displays the method will return a large image with all screens organized in the logical order. Empty spaces resulting from joining of displays of different resolutions will be padded with a transparent color returned by the getEmptySpaceColor() method.

Returns:

multi display aware screen shot of the local desktop.

getScreenImage

public static BufferedImage getScreenImage(Integer screenNo,
                                           Rectangle bounds,
                                           boolean boundsAreInRobotCoordSystem)

Get a screen shot of the specified area.

Parameters:

screenNo - the screen number or null or a number lower than 1 to use full screen consisting of multiple monitors.

bounds - rectangular part of the screen to capture . It must be in the Robot coordinates which means that it may not contain negative X,Y coordinates. See the toRobotX(int) method for an explanation of the difference between the local OS and Robot coordinate systems.

boundsAreInRobotCoordSystem - true/false mean that the bounds are specified in the Robot/local OS coordinate system.

Returns:

the screen shot of the specified area.

toRobotX

public static int toRobotX(int screenX)

Convert a local OS screen X-coordinate to the one compatible with the Robot's coordinate system. The local OS always puts the [0,0] coordinate to the top left corner of the primary display. This means that when a secondary display is placed to the left from the primary one it uses negative X-coordinates. Robot on the other hand places the [0,0] coordinate to the top left corner of the logical desktop and it never uses negative coordinates. This method performs conversion between the two systems.

Parameters:

screenX - a screen X-coordinate returned from the local OS.

Returns:

corresponding X-coordinate in the Robot's coordinate system.

toRobotY

public static int toRobotY(int screenY)

Convert a local OS screen Y-coordinate to the one compatible with the Robot's coordinate system. The local OS always puts the [0,0] coordinate to the top left corner of the primary display. This means that when a secondary display is placed to the top from the primary one it uses negative Y-coordinates. Robot on the other hand places the [0,0] coordinate to the top left corner of the logical desktop and it never uses negative coordinates. This method performs conversion between the two systems.

Parameters:

screenY - a screen Y-coordinate returned from the local OS.

Returns:

corresponding Y-coordinate in the Robot's coordinate system.

toScreenX

public static int toScreenX(int robotX)

Convert a Robot screen X-coordinate to the one compatible with the local OS screen coordinate system. The local OS always puts the [0,0] coordinate to the top left corner of the primary display. This means that when a secondary display is placed to the left from the primary one it uses negative X-coordinates. Robot on the other hand places the [0,0] coordinate to the top left corner of the logical desktop and it never uses negative coordinates. This method performs conversion between the two systems.

Parameters:

robotX - a Robot screen X-coordinate.

Returns:

the corresponding local OS desktop X-coordinate.

toScreenY

public static int toScreenY(int robotY)

Convert a Robot screen Y-coordinate to the one compatible with the local OS screen coordinate system. The local OS always puts the [0,0] coordinate to the top left corner of the primary display. This means that when a secondary display is placed to the top from the primary one it uses negative Y-coordinates. Robot on the other hand places the [0,0] coordinate to the top left corner of the logical desktop and it never uses negative coordinates. This method performs conversion between the two systems.

Parameters:

robotY - a Robot screen Y-coordinate.

Returns:

the corresponding local OS desktop Y-coordinate.

getDisplayRectForPoint

public static Rectangle getDisplayRectForPoint(int screenX,
                                               int screenY)

Get rectangle of a display containing the specified coordinates. It is typically used to center windows on a particular display.

Parameters:

screenX - a local OS screen X-coordinate.

screenY - a local OS screen Y-coordinate.

Returns:

rectangle of a display containing the specified coordinates.

getDisplayRectForRect

public static Rectangle getDisplayRectForRect(Rectangle rect)

Get rectangle of a display containing the specified rectangle or its largest part if it spans across multiple displays. It is typically used to identify which display a window is showing on.

Parameters:

rect - a rectangle of the local OS screen coordinates. See the toRobotX(int) method for an explanation of the difference between the local OS and Robot coordinate systems.

Returns:

bounds of the display that contains the largest part of the argument rectangle.

getScreenRect

public static Rectangle getScreenRect()

Get the screen rectangle in the local OS coordinates. See the toRobotX(int) method for an explanation of the difference between the local OS and Robot coordinate systems.

Returns:

the screen rectangle (multi screen aware).

getScreenRect

public static Rectangle getScreenRect(int screenNo)

getScreensForRect

public static List<Integer> getScreensForRect(Rectangle rect)

createCompatibleCopy

public static BufferedImage createCompatibleCopy(Image image,
                                                 boolean copyPixels)

Create a copy of the image compatible with the Robot's image comparison and display requirements. The method always returns either a new BufferedImage.TYPE_INT_ARGB or BufferedImage.TYPE_INT_RGB depending on whether the argument image has an Alpha channel or not.

Parameters:

image - the image to create a copy of.

copyPixels - true will copy the source image pixels to the target one. The value of false will make the method return an empty image of the compatible type and equal dimensions.

Returns:

a copy of the source image.

isFullScreenCaptureSupported

public static boolean isFullScreenCaptureSupported()

Find out if capture on the live screen is supported on the local environment. If the method returns true the calling screen capture components should take a screen shot and then display it in the image editor instead of showing the live screen editor implemented as a full screen window.

Returns:

true if full screen capture is supported or false if not.

getTopLeftScreen

public static GraphicsDevice getTopLeftScreen(Rectangle r)

Get the top left graphics device.

Parameters:

r - an optional output rectangle to store the device bounds to.

Returns:

the top left graphical device.

setFullScreenWindow

public static boolean setFullScreenWindow(Window w)

Set the full screen window. This method is equivalent to the GraphicsDevice.setFullScreenWindow(java.awt.Window) one save for two features:

• The window is set to full screen on the top left graphics device regardless of whether it is the primary display or not.
• The method may apply OS specific hacks, such as calling of the native APIs on Mac OS X.

Parameters:

w - a window.

Returns:

true if the operation succeeds.

addChangeListener

public static void addChangeListener(ChangeListener l)

Add a change listener to be notified of the screen layout changes.

Parameters:

l - the change listener to add.

Since:

4.1.4

removeChangeListener

public static void removeChangeListener(ChangeListener l)

Remove a change listener.

Parameters:

l - the listener to remove.

Since:

4.1.4

imageUpdate

public boolean imageUpdate(Image img,
                           int infoflags,
                           int x,
                           int y,
                           int width,
                           int height)

Implementation of the ImageObserver interface allowing the class to act as a dummy image observer when performing buffered image operations.

Specified by:

imageUpdate in interface ImageObserver

Parameters:

img - an image.

infoflags - flags.

x - the X-coordinate of the update.

y - the Y-coordinate of the update.

width - the update width.

height - the update height.

Returns:

always returns true because we are working just with buffered images.

compare

public int compare(com.tplan.robot.util.ScreenUtils.ScreenEntry o1,
                   com.tplan.robot.util.ScreenUtils.ScreenEntry o2)

Specified by:

compare in interface Comparator<com.tplan.robot.util.ScreenUtils.ScreenEntry>