Update the java.awt.Robot
specification to describe how it
may operate in modern desktop environments which do not automatically
give applications full access to the screen.
Append the following text to the class specification:
Platforms and desktop environments may impose restrictions or limitations
on the access required to implement all functionality in the Robot class.
For example:
- preventing access to the contents of any part of a desktop
or Window on the desktop that is not owned by the running application.
- treating window decorations as non-owned content.
- ignoring or limiting specific requests to manipulate windows.
- ignoring or limiting specific requests for Robot generated
(synthesized) events related to keyboard and mouse etc.
- requiring specific or global permissions to any access to window
contents, even application owned content,or to perform even limited
synthesizing of events.
The Robot API specification requires that approvals for these be granted
for full operation. If they are not granted, the API will be degraded as
discussed here. Relevant specific API methods may document more specific
limitations and requirements. Depending on the policies of the desktop
environment, the approvals mentioned above may:
- be required every time
- or persistent for the lifetime of an application,
- or persistent across multiple user desktop sessions
- be fine-grained permissions
- be associated with a specific binary application, or a class of binary
applications.
When such approvals need to given interactively, it may impede the normal
operation of the application until approved, and if approval is denied
or not possible, or cannot be made persistent then it will degrade
the functionality of this class and in turn any part of the operation
of the application which is dependent on it.
Augment the specification of mouseMove(int, int)
to describe
acceptable behaviour:
The mouse pointer may not visually move on some platforms, while the
subsequent mousePress and mouseRelease can be delivered to the correct
location
Update the specification of getPixelColor(int, int)
to allow
for degraded behaviour if the required permissions are missing.
- Extend the method specification to discuss permissions:
Returns the color of a pixel at the given screen coordinates.
If the desktop environment requires that permissions be granted to
capture screen content, and the required permissions are not granted,
then a SecurityException
may be thrown, or the content of
the returned Color
is undefined.
- Add an "API Note":
It is recommended to avoid calling this method on the AWT Event
Dispatch Thread since screen capture may be a lengthy operation,
particularly if acquiring permissions is needed and involves user
interaction.
- Define conditions when a
SecurityException
may be
thrown:
SecurityException
- if readDisplayPixels
permission is not granted, or access to the screen is denied by the
desktop environment
Similarly, update the specification of
createScreenCapture(Rectangle)
to allow for degraded
behaviour if the required permissions are missing:
- Remove the mouse cursor exclusion and discuss permissions in the
method description:
Creates an image containing pixels read from the screen.
This image does not include the mouse cursor.
If the desktop environment requires that permissions be granted to
capture screen content, and the required permissions are not granted,
then a SecurityException
may be thrown, or the content of
the returned BufferedImage
is undefined.
- Add an "API Note":
It is recommended to avoid calling this method on the AWT Event
Dispatch Thread since screen capture may be a lengthy operation,
particularly if acquiring permissions is needed and involves user
interaction.
- Provide additional conditions for throwing
a
SecurityException
:
SecurityException
- if readDisplayPixels
permission is not
granted,
or access to the screen is denied by the desktop environment
Finally, update the specification of
createMultiResolutionScreenCapture(Rectangle)
to allow for
degraded behaviour if the required permissions are missing.
- Remove the mouse cursor exclusion in the method description:
Creates an image containing pixels read from the screen.
This image does not include the mouse cursor.
This method can be used in case there is a scaling transform from
user space to screen (device) space. Typically this means that the
display is a high resolution screen, although strictly it means any
case in which there is such a tranform. Returns
a MultiResolutionImage
.
- Provide additional conditions for throwing
a
SecurityException
.
SecurityException
- if readDisplayPixels
permission is not granted,
or access to the screen is denied by the desktop environment
The Change Specification Request (CSR) associated with these changes is
8331036. This
specification aligns with the
corresponding specification
in the
Final Release of Java SE 21.