Класс Robot

java.lang.Object

java.awt.Robot

public class Robot extends Object

Этот класс используется для генерации системных событий ввода для автоматизации тестирования, демонстраций с автоматическим выполнением и других приложений, которым требуется управление мышью и клавиатурой. Основное назначение Robot — упрощение автоматизированного тестирования реализаций платформы Java.

Генерация событий ввода с помощью этого класса отличается от отправки событий в очередь событий AWT или компонентам AWT тем, что события генерируются в собственной очереди ввода платформы. Например, Robot.mouseMove действительно переместит указатель мыши, а не просто сгенерирует события перемещения мыши.

Примечание API:

Когда включен autoWaitForIdle(), методы, связанные с мышью и клавиатурой, нельзя вызывать в AWT EDT. Это связано с тем, что при включенном autoWaitForIdle() методы работы с мышью и клавиатурой неявно вызывают waitForIdle(), который выбрасывает IllegalThreadStateException при вызове в AWT EDT. Кроме того, операции захвата экрана могут занимать много времени, а delay(long ms) явно вносит задержку, поэтому их также не следует вызывать в EDT. В совокупности это означает, что методы этого класса по возможности не следует вызывать в EDT.

Обратите внимание: некоторым платформам для доступа к низкоуровневому управлению вводом требуются особые привилегии или расширения. Если текущая конфигурация платформы не допускает управление вводом, при попытке создать объекты Robot будет выброшено AWTException. Например, в системах X Window это исключение выбрасывается, если сервер X не поддерживает (или не включил) стандартное расширение XTEST 2.2.

Приложения, использующие Robot не для самотестирования, должны корректно обрабатывать эти условия ошибки.

Платформы и среды рабочего стола могут вводить ограничения или запреты на доступ, необходимый для реализации всех возможностей класса Robot. Например:

запрет доступа к содержимому любой части рабочего стола или любого окна на рабочем столе, не принадлежащего выполняющемуся приложению;
обработка украшений окна как содержимого, не принадлежащего приложению;
игнорирование или ограничение определенных запросов на управление окнами;
игнорирование или ограничение определенных запросов на события клавиатуры, мыши и другие события, сгенерированные (синтезированные) Robot;
требование отдельных или глобальных разрешений для любого доступа к содержимому окон, включая содержимое окон приложения, или даже для ограниченной генерации событий.

Спецификация API Robot требует предоставления необходимых разрешений для полноценной работы. Если разрешения не предоставлены, возможности API будут ограничены, как описано здесь. В соответствующей документации конкретных методов API могут быть указаны более точные ограничения и требования. В зависимости от политики среды рабочего стола упомянутые выше разрешения могут:

требоваться при каждом обращении;
сохраняться на время работы приложения;
сохраняться между несколькими сеансами рабочего стола пользователя;
быть разрешениями с детальной настройкой;
быть связаны с конкретным двоичным файлом приложения или классом двоичных приложений.

Если такие разрешения необходимо предоставлять в интерактивном режиме, это может мешать обычной работе приложения до их получения. Если в разрешении отказано, его невозможно получить или сохранить, функциональность этого класса будет ограничена, а вместе с ней — и любые части работы приложения, зависящие от нее.

С момента:

1.3

Краткое описание конструкторов

Конструктор	Описание
`Robot()`	Создает объект Robot в системе координат основного экрана.
`Robot(GraphicsDevice screen)`	Создает объект Robot для указанного устройства отображения.

Краткое описание методов

Модификатор и тип	Метод	Описание
`MultiResolutionImage`	`createMultiResolutionScreenCapture(Rectangle screenRect)`	Создает изображение, содержащее пиксели, считанные с экрана.
`BufferedImage`	`createScreenCapture(Rectangle screenRect)`	Создает изображение, содержащее пиксели, считанные с экрана.
`void`	`delay(int ms)`	Приостанавливает выполнение на заданное время.
`int`	`getAutoDelay()`	Возвращает время в миллисекундах, в течение которого этот Robot приостанавливает выполнение после генерации события.
`Color`	`getPixelColor(int x, int y)`	Возвращает цвет пикселя в заданных экранных координатах.
`boolean`	`isAutoWaitForIdle()`	Возвращает информацию о том, вызывает ли этот Robot автоматически `waitForIdle` после генерации события.
`void`	`keyPress(int keycode)`	Нажимает указанную клавишу.
`void`	`keyRelease(int keycode)`	Отпускает указанную клавишу.
`void`	`mouseMove(int x, int y)`	Перемещает указатель мыши в заданные экранные координаты.
`void`	`mousePress(int buttons)`	Нажимает одну или несколько кнопок мыши.
`void`	`mouseRelease(int buttons)`	Отпускает одну или несколько кнопок мыши.
`void`	`mouseWheel(int wheelAmt)`	Поворачивает колесо прокрутки мыши.
`void`	`setAutoDelay(int ms)`	Задает время в миллисекундах, в течение которого этот Robot приостанавливает выполнение после генерации события.
`void`	`setAutoWaitForIdle(boolean isOn)`	Задает, будет ли этот Robot автоматически вызывать `waitForIdle` после генерации события.
`String`	`toString()`	Возвращает строковое представление этого Robot.
`void`	`waitForIdle()`	Ожидает обработки всех событий, находящихся в данный момент в очереди событий.

Методы, объявленные в классе Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Подробное описание конструкторов

Robot

public Robot() throws AWTException

Создает объект Robot в системе координат основного экрана.

Выбрасывает:

AWTException — если конфигурация платформы не допускает низкоуровневое управление вводом. Это исключение всегда выбрасывается, если GraphicsEnvironment.isHeadless() возвращает true

См. также:

Robot

public Robot(GraphicsDevice screen) throws AWTException

Создает объект Robot для указанного устройства отображения. Координаты, передаваемые в вызовы методов Robot, таких как mouseMove, getPixelColor и createScreenCapture, будут интерпретироваться в той же системе координат, что и у указанного экрана. Обратите внимание: в зависимости от конфигурации платформы несколько экранов могут:

использовать общую систему координат, образуя единый виртуальный экран;
использовать разные системы координат, выступая в качестве независимых экранов.

Если конфигурация экранных устройств изменяется таким образом, что затрагивается система координат, поведение существующих объектов Robot не определено.

Параметры:

screen — экранное устройство GraphicsDevice, задающее систему координат, в которой будет работать Robot.

Выбрасывает:

IllegalArgumentException — если screen не является экранным устройством GraphicsDevice.

См. также:

Подробное описание методов

mouseMove

public void mouseMove(int x, int y)

Перемещает указатель мыши в заданные экранные координаты.

На некоторых платформах указатель мыши может визуально не перемещаться, хотя последующие вызовы mousePress и mouseRelease могут быть доставлены в правильное место.

Параметры:: x — координата X; y — координата Y
Выбрасывает:: IllegalThreadStateException — если метод вызван в потоке диспетчеризации событий AWT и isAutoWaitForIdle возвращает true

mousePress

public void mousePress(int buttons)

Нажимает одну или несколько кнопок мыши. Кнопки мыши следует отпускать с помощью метода mouseRelease(int).

Параметры:

buttons — маска кнопок; комбинация одной или нескольких масок кнопок мыши.

В качестве параметра buttons разрешено использовать только комбинацию допустимых значений. Допустимая комбинация состоит из InputEvent.BUTTON1_DOWN_MASK, InputEvent.BUTTON2_DOWN_MASK, InputEvent.BUTTON3_DOWN_MASK и значений, возвращаемых методом InputEvent.getMaskForButton(button). Допустимая комбинация также зависит от значения Toolkit.areExtraMouseButtonsEnabled() следующим образом:

Если поддержка расширенных кнопок мыши disabled в Java, разрешено использовать только следующие стандартные маски кнопок: InputEvent.BUTTON1_DOWN_MASK, InputEvent.BUTTON2_DOWN_MASK, InputEvent.BUTTON3_DOWN_MASK.
Если поддержка расширенных кнопок мыши enabled в Java, разрешено использовать стандартные маски кнопок и маски существующих расширенных кнопок мыши, если у мыши больше трех кнопок. Таким образом, разрешено использовать маски кнопок, соответствующие кнопкам с номерами от 1 до MouseInfo.getNumberOfButtons().
Для получения маски любой кнопки мыши по ее номеру рекомендуется использовать метод InputEvent.getMaskForButton(button).

Также принимаются следующие стандартные маски кнопок:

InputEvent.BUTTON1_MASK
InputEvent.BUTTON2_MASK
InputEvent.BUTTON3_MASK

Однако вместо них рекомендуется использовать InputEvent.BUTTON1_DOWN_MASK, InputEvent.BUTTON2_DOWN_MASK, InputEvent.BUTTON3_DOWN_MASK. Следует использовать либо расширенные значения _DOWN_MASK, либо старые значения _MASK, но не смешивать эти две модели.

Выбрасывает:

IllegalArgumentException — если маска buttons содержит маску дополнительной кнопки мыши, а поддержка расширенных кнопок мыши disabled в Java

IllegalArgumentException — если маска buttons содержит маску дополнительной кнопки мыши, которой нет у мыши, а поддержка расширенных кнопок мыши enabled в Java

IllegalThreadStateException — если метод вызван в потоке диспетчеризации событий AWT и isAutoWaitForIdle возвращает true

См. также:

mouseRelease

public void mouseRelease(int buttons)

Отпускает одну или несколько кнопок мыши.

Параметры:

buttons — маска кнопок; комбинация одной или нескольких масок кнопок мыши.

Если поддержка расширенных кнопок мыши disabled в Java, разрешено использовать только следующие стандартные маски кнопок: InputEvent.BUTTON1_DOWN_MASK, InputEvent.BUTTON2_DOWN_MASK, InputEvent.BUTTON3_DOWN_MASK.
Если поддержка расширенных кнопок мыши enabled в Java, разрешено использовать стандартные маски кнопок и маски существующих расширенных кнопок мыши, если у мыши больше трех кнопок. Таким образом, разрешено использовать маски кнопок, соответствующие кнопкам с номерами от 1 до MouseInfo.getNumberOfButtons().
Для получения маски любой кнопки мыши по ее номеру рекомендуется использовать метод InputEvent.getMaskForButton(button).

Также принимаются следующие стандартные маски кнопок:

InputEvent.BUTTON1_MASK
InputEvent.BUTTON2_MASK
InputEvent.BUTTON3_MASK

Выбрасывает:

IllegalThreadStateException — если метод вызван в потоке диспетчеризации событий AWT и isAutoWaitForIdle возвращает true

См. также:

mouseWheel

public void mouseWheel(int wheelAmt)

Поворачивает колесо прокрутки мыши.

Параметры:: wheelAmt — количество «щелчков» колеса мыши. Отрицательные значения обозначают движение вверх, от пользователя; положительные — вниз, к пользователю.
Выбрасывает:: IllegalThreadStateException — если метод вызван в потоке диспетчеризации событий AWT и isAutoWaitForIdle возвращает true
С момента:: 1.4

keyPress

public void keyPress(int keycode)

Нажимает указанную клавишу. Клавишу следует отпускать с помощью метода keyRelease.

Коды клавиш, которым соответствуют несколько физических клавиш (например, KeyEvent.VK_SHIFT может обозначать как левую, так и правую клавишу Shift), будут сопоставлены с левой клавишей.

Параметры:

keycode — клавиша для нажатия (например, KeyEvent.VK_A)

Выбрасывает:

IllegalArgumentException — если keycode не является допустимой клавишей

IllegalThreadStateException — если метод вызван в потоке диспетчеризации событий AWT и isAutoWaitForIdle возвращает true

См. также:

keyRelease

public void keyRelease(int keycode)

Отпускает указанную клавишу.

Параметры:

keycode — клавиша для отпускания (например, KeyEvent.VK_A)

Выбрасывает:

IllegalArgumentException — если keycode не является допустимой клавишей

IllegalThreadStateException — если метод вызван в потоке диспетчеризации событий AWT и isAutoWaitForIdle возвращает true

См. также:

getPixelColor

public Color getPixelColor(int x, int y)

Возвращает цвет пикселя в заданных экранных координатах.

Если среда рабочего стола требует предоставления разрешений на захват содержимого экрана, а необходимые разрешения не предоставлены, может быть выброшено SecurityException либо содержимое возвращенного Color не определено.

Примечание API:: Рекомендуется не вызывать этот метод в потоке диспетчеризации событий AWT, поскольку захват экрана может занимать много времени, особенно если требуется получить разрешения, для чего необходимо взаимодействие с пользователем.
Параметры:: x — координата X пикселя; y — координата Y пикселя
Возвращает:: Цвет пикселя
Выбрасывает:: SecurityException — если среда рабочего стола запрещает доступ к экрану

createScreenCapture

public BufferedImage createScreenCapture(Rectangle screenRect)

Создает изображение, содержащее пиксели, считанные с экрана.

Примечание API:: Рекомендуется не вызывать этот метод в потоке диспетчеризации событий AWT, поскольку захват экрана может занимать много времени, особенно если требуется получить разрешения, для чего необходимо взаимодействие с пользователем.
Параметры:: screenRect — прямоугольная область для захвата в экранных координатах
Возвращает:: Захваченное изображение
Выбрасывает:: IllegalArgumentException — если ширина и высота screenRect не больше нуля; SecurityException — если среда рабочего стола запрещает доступ к экрану

createMultiResolutionScreenCapture

public MultiResolutionImage createMultiResolutionScreenCapture(Rectangle screenRect)

Создает изображение, содержащее пиксели, считанные с экрана. Этот метод можно использовать, если между пользовательским пространством и пространством экрана (устройства) применяется масштабирование. Обычно это означает, что дисплей имеет высокое разрешение, хотя строго говоря, речь идет о любом случае применения такого преобразования. Возвращает MultiResolutionImage.

На дисплее без масштабирования MultiResolutionImage будет иметь один вариант изображения:

Базовое изображение с размером, заданным пользователем.

На дисплее высокого разрешения с масштабированием MultiResolutionImage будет иметь два варианта изображения:

Базовое изображение с размером, заданным пользователем. Оно масштабируется с экрана.
Изображение с исходным разрешением устройства и количеством пикселей, соответствующим размеру устройства.

Пример:

     Image nativeResImage;
     MultiResolutionImage mrImage = robot.createMultiResolutionScreenCapture(frame.getBounds());
     List<Image> resolutionVariants = mrImage.getResolutionVariants();
     if (resolutionVariants.size() > 1) {
         nativeResImage = resolutionVariants.get(1);
     } else {
         nativeResImage = resolutionVariants.get(0);
     }

Примечание API:: Рекомендуется не вызывать этот метод в потоке диспетчеризации событий AWT, поскольку захват экрана может занимать много времени, особенно если требуется получить разрешения, для чего необходимо взаимодействие с пользователем.
Параметры:: screenRect — прямоугольная область для захвата в экранных координатах
Возвращает:: Захваченное изображение
Выбрасывает:: IllegalArgumentException — если ширина и высота screenRect не больше нуля; SecurityException — если среда рабочего стола запрещает доступ к экрану
С момента:: 9

isAutoWaitForIdle

public boolean isAutoWaitForIdle()

Возвращает информацию о том, вызывает ли этот Robot автоматически waitForIdle после генерации события.

Возвращает:: Информацию о том, вызывается ли автоматически waitForIdle

setAutoWaitForIdle

public void setAutoWaitForIdle(boolean isOn)

Задает, будет ли этот Robot автоматически вызывать waitForIdle после генерации события.

Примечание API:: Если установить значение true, вы не сможете вызывать события управления мышью и клавиатурой в потоке диспетчеризации событий AWT.
Параметры:: isOn — указывает, будет ли автоматически вызываться waitForIdle

getAutoDelay

public int getAutoDelay()

Возвращает время в миллисекундах, в течение которого этот Robot приостанавливает выполнение после генерации события.

Возвращает:: длительность задержки в миллисекундах

setAutoDelay

public void setAutoDelay(int ms)

Задает время в миллисекундах, в течение которого этот Robot приостанавливает выполнение после генерации события.

Параметры:: ms — длительность задержки в миллисекундах
Выбрасывает:: IllegalArgumentException — если ms не находится в диапазоне от 0 до 60 000 миллисекунд включительно

delay

public void delay(int ms)

Приостанавливает выполнение на заданное время.

Если во время ожидания вызывающий поток будет прерван, метод немедленно вернет управление с установленным флагом прерывания. Если флаг прерывания уже установлен, метод немедленно вернет управление, сохранив этот флаг.

Примечание API:: Рекомендуется не вызывать этот метод в потоке диспетчеризации событий AWT, поскольку задержка может быть значительной.
Параметры:: ms — время приостановки в миллисекундах
Выбрасывает:: IllegalArgumentException — если ms не находится в диапазоне от 0 до 60,000 миллисекунд включительно

waitForIdle

public void waitForIdle()

Ожидает обработки всех событий, находящихся в данный момент в очереди событий.

Выбрасывает:: IllegalThreadStateException — если метод вызван в потоке диспетчеризации событий AWT

toString

public String toString()

Возвращает строковое представление этого Robot.

Переопределяет:: toString в классе Object
Возвращает:: строковое представление.

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/25/docs/api/java.desktop/java/awt/Robot.html