Класс Robot

java.lang.Object

java.awt.Robot

public class Robot extends Object

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

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

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

Приложения, использующие 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()`	Ожидает, пока все события, находящиеся в настоящее время в очереди событий, не будут обработаны.

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

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

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

Robot

public Robot() throws AWTException

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

Исключения:

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

SecurityException - если разрешение createRobot не предоставлено

См. также:

Robot

public Robot(GraphicsDevice screen) throws AWTException

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

разделять одну и ту же систему координат, чтобы сформировать объединённый виртуальный экран
использовать разные системы координат, чтобы действовать как независимые экраны

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

Параметры:

screen - Графическое устройство экрана, указывающее систему координат, в которой будет работать Robot.

Исключения:

IllegalArgumentException - если screen не является графическим устройством экрана.

SecurityException - если разрешение createRobot не предоставлено

См. также:

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

mouseMove

public void mouseMove(int x, int y)

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

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

Параметры:: x - Позиция X; y - Позиция Y

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

См. также:

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

Исключения:

См. также:

mouseWheel

public void mouseWheel(int wheelAmt)

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

Параметры:: wheelAmt - количество "ступеней" для перемещения колеса мыши. Отрицательные значения указывают на движение вверх/вдаль от пользователя, положительные значения указывают на движение вниз/к пользователю.
С:: 1.4

keyPress

public void keyPress(int keycode)

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

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

Параметры:

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

Исключения:

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

См. также:

keyRelease

public void keyRelease(int keycode)

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

Параметры:

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

Исключения:

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

См. также:

getPixelColor

public Color getPixelColor(int x, int y)

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

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

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

createScreenCapture

public BufferedImage createScreenCapture(Rectangle screenRect)

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

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

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

Параметры:

screenRect - Прямоугольник для захвата в координатах экрана

Возвращает:

Захваченное изображение

Исключение:

IllegalArgumentException - если ширина и высота screenRect не больше нуля

SecurityException - если разрешение readDisplayPixels не предоставлено или доступ к экрану запрещен операционной системой

См. также:

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);
      }

Параметры:

screenRect - Прямоугольник для захвата в координатах экрана

Возвращает:

Захваченное изображение

Исключение:

IllegalArgumentException - если ширина и высота screenRect не больше нуля

SecurityException - если разрешение readDisplayPixels не предоставлено или доступ к экрану запрещен операционной системой

С:

См. также:

isAutoWaitForIdle

public boolean isAutoWaitForIdle()

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

Возвращает:: Вызывается ли waitForIdle автоматически

setAutoWaitForIdle

public void setAutoWaitForIdle(boolean isOn)

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

Параметры:: 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)

Ожидает указанное время.

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

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

waitForIdle

public void waitForIdle()

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

Исключение:: IllegalThreadStateException - если вызывается в потоке обработки событий AWT

toString

public String toString()

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

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

© 1993, 2023, 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/21/docs/api/java.desktop/java/awt/Robot.html