list_windows

Экран, окна и интерфейс · macOS · Windows

Эффект: чтение. Статус: условно доступен.

«Условная доступность» означает, что инструмент может зависеть от версии, платформы, разрешений, учётной записи или настроек. Он доступен не во всех установках.

macOS

Назначение

Перечисляет видимые на экране окна любого приложения с window_id, идентификатором пакета и именем приложения-владельца, заголовком, границами в глобальном пространстве (начало слева сверху, единицы — точки), display_id (CGDirectDisplayID, совпадающий с list_displays, поэтому можно определить дисплей окна), layer (0 = обычное окно приложения; не ноль = панель/оверлей/меню) и is_focused. Для ЗАГОЛОВКОВ окон требуется разрешение на запись экрана; без него возвращается явная ошибка permission_required, а не результат без заголовков. Доступен фильтр app_bundle_id; учтите, что приложения на Electron часто создают окна через ВСПОМОГАТЕЛЬНЫЙ процесс с другим идентификатором пакета, поэтому фильтр может вернуть пусто, хотя приложение видно на экране. on_screen_only ПО УМОЛЧАНИЮ РАВЕН TRUE и исключает свернутые, скрытые окна и окна в других Spaces; передайте false, чтобы увидеть их. include_overlays ПО УМОЛЧАНИЮ РАВЕН FALSE и исключает окна с ненулевым layer (Центр уведомлений, виджеты, меню); передайте true, чтобы включить их — по layer в результате их можно отличить от обычных окон. include_minimized_state ПО УМОЛЧАНИЮ РАВЕН FALSE (это дополнительный запрос Accessibility для каждого приложения, поэтому он включается явно); передайте true, чтобы добавить `minimized` (true/false) к каждому окну И, когда on_screen_only равен true (по умолчанию), также вернуть свернутые окна, которые этот фильтр иначе отбросил бы — БЕЗ выданного доступа Accessibility `minimized` равно `null` (неизвестно), свернутые окна не добавляются, а значение false никогда не угадывается, так что свернутое окно можно найти или захватить, не выводя его на передний план. При пустом результате инструмент возвращает `note` с объяснением, какой фильтр его опустошил и что передать вместо него; прочитайте это пояснение, прежде чем заключать, что у приложения нет окон. window_id стабилен в течение сеанса для последующего выбора цели.

Обязательные входные данные

Схема этой платформы не объявляет обязательных входных данных. Необязательные селекторы или требования среды всё же могут применяться.

Разрешения и подтверждение

Схема не объявляет явного параметра подтверждения. Это не разрешает действовать без согласия: проверьте эффект и получите разрешение.

Используйте на этой платформе только приложения, учетные записи и ресурсы, разрешенные пользователем. Требования к подключению и разрешениям приведены в описании инструмента для конкретной платформы; этот каталог не заявляет о дополнительных областях OAuth или разрешениях OS.

Каноническая техническая схема на английском — macOS

{
  "properties": {
    "app_bundle_id": {
      "description": "Only return windows owned by this app bundle id.",
      "type": "string"
    },
    "include_minimized_state": {
      "description": "Add `minimized` (true/false) to each window via an Accessibility lookup; null without Accessibility granted (default false).",
      "type": "boolean"
    },
    "include_overlays": {
      "description": "Include non-zero-layer windows — Notification Center, desktop widgets, menus (default false).",
      "type": "boolean"
    },
    "on_screen_only": {
      "description": "Only on-screen windows (default true).",
      "type": "boolean"
    }
  },
  "required": [],
  "type": "object"
}

Пример для документации

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

{}

Windows

Назначение

Перечисляет открытые окна на этом компьютере: идентификатор окна, приложение-владелец (имя exe), pid, заголовок, границы {x,y,w,h} и идентификатор дисплея. Только для Windows, использует Win32 API окон. Фильтруйте по приложению через app_bundle_id — в Windows это поиск подстроки в имени exe. on_screen_only ПО УМОЛЧАНИЮ РАВЕН TRUE и исключает свернутые окна и окна без заголовка (аналогично list_windows в mac-swift, #3634); передайте false, чтобы увидеть их. include_minimized_state ПО УМОЛЧАНИЮ РАВЕН FALSE; передайте true, чтобы добавить `minimized` (true/false) к каждому окну И, когда on_screen_only равен true (по умолчанию), также сохранить свернутые окна, которые этот фильтр иначе отбросил бы (#3663, паритет с mac-swift) — в отличие от запроса через Accessibility на Mac, IsIconic не требует разрешения в Windows, поэтому `minimized` всегда определяется и здесь никогда не бывает null/неизвестным.

Обязательные входные данные

Разрешения и подтверждение

Используйте на этой платформе только приложения, учетные записи и ресурсы, разрешенные пользователем. Требования к подключению и разрешениям приведены в описании инструмента для конкретной платформы; этот каталог не заявляет о дополнительных областях OAuth или разрешениях OS.

Каноническая техническая схема на английском — Windows

{
  "properties": {
    "app_bundle_id": {
      "description": "Filter to windows owned by this app. On Windows, a case-insensitive substring of the exe name (e.g. 'chrome').",
      "type": "string"
    },
    "include_minimized_state": {
      "description": "Add `minimized` (true/false) to each window, and keep minimized windows under on_screen_only:true instead of dropping them (default false).",
      "type": "boolean"
    },
    "on_screen_only": {
      "description": "Only return visible, non-minimized, non-empty-title windows (default true).",
      "type": "boolean"
    }
  },
  "required": [],
  "type": "object"
}

Пример для документации

{}