Ir para o conteúdo
Todas as ferramentas

list_windows

Ecrã, janelas e interface · macOS · Windows

Efeito: leitura. Estado: disponibilidade condicionada.

«Disponibilidade condicionada» significa que a ferramenta pode depender da versão, plataforma, permissões, conta ou configuração. Não significa que esteja ativa em todas as instalações.

macOS

Finalidade

Lista as janelas na tela de qualquer app com window_id, ID do pacote e nome do app proprietário, título, limites (espaço global, canto superior esquerdo, pontos), display_id (o CGDirectDisplayID: corresponde a list_displays, para que você possa descobrir em que tela está uma janela), layer (0 = janela normal de app; diferente de zero = painel/sobreposição/menu) e is_focused. Os TÍTULOS das janelas exigem a permissão de Gravação de Tela; sem ela, retorna um erro explícito permission_required em vez de um resultado sem títulos. Filtro app_bundle_id opcional: observe que apps do tipo Electron costumam ser donos de suas janelas a partir de um processo HELPER com outro ID de pacote, então um filtro pode voltar vazio mesmo com o app claramente na tela. on_screen_only É TRUE POR PADRÃO e exclui janelas minimizadas, ocultas e de outros Spaces; passe false para vê-las. include_overlays É FALSE POR PADRÃO e exclui janelas de camada diferente de zero (Central de Notificações, widgets, menus); passe true para incluí-las; use layer no resultado para distingui-las das janelas normais. include_minimized_state É FALSE POR PADRÃO (uma consulta extra de Acessibilidade por app, por isso é opcional); passe true para adicionar `minimized` (true/false) a cada janela E, quando on_screen_only é true (o padrão), também trazer de volta as janelas minimizadas que esse filtro descartaria; SEM Acessibilidade concedida, `minimized` é `null` (desconhecido) e nenhuma janela minimizada é adicionada de volta, nunca um false presumido, de modo que você pode encontrar ou capturar uma janela minimizada sem trazê-la para a frente antes. Quando o resultado está vazio, esta ferramenta retorna um `note` explicando qual filtro o esvaziou e o que passar no lugar; leia-o em vez de concluir que o app não tem janelas. window_id é estável dentro da sessão para direcionamento posterior.

Entradas obrigatórias

O esquema desta plataforma não declara entradas obrigatórias. Ainda podem existir seletores opcionais ou requisitos de execução.

Permissões e confirmação

O esquema não declara um parâmetro explícito de confirmação. Isto não autoriza qualquer ação sem permissão; reveja o efeito e obtenha autorização.

Esquema técnico canónico em inglês — 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"
}

Exemplo documental

Exemplo de documentação para list_windows. Não execute este exemplo. Os argumentos apresentados pertencem a um conjunto de dados fictício; resolva identificadores reais e obtenha autorização antes de uma chamada real.

{}

Windows

Finalidade

Lista as janelas abertas nesta máquina: id da janela, app proprietário (nome do exe), pid, título, limites {x,y,w,h} e id da tela. Somente para Windows (usa a API de janelas Win32). Filtre por app com app_bundle_id (uma correspondência de substring do nome do exe no Windows). on_screen_only É TRUE POR PADRÃO e exclui janelas minimizadas e sem título (espelha list_windows do mac-swift, #3634); passe false para vê-las. include_minimized_state É FALSE POR PADRÃO; passe true para adicionar `minimized` (true/false) a cada janela E, quando on_screen_only é true (o padrão), também manter as janelas minimizadas que esse filtro descartaria (paridade #3663 com o mac-swift); ao contrário da consulta de Acessibilidade do Mac, IsIconic não precisa de permissão no Windows, então `minimized` sempre é resolvido e aqui nunca é null/desconhecido.

Entradas obrigatórias

O esquema desta plataforma não declara entradas obrigatórias. Ainda podem existir seletores opcionais ou requisitos de execução.

Permissões e confirmação

O esquema não declara um parâmetro explícito de confirmação. Isto não autoriza qualquer ação sem permissão; reveja o efeito e obtenha autorização.

Esquema técnico canónico em inglês — 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"
}

Exemplo documental

Exemplo de documentação para list_windows. Não execute este exemplo. Os argumentos apresentados pertencem a um conjunto de dados fictício; resolva identificadores reais e obtenha autorização antes de uma chamada real.

{}