Spec-Zone.ru › OpenJDK 24

Класс 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
См. также:
  • GraphicsEnvironment.isHeadless()

Robot

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

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

Параметры:
screen - устройство GraphicsDevice экрана, указывающее систему координат, в которой будет работать Robot.
Вызывает исключение:
AWTException - если конфигурация платформы не позволяет управлять низкоуровневым вводом. Это исключение всегда выбрасывается, когда GraphicsEnvironment.isHeadless() возвращает true.
IllegalArgumentException - если screen не является устройством GraphicsDevice экрана.
См. также:
  • GraphicsEnvironment.isHeadless()
  • GraphicsDevice

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

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(int)
  • InputEvent.getMaskForButton(int)
  • Toolkit.areExtraMouseButtonsEnabled()
  • MouseInfo.getNumberOfButtons()
  • MouseEvent

mouseRelease

public void mouseRelease(int buttons)
Отпускает одну или несколько кнопок мыши.
Параметры:
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
См. также:
  • mousePress(int)
  • InputEvent.getMaskForButton(int)
  • Toolkit.areExtraMouseButtonsEnabled()
  • MouseInfo.getNumberOfButtons()
  • MouseEvent

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(int)
  • KeyEvent

keyRelease

public void keyRelease(int keycode)
Отпускает заданную клавишу.

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

Параметры:
keycode - Отпускаемая клавиша (например, KeyEvent.VK_A)
Вызывает исключение:
IllegalArgumentException - если keycode не является допустимой клавишей
См. также:
  • keyPress(int)
  • KeyEvent

getPixelColor

public Color getPixelColor(int x, int y)
Возвращает цвет пикселя в заданных координатах экрана.

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

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

createScreenCapture

public BufferedImage createScreenCapture(Rectangle screenRect)
Создаёт изображение, содержащее пиксели, считанные с экрана.

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

Примечание 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);
      }
Параметры:
screenRect - Область для захвата в координатах экрана
Возвращает:
Захваченное изображение
Выбрасывает:
IllegalArgumentException - если ширина и высота screenRect не больше нуля
SecurityException - если доступ к экрану запрещён средой рабочего стола
С:
9

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, 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://download.java.net/java/early_access/jdk24/docs/api/java.desktop/java/awt/Robot.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API