Pular para o conteúdo principal

Assinaturas das funções internas

Todas as funções internas, agrupadas por área. Cada linha mostra os nomes e os tipos dos parâmetros, em ordem, e o tipo retornado. Simples marca as funções internas que o modo Simples da interface de configuração oferece. Exemplos filtra a biblioteca de exemplos para os scripts que chamam essa função interna. A dica de ferramenta do preenchimento automático do editor mostra as mesmas assinaturas.

AutoHotkey​

AutoHotkeyExecuteScript​

AutoHotkeyExecuteScript(script: Text) → Integer · Simples

Executa código AutoHotkey v2 com o programa AutoHotkey definido nas configurações e aguarda até que ele termine. O contexto do gatilho é passado como variáveis, e as linhas de saída são impressas com o prefixo AHK:.

Parâmetros

  • script: Text — O texto do script AutoHotkey v2 a executar. Interromper a ação encerra o processo do AutoHotkey.

Retorna

O código de saída do AutoHotkey, ou -1 se o suporte ao AutoHotkey estiver desativado, se o caminho do programa não estiver definido ou não for encontrado, ou se o programa não iniciar.

1 exemplo: Passar o trabalho ao AutoHotkey

Capture​

CaptureSaveRegion​

CaptureSaveRegion(fileName: Text, x: Integer, y: Integer, width: Integer, height: Integer) → Bool

Captura um retângulo da tela e o salva como arquivo de imagem. Antes, remove da tela o rastro de gesto e a dica do próprio aplicativo, aguardando até 250 milissegundos por isso.

Parâmetros

  • fileName: Text — Caminho do arquivo de imagem a gravar. A extensão (.bmp, .png, .jpg ou .jpeg) define o formato. Um arquivo existente é substituído; pastas ausentes não são criadas.
  • x: Integer — Borda esquerda do retângulo, em pixels da tela.
  • y: Integer — Borda superior do retângulo, em pixels da tela.
  • width: Integer — Largura do retângulo, em pixels. Deve ser maior que 0.
  • height: Integer — Altura do retângulo, em pixels. Deve ser maior que 0.

Retorna

true se o arquivo de imagem foi gravado; false se width ou height não for positivo, se a captura falhar ou se o arquivo não puder ser gravado. Um fileName que não termine em .bmp, .png, .jpg ou .jpeg interrompe o script com um erro.

1 exemplo: Capturar a área que você circulou

CaptureShowImage​

CaptureShowImage(fileName: Text) → Bool

Mostra um arquivo de imagem em tamanho original em uma janela de visualização sem borda e sempre visível, centralizada no monitor sob o cursor. Arraste para movê-la, clique duas vezes para fechá-la ou clique com o botão direito para Copiar, Salvar e Fechar.

Parâmetros

  • fileName: Text — Caminho do arquivo .bmp, .png, .jpg ou .jpeg a mostrar.

Retorna

true se a imagem foi carregada e a janela de visualização está abrindo; false se o arquivo não existir ou não for uma imagem legível. Um fileName que não termine em .bmp, .png, .jpg ou .jpeg interrompe o script com um erro.

CaptureShowRegion​

CaptureShowRegion(x: Integer, y: Integer, width: Integer, height: Integer) → Bool

Captura um retângulo da tela e mostra a cópia em uma janela de visualização sem borda e sempre visível, posicionada exatamente sobre essa área. Antes, remove o rastro de gesto e a dica do próprio aplicativo, aguardando até 250 milissegundos.

Parâmetros

  • x: Integer — Borda esquerda do retângulo, em pixels da tela.
  • y: Integer — Borda superior do retângulo, em pixels da tela.
  • width: Integer — Largura do retângulo, em pixels. Deve ser maior que 0.
  • height: Integer — Altura do retângulo, em pixels. Deve ser maior que 0.

Retorna

true se a captura foi bem-sucedida e a janela de visualização está abrindo; false se width ou height não for positivo ou se não for possível capturar a tela.

Clipboard​

ClipboardClear​

ClipboardClear() → Bool

Esvazia a área de transferência, removendo texto, imagens e todos os outros formatos, sem colocar nada novo nela.

Parâmetros

Sem parâmetros.

Retorna

true se a área de transferência foi esvaziada; false se outro programa a manteve ocupada.

1 exemplo: Converter o texto selecionado em maiúsculas

ClipboardCopySelection​

ClipboardCopySelection(timeoutMs: Integer) → Text · Simples

Envia Ctrl+C para a janela ativa e retorna o texto copiado, aguardando antes que as teclas Ctrl, Shift, Alt e Windows sejam soltas. A cópia substitui a área de transferência; use ClipboardSave e ClipboardRestore para preservá-la.

Parâmetros

  • timeoutMs: Integer — Tempo total de espera para que as teclas sejam soltas e a cópia chegue, em milissegundos, de 0 a 60000. Valores maiores contam como 60000. 1000 atende à maioria dos programas.

Retorna

O texto copiado, ou texto vazio se as teclas continuarem pressionadas, se nada for copiado (sem seleção) ou se a cópia não contiver texto antes de timeoutMs se esgotar.

1 exemplo: Pesquisar na Web o texto selecionado

ClipboardGetHtml​

ClipboardGetHtml() → Text

Retorna o HTML da área de transferência, como o que um navegador coloca nela quando você copia parte de uma página da Web.

Parâmetros

Sem parâmetros.

Retorna

O fragmento HTML copiado sem o cabeçalho HTML da área de transferência, ou texto vazio se a área de transferência não contiver HTML ou estiver ocupada.

ClipboardGetRtf​

ClipboardGetRtf() → Text

Retorna o rich text (RTF) da área de transferência, como o que um processador de texto coloca nela quando você copia texto formatado.

Parâmetros

Sem parâmetros.

Retorna

A marcação RTF como texto, ou texto vazio se a área de transferência não contiver RTF ou estiver ocupada.

ClipboardGetSequenceNumber​

ClipboardGetSequenceNumber() → Integer

Retorna um número que o Windows altera sempre que o conteúdo da área de transferência muda. Leia-o antes de algo que deva copiar e depois compare para saber que a cópia chegou.

Parâmetros

Sem parâmetros.

Retorna

O número de sequência atual da área de transferência. Só a mudança do número tem significado, não o valor em si.

ClipboardGetText​

ClipboardGetText() → Text · Simples

Retorna o texto sem formatação que está na área de transferência. Formatação, imagens e arquivos na área de transferência são ignorados.

Parâmetros

Sem parâmetros.

Retorna

O texto da área de transferência, ou texto vazio se ela não contiver texto ou se outro programa a manteve ocupada.

6 exemplos: Extrair um valor de um texto copiado com uma expressão regular, Contar as palavras da área de transferência, Juntar as linhas da área de transferência em uma só, A data de hoje e um nome de arquivo com carimbo de data e hora, Converter o texto selecionado em maiúsculas, Pesquisar a seleção na Web

ClipboardLoadImage​

ClipboardLoadImage(path: Text) → Bool

Carrega um arquivo de imagem e o coloca na área de transferência, substituindo o conteúdo atual, pronto para colar em outros programas. Áreas transparentes de um PNG ficam brancas.

Parâmetros

  • path: Text — Caminho completo do arquivo de imagem, terminando em .bmp, .png, .jpg ou .jpeg. Qualquer outra extensão interrompe o script com um erro.

Retorna

true se a imagem está na área de transferência; false se o arquivo não existir, não for uma imagem legível ou se a área de transferência estiver ocupada.

ClipboardPasteReplacementText​

ClipboardPasteReplacementText(text: Text) → Bool · Simples

Coloca texto na área de transferência e envia Ctrl+V para colá-lo na janela ativa. Não aguarda a colagem terminar; por isso, aguarde um pouco com UtilityWait antes de ClipboardRestore.

Parâmetros

  • text: Text — O texto a colar.

Retorna

true se a área de transferência foi definida e Ctrl+V foi enviado; false se a área de transferência estava ocupada ou se o Windows bloqueou os pressionamentos de tecla.

2 exemplos: Preencher um modelo e colá-lo, Converter o texto selecionado em maiúsculas

ClipboardRestore​

ClipboardRestore() → Bool

Restaura o conteúdo da área de transferência salvo pelo último ClipboardSave nesta execução do script, em todos os formatos. Sem um ClipboardSave anterior nesta execução, esvazia a área de transferência.

Parâmetros

Sem parâmetros.

Retorna

true se tudo o que foi salvo foi restaurado; false se a área de transferência estava ocupada ou se um formato não pôde ser restaurado.

5 exemplos: Preencher um modelo e colá-lo, Pesquisar na Web o texto selecionado, Converter o texto selecionado em maiúsculas, Pesquisar a seleção na Web, Deixar só uma ação executar um trecho por vez

ClipboardSave​

ClipboardSave() → Bool

Salva uma cópia de tudo o que está na área de transferência, em todos os formatos, para que ClipboardRestore possa restaurá-la depois na mesma execução do script. Uma segunda chamada substitui a cópia salva.

Parâmetros

Sem parâmetros.

Retorna

true se a área de transferência foi lida; false se outro programa a manteve ocupada.

5 exemplos: Preencher um modelo e colá-lo, Pesquisar na Web o texto selecionado, Converter o texto selecionado em maiúsculas, Pesquisar a seleção na Web, Deixar só uma ação executar um trecho por vez

ClipboardSaveImage​

ClipboardSaveImage(path: Text) → Bool

Salva em um arquivo a imagem da área de transferência, como uma captura de tela feita com Print Screen, no formato indicado pela extensão do arquivo. Um arquivo existente é substituído.

Parâmetros

  • path: Text — Caminho completo do arquivo a gravar, terminando em .bmp, .png, .jpg ou .jpeg. Qualquer outra extensão interrompe o script com um erro.

Retorna

true se o arquivo foi gravado; false se a área de transferência não contiver imagem ou se o arquivo não puder ser gravado.

1 exemplo: Salvar uma imagem copiada em um arquivo

ClipboardSetHtml​

ClipboardSetHtml(html: Text) → Bool

Coloca um fragmento HTML na área de transferência, substituindo o conteúdo atual, para que colar em um email ou processador de texto mantenha a formatação. Uma cópia em texto sem formatação, sem as tags, também é adicionada, para programas que só colam texto.

Parâmetros

  • html: Text — O fragmento HTML a colocar, como texto em <b>negrito</b>. Não adicione o cabeçalho HTML da área de transferência; ele é adicionado automaticamente.

Retorna

true se o HTML e sua cópia em texto sem formatação foram colocados na área de transferência; false se a área de transferência estava ocupada.

ClipboardSetRtf​

ClipboardSetRtf(rtf: Text) → Bool

Coloca rich text (RTF) na área de transferência, substituindo o conteúdo atual, para que colar no WordPad, Word ou Outlook mantenha a formatação. Uma cópia das palavras em texto sem formatação também é adicionada, para programas que só colam texto.

Parâmetros

  • rtf: Text — Um documento RTF completo como texto. Qualquer caractere pode ser digitado diretamente; os caracteres fora do ASCII simples são escritos como escapes Unicode do RTF automaticamente.

Retorna

true se o RTF e sua cópia em texto sem formatação foram colocados na área de transferência; false se a área de transferência estava ocupada.

ClipboardSetText​

ClipboardSetText(text: Text) → Bool · Simples

Coloca texto na área de transferência, substituindo o que houver nela, pronto para colar em qualquer programa.

Parâmetros

  • text: Text — O texto a colocar na área de transferência.

Retorna

true se o texto foi colocado na área de transferência; false se outro programa a manteve ocupada.

2 exemplos: Extrair um valor de um texto copiado com uma expressão regular, Juntar as linhas da área de transferência em uma só

Context​

ContextGetActionName​

ContextGetActionName() → Text

Retorna o nome da ação em execução. Um evento global retorna Global_Event_ seguido do id do evento, como Global_Event_release.

Parâmetros

Sem parâmetros.

Retorna

O nome da ação, um nome Global_Event_ para um evento global, ou texto vazio em um script de timer, monitoramento de pasta ou monitor serial.

1 exemplo: Tudo o que o contexto do gatilho sabe

ContextGetApplicationName​

ContextGetApplicationName() → Text

Retorna o nome do grupo de aplicativos cuja ação está em execução, para uma ação disparada por um gesto, uma tecla de atalho ou uma expansão de texto.

Parâmetros

Sem parâmetros.

Retorna

O nome do grupo de aplicativos (normalmente Global para o grupo global), ou texto vazio para um script de evento global, timer, monitoramento de pasta ou monitor serial.

4 exemplos: Preencher um modelo e colá-lo, Tudo o que o contexto do gatilho sabe, Deixar passar um desenho não reconhecido, Acrescentar a um arquivo de log

ContextGetBoundingBoxHeight​

ContextGetBoundingBoxHeight() → Integer

Retorna a altura do retângulo em torno de todo o gesto desenhado, em pixels. Fora de um gesto, retorna 0.

Parâmetros

Sem parâmetros.

Retorna

A altura em pixels, ou 0 fora de um gesto.

2 exemplos: Tudo o que o contexto do gatilho sabe, Capturar a área que você circulou

ContextGetBoundingBoxWidth​

ContextGetBoundingBoxWidth() → Integer

Retorna a largura do retângulo em torno de todo o gesto desenhado, em pixels. Fora de um gesto, retorna 0.

Parâmetros

Sem parâmetros.

Retorna

A largura em pixels, ou 0 fora de um gesto.

2 exemplos: Tudo o que o contexto do gatilho sabe, Capturar a área que você circulou

ContextGetBoundingBoxX​

ContextGetBoundingBoxX() → Integer

Retorna a borda esquerda do retângulo em torno de todo o gesto desenhado, em pixels da tela virtual. Fora de um gesto, retorna 0.

Parâmetros

Sem parâmetros.

Retorna

A borda esquerda em pixels da tela virtual, ou 0 fora de um gesto.

2 exemplos: Tudo o que o contexto do gatilho sabe, Capturar a área que você circulou

ContextGetBoundingBoxY​

ContextGetBoundingBoxY() → Integer

Retorna a borda superior do retângulo em torno de todo o gesto desenhado, em pixels da tela virtual. Fora de um gesto, retorna 0.

Parâmetros

Sem parâmetros.

Retorna

A borda superior em pixels da tela virtual, ou 0 fora de um gesto.

2 exemplos: Tudo o que o contexto do gatilho sabe, Capturar a área que você circulou

ContextGetButtonState​

ContextGetButtonState() → Text

Retorna se um evento global de botão do mouse foi disparado ao pressionar o botão ou ao soltá-lo. Só o script de um evento global de botão do mouse recebe um valor.

Parâmetros

Sem parâmetros.

Retorna

'down' ao pressionar, 'up' ao soltar, ou texto vazio para qualquer outro gatilho, inclusive um gesto.

ContextGetControl​

ContextGetControl() → Window

Retorna o controle exato a que o gatilho se destinava, como uma caixa de edição sob o gesto ou o mouse, ou a janela com foco para uma tecla de atalho ou expansão de texto. Use ContextGetWindow para a janela do aplicativo.

Parâmetros

Sem parâmetros.

Retorna

O controle como Window, ou uma janela nula quando o gatilho não tem janela, como em um script de timer, monitoramento de pasta, monitor serial ou Load.

ContextGetGestureName​

ContextGetGestureName() → Text

Retorna o nome do gesto desenhado para executar esta ação. É o nome do próprio gesto, não o da ação; consulte ContextGetActionName.

Parâmetros

Sem parâmetros.

Retorna

O nome do gesto, ou texto vazio fora de um gesto.

2 exemplos: Tudo o que o contexto do gatilho sabe, Acrescentar a um arquivo de log

ContextGetPointCount​

ContextGetPointCount() → Integer

Retorna quantas posições do cursor foram registradas ao longo do gesto desenhado. Leia cada uma com ContextGetPointX e ContextGetPointY.

Parâmetros

Sem parâmetros.

Retorna

O número de pontos, ou 0 fora de um gesto.

3 exemplos: Comprimento do traço de um gesto, Tudo o que o contexto do gatilho sabe, Para que lado o traço foi?

ContextGetPointX​

ContextGetPointX(index: Integer) → Integer

Retorna a posição horizontal na tela de um ponto registrado do gesto desenhado, em pixels da tela virtual.

Parâmetros

  • index: Integer — Número do ponto, a partir de zero, de 0 a ContextGetPointCount() menos 1. O ponto 0 é onde o gesto começou.

Retorna

A coordenada x, ou 0 se index estiver fora do intervalo ou se a ação não foi disparada por um gesto.

2 exemplos: Comprimento do traço de um gesto, Para que lado o traço foi?

ContextGetPointY​

ContextGetPointY(index: Integer) → Integer

Retorna a posição vertical na tela de um ponto registrado do gesto desenhado, em pixels da tela virtual.

Parâmetros

  • index: Integer — Número do ponto, a partir de zero, de 0 a ContextGetPointCount() menos 1. O ponto 0 é onde o gesto começou.

Retorna

A coordenada y, ou 0 se index estiver fora do intervalo ou se a ação não foi disparada por um gesto.

2 exemplos: Comprimento do traço de um gesto, Para que lado o traço foi?

ContextGetSerialMonitorName​

ContextGetSerialMonitorName() → Text

Retorna o nome do monitor serial cuja linha recebida iniciou este script, conforme passado a SerialMonitorCreate. Só o script de um monitor serial recebe um valor.

Parâmetros

Sem parâmetros.

Retorna

O nome do monitor, ou texto vazio para qualquer outro gatilho.

ContextGetSerialPortName​

ContextGetSerialPortName() → Text

Retorna a porta COM, como COM3, em que a linha recebida chegou. Só o script de um monitor serial recebe um valor.

Parâmetros

Sem parâmetros.

Retorna

O nome da porta, ou texto vazio para qualquer outro gatilho.

ContextGetSerialTextLine​

ContextGetSerialTextLine() → Text

Retorna a linha de texto que chegou pela porta serial e iniciou este script, como a leitura de um sensor que um Arduino enviou com Serial.println. A quebra de linha final é removida.

Parâmetros

Sem parâmetros.

Retorna

A linha recebida sem o terminador, ou texto vazio para qualquer outro gatilho.

2 exemplos: Mapear os botões de um dispositivo serial para teclas de mídia, Transformar um botão giratório de Arduino em controle de volume

ContextGetStrokeButton​

ContextGetStrokeButton() → Integer

Retorna o botão do mouse que desenhou o gesto, ou que disparou um evento global de botão do mouse, como uma constante MouseButton: MouseButton.Primary ou MouseButton.Secondary para os botões que o Windows trata como clique esquerdo e clique direito, após qualquer troca entre botão principal e secundário; caso contrário, MouseButton.Middle, MouseButton.X1 ou MouseButton.X2. Passe-o para MouseClick ou MouseButtonDown para pressionar o mesmo botão.

Parâmetros

Sem parâmetros.

Retorna

Um valor MouseButton como MouseButton.Secondary, ou -1 para qualquer outro gatilho.

2 exemplos: Tudo o que o contexto do gatilho sabe, Ramificar conforme o botão do traço

ContextGetWatchAction​

ContextGetWatchAction() → Text

Retorna o que aconteceu na pasta monitorada para iniciar este script: 'created', 'deleted', 'modified', 'renamed-old-name', 'renamed-new-name' ou 'overflow'.

Parâmetros

Sem parâmetros.

Retorna

O tipo de alteração, ou texto vazio para qualquer outro gatilho. 'overflow' significa que chegaram alterações demais de uma vez e a pasta precisa ser verificada novamente.

1 exemplo: Monitorar uma pasta

ContextGetWatchName​

ContextGetWatchName() → Text

Retorna o nome do monitoramento de pasta que iniciou este script, conforme passado a FolderWatchCreate. Só o script de um monitoramento de pasta recebe um valor.

Parâmetros

Sem parâmetros.

Retorna

O nome do monitoramento, ou texto vazio para qualquer outro gatilho.

ContextGetWatchPath​

ContextGetWatchPath() → Text

Retorna o caminho do arquivo ou da pasta que mudou e iniciou este script de monitoramento de pasta, relativo à pasta monitorada.

Parâmetros

Sem parâmetros.

Retorna

O caminho do item alterado relativo à pasta monitorada, ou texto vazio para uma alteração 'overflow' ou qualquer outro gatilho.

1 exemplo: Monitorar uma pasta

ContextGetWindow​

ContextGetWindow() → Window

Retorna a janela do aplicativo a que o gatilho se destinava: a janela de nível superior em torno do controle sob o gesto ou o mouse, ou em torno do controle com foco para uma tecla de atalho ou expansão de texto.

Parâmetros

Sem parâmetros.

Retorna

A janela, ou uma janela nula quando o gatilho não tem janela, como em um script de timer, monitoramento de pasta, monitor serial ou Load.

16 exemplos: Um gesto, várias opções, Alternar a maximização da janela do gesto, Fixar uma janela por cima, Alternar a transparência da janela em ciclo, Encaixar uma janela na célula de uma grade 3×2 sob o cursor, Jogar uma janela para o próximo monitor, Lembrar e restaurar a posição de uma janela, Inspecionar os controles filhos de uma janela, Esconder uma janela na bandeja, Tudo o que o contexto do gatilho sabe, Ramificar conforme o botão do traço, Confinar o cursor a uma janela por 5 segundos, Mudar o comportamento enquanto Ctrl está pressionada, Uma lista guardada no Storage, Enviar uma janela para um monitor específico, Snippets como funções reutilizáveis

ContextRelayGesture​

ContextRelayGesture() → Bool

Reproduz o gesto desenhado como um arrasto real do mouse, com o mesmo botão e pelo mesmo caminho, para que o aplicativo abaixo o receba, por exemplo para selecionar texto. A entrada real fica retida durante o arrasto.

Parâmetros

Sem parâmetros.

Retorna

true se o arrasto inteiro foi enviado; false fora de um gesto ou se o Windows rejeitou parte da entrada.

1 exemplo: Deixar passar um desenho não reconhecido

DateTime​

DateTimeFormat​

DateTimeFormat(iso: Text, style: Integer) → Text · Simples

Formata uma data e hora como texto legível no formato regional do usuário, ou como um FileStamp ordenável. Uma hora com Z ou deslocamento UTC é convertida antes para a hora local.

Parâmetros

  • iso: Text — Uma data e hora no formato ISO 8601, como DateTimeGetNow a retorna (2026-10-05T14:05:09-04:00). Uma data sozinha significa meia-noite; sem Z ou deslocamento, é considerada hora local. Anos de 1601 a 9999.
  • style: Integer — Uma constante DateTimeStyle, como DateTimeStyle.ShortDate, DateTimeStyle.LongDateTime ou DateTimeStyle.FileStamp. Qualquer outro valor interrompe a ação com um erro.

Retorna

O texto formatado, como 20261005-140509 para DateTimeStyle.FileStamp, ou texto vazio se iso estiver vazio. Texto que não seja ISO 8601 interrompe a ação com um erro.

1 exemplo: A data de hoje e um nome de arquivo com carimbo de data e hora

DateTimeGetNow​

DateTimeGetNow() → Text · Simples

Retorna a data e hora locais atuais como texto ISO 8601, com precisão de segundos e com o deslocamento UTC. Passe-a para DateTimeFormat ou DateTimeGetPart.

Parâmetros

Sem parâmetros.

Retorna

Texto como 2026-10-05T14:05:09-04:00, ou texto vazio se o Windows não conseguir informar o fuso horário.

1 exemplo: A data de hoje e um nome de arquivo com carimbo de data e hora

DateTimeGetPart​

DateTimeGetPart(iso: Text, part: Integer) → Integer

Retorna uma parte de uma data e hora como número: ano, mês, dia, hora, minuto, segundo ou dia da semana, na hora local.

Parâmetros

  • iso: Text — Uma data e hora no formato ISO 8601, como DateTimeGetNow a retorna. Uma hora com Z ou deslocamento UTC é convertida para a hora local; sem ele, é considerada hora local.
  • part: Integer — Uma constante DateTimePart, como DateTimePart.Hour ou DateTimePart.Weekday. Qualquer outro valor interrompe a ação com um erro.

Retorna

O valor da parte: mês de 1 a 12, hora de 0 a 23, dia da semana de 1 (segunda-feira) a 7 (domingo). -1 se iso estiver vazio. Texto que não seja ISO 8601 interrompe a ação com um erro.

1 exemplo: A data de hoje e um nome de arquivo com carimbo de data e hora

Display​

DisplayGetMonitorDpiFromPoint​

DisplayGetMonitorDpiFromPoint(x: Integer, y: Integer) → Integer

Retorna o DPI que o Windows usa no momento para o monitor que contém um ponto da tela. Um ponto fora de todos os monitores usa o monitor mais próximo.

Parâmetros

  • x: Integer — Posição horizontal na tela, em pixels.
  • y: Integer — Posição vertical na tela, em pixels.

Retorna

O DPI, como 96 com escala de 100 por cento ou 144 com 150 por cento. Se o Windows não conseguir informá-lo, o DPI do sistema.

DisplayGetPixelColorFromPoint​

DisplayGetPixelColorFromPoint(x: Integer, y: Integer) → Integer

Retorna a cor do pixel da tela em um ponto, como mostrada no momento no monitor.

Parâmetros

  • x: Integer — Posição horizontal do pixel na tela, em pixels.
  • y: Integer — Posição vertical do pixel na tela, em pixels.

Retorna

A cor como Integer no formato 0xRRGGBB (vermelho no byte mais alto, azul no mais baixo), ou -1 se o ponto estiver fora de todos os monitores ou se a tela não puder ser lida.

1 exemplo: Ler a cor do pixel sob o cursor

DisplayMonitorEnumeratedAll​

DisplayMonitorEnumeratedAll() → Integer

Tira um instantâneo de todos os monitores conectados, ordenados da esquerda para a direita e depois de cima para baixo, para as funções internas DisplayMonitorGetEnumerated lerem por índice. Chame-a novamente depois que os monitores mudarem.

Parâmetros

Sem parâmetros.

Retorna

O número de monitores no instantâneo. Os índices válidos vão de 0 a esse número menos 1.

2 exemplos: Listar os monitores, Enviar uma janela para um monitor específico

DisplayMonitorExistsByName​

DisplayMonitorExistsByName(name: Text) → Bool

Verifica se um monitor salvo por nome está conectado agora. Use-a antes das funções internas de retângulo FromName, que retornam 0 tanto para um monitor ausente quanto para uma coordenada 0 real.

Parâmetros

  • name: Text — Um caminho de dispositivo do monitor (a opção confiável, obtida com DisplayMonitorGetDevicePathFromPoint) ou um nome de modelo como DELL U2720Q. Não diferencia maiúsculas de minúsculas; uma correspondência exata de caminho de dispositivo prevalece sobre um nome de modelo.

Retorna

true se um monitor conectado corresponder ao nome; false se nenhum corresponder ou se name estiver vazio.

DisplayMonitorGetDevicePathFromPoint​

DisplayMonitorGetDevicePathFromPoint(x: Integer, y: Integer) → Text

Retorna o caminho de dispositivo do monitor que contém um ponto da tela: um nome exclusivo para salvar e passar depois às funções internas FromName. Ele muda se o monitor for ligado a outra porta de vídeo.

Parâmetros

  • x: Integer — Posição horizontal na tela, em pixels.
  • y: Integer — Posição vertical na tela, em pixels.

Retorna

O caminho de dispositivo, ou texto vazio se o Windows não conseguir identificar o monitor. Um ponto fora de todos os monitores usa o monitor mais próximo.

DisplayMonitorGetEnumeratedDevicePathAt​

DisplayMonitorGetEnumeratedDevicePathAt(index: Integer) → Text

Retorna o caminho de dispositivo, um nome exclusivo para salvar, de um monitor no último instantâneo de DisplayMonitorEnumeratedAll.

Parâmetros

  • index: Integer — Posição do monitor, a partir de zero, no último instantâneo de DisplayMonitorEnumeratedAll (da esquerda para a direita, depois de cima para baixo).

Retorna

O caminho de dispositivo, ou texto vazio se index estiver fora do intervalo ou se os monitores mudaram desde o instantâneo.

DisplayMonitorGetEnumeratedDpiAt​

DisplayMonitorGetEnumeratedDpiAt(index: Integer) → Integer

Retorna o DPI de um monitor no último instantâneo de DisplayMonitorEnumeratedAll, como era quando o instantâneo foi tirado.

Parâmetros

  • index: Integer — Posição do monitor, a partir de zero, no último instantâneo de DisplayMonitorEnumeratedAll (da esquerda para a direita, depois de cima para baixo).

Retorna

O DPI, como 96 com escala de 100 por cento ou 144 com 150 por cento, ou 0 se index estiver fora do intervalo.

1 exemplo: Listar os monitores

DisplayMonitorGetEnumeratedFriendlyNameAt​

DisplayMonitorGetEnumeratedFriendlyNameAt(index: Integer) → Text

Retorna o nome de modelo que um monitor informa, como DELL U2720Q, para um monitor no último instantâneo de DisplayMonitorEnumeratedAll. Dois monitores idênticos informam o mesmo nome.

Parâmetros

  • index: Integer — Posição do monitor, a partir de zero, no último instantâneo de DisplayMonitorEnumeratedAll (da esquerda para a direita, depois de cima para baixo).

Retorna

O nome de modelo, ou texto vazio se index estiver fora do intervalo, se o monitor não informar nome (comum em telas integradas de notebooks) ou se os monitores mudaram desde o instantâneo.

1 exemplo: Listar os monitores

DisplayMonitorGetEnumeratedHeightAt​

DisplayMonitorGetEnumeratedHeightAt(index: Integer, workArea: Bool) → Integer

Retorna a altura de um monitor no último instantâneo de DisplayMonitorEnumeratedAll, da área total ou da área de trabalho, como era quando o instantâneo foi tirado.

Parâmetros

  • index: Integer — Posição do monitor, a partir de zero, no último instantâneo de DisplayMonitorEnumeratedAll (da esquerda para a direita, depois de cima para baixo).
  • workArea: Bool — true para a área de trabalho, que exclui a barra de tarefas e as barras de ferramentas encaixadas; false para o monitor inteiro.

Retorna

A altura em pixels, ou 0 se index estiver fora do intervalo.

1 exemplo: Listar os monitores

DisplayMonitorGetEnumeratedWidthAt​

DisplayMonitorGetEnumeratedWidthAt(index: Integer, workArea: Bool) → Integer

Retorna a largura de um monitor no último instantâneo de DisplayMonitorEnumeratedAll, da área total ou da área de trabalho, como era quando o instantâneo foi tirado.

Parâmetros

  • index: Integer — Posição do monitor, a partir de zero, no último instantâneo de DisplayMonitorEnumeratedAll (da esquerda para a direita, depois de cima para baixo).
  • workArea: Bool — true para a área de trabalho, que exclui a barra de tarefas e as barras de ferramentas encaixadas; false para o monitor inteiro.

Retorna

A largura em pixels, ou 0 se index estiver fora do intervalo.

1 exemplo: Listar os monitores

DisplayMonitorGetEnumeratedXAt​

DisplayMonitorGetEnumeratedXAt(index: Integer, workArea: Bool) → Integer

Retorna a borda esquerda de um monitor no último instantâneo de DisplayMonitorEnumeratedAll, da área total ou da área de trabalho, como era quando o instantâneo foi tirado.

Parâmetros

  • index: Integer — Posição do monitor, a partir de zero, no último instantâneo de DisplayMonitorEnumeratedAll (da esquerda para a direita, depois de cima para baixo).
  • workArea: Bool — true para a área de trabalho, que exclui a barra de tarefas e as barras de ferramentas encaixadas; false para o monitor inteiro.

Retorna

A borda esquerda em pixels da tela (negativa para um monitor à esquerda do principal), ou 0 se index estiver fora do intervalo. 0 também é uma borda real; por isso, compare index com o número de monitores.

DisplayMonitorGetEnumeratedYAt​

DisplayMonitorGetEnumeratedYAt(index: Integer, workArea: Bool) → Integer

Retorna a borda superior de um monitor no último instantâneo de DisplayMonitorEnumeratedAll, da área total ou da área de trabalho, como era quando o instantâneo foi tirado.

Parâmetros

  • index: Integer — Posição do monitor, a partir de zero, no último instantâneo de DisplayMonitorEnumeratedAll (da esquerda para a direita, depois de cima para baixo).
  • workArea: Bool — true para a área de trabalho, que exclui a barra de tarefas e as barras de ferramentas encaixadas; false para o monitor inteiro.

Retorna

A borda superior em pixels da tela (negativa para um monitor acima do principal), ou 0 se index estiver fora do intervalo. 0 também é uma borda real; por isso, compare index com o número de monitores.

DisplayMonitorGetFriendlyNameFromPoint​

DisplayMonitorGetFriendlyNameFromPoint(x: Integer, y: Integer) → Text

Retorna o nome de modelo, como DELL U2720Q, do monitor que contém um ponto da tela. Legível, mas não exclusivo: dois monitores idênticos informam o mesmo nome.

Parâmetros

  • x: Integer — Posição horizontal na tela, em pixels.
  • y: Integer — Posição vertical na tela, em pixels.

Retorna

O nome de modelo, ou texto vazio se o monitor não informar nenhum (comum em telas integradas de notebooks). Um ponto fora de todos os monitores usa o monitor mais próximo.

DisplayMonitorGetRectHeightFromName​

DisplayMonitorGetRectHeightFromName(name: Text, workArea: Bool) → Integer

Retorna a altura de um monitor conectado, encontrado pelo caminho de dispositivo salvo ou pelo nome de modelo, da área total ou da área de trabalho.

Parâmetros

  • name: Text — Um caminho de dispositivo do monitor (a opção confiável) ou um nome de modelo como DELL U2720Q. Não diferencia maiúsculas de minúsculas; uma correspondência exata de caminho de dispositivo prevalece sobre um nome de modelo.
  • workArea: Bool — true para a área de trabalho, que exclui a barra de tarefas e as barras de ferramentas encaixadas; false para o monitor inteiro.

Retorna

A altura em pixels, ou 0 se nenhum monitor conectado corresponder ao nome.

DisplayMonitorGetRectHeightFromPoint​

DisplayMonitorGetRectHeightFromPoint(x: Integer, y: Integer, workArea: Bool) → Integer

Retorna a altura do monitor que contém um ponto da tela, da área total ou da área de trabalho. Um ponto fora de todos os monitores usa o monitor mais próximo.

Parâmetros

  • x: Integer — Posição horizontal na tela, em pixels.
  • y: Integer — Posição vertical na tela, em pixels.
  • workArea: Bool — true para a área de trabalho, que exclui a barra de tarefas e as barras de ferramentas encaixadas; false para o monitor inteiro.

Retorna

A altura em pixels.

2 exemplos: Encaixar a janela ativa na metade esquerda do seu monitor, Encaixar uma janela na célula de uma grade 3×2 sob o cursor

DisplayMonitorGetRectWidthFromName​

DisplayMonitorGetRectWidthFromName(name: Text, workArea: Bool) → Integer

Retorna a largura de um monitor conectado, encontrado pelo caminho de dispositivo salvo ou pelo nome de modelo, da área total ou da área de trabalho.

Parâmetros

  • name: Text — Um caminho de dispositivo do monitor (a opção confiável) ou um nome de modelo como DELL U2720Q. Não diferencia maiúsculas de minúsculas; uma correspondência exata de caminho de dispositivo prevalece sobre um nome de modelo.
  • workArea: Bool — true para a área de trabalho, que exclui a barra de tarefas e as barras de ferramentas encaixadas; false para o monitor inteiro.

Retorna

A largura em pixels, ou 0 se nenhum monitor conectado corresponder ao nome.

DisplayMonitorGetRectWidthFromPoint​

DisplayMonitorGetRectWidthFromPoint(x: Integer, y: Integer, workArea: Bool) → Integer

Retorna a largura do monitor que contém um ponto da tela, da área total ou da área de trabalho. Um ponto fora de todos os monitores usa o monitor mais próximo.

Parâmetros

  • x: Integer — Posição horizontal na tela, em pixels.
  • y: Integer — Posição vertical na tela, em pixels.
  • workArea: Bool — true para a área de trabalho, que exclui a barra de tarefas e as barras de ferramentas encaixadas; false para o monitor inteiro.

Retorna

A largura em pixels.

3 exemplos: Encadeamento else-if, Encaixar a janela ativa na metade esquerda do seu monitor, Encaixar uma janela na célula de uma grade 3×2 sob o cursor

DisplayMonitorGetRectXFromName​

DisplayMonitorGetRectXFromName(name: Text, workArea: Bool) → Integer

Retorna a borda esquerda de um monitor conectado, encontrado pelo caminho de dispositivo salvo ou pelo nome de modelo, da área total ou da área de trabalho.

Parâmetros

  • name: Text — Um caminho de dispositivo do monitor (a opção confiável) ou um nome de modelo como DELL U2720Q. Não diferencia maiúsculas de minúsculas; uma correspondência exata de caminho de dispositivo prevalece sobre um nome de modelo.
  • workArea: Bool — true para a área de trabalho, que exclui a barra de tarefas e as barras de ferramentas encaixadas; false para o monitor inteiro.

Retorna

A borda esquerda em pixels da tela, ou 0 se nenhum monitor conectado corresponder ao nome. 0 também é uma borda real; por isso, verifique antes com DisplayMonitorExistsByName.

DisplayMonitorGetRectXFromPoint​

DisplayMonitorGetRectXFromPoint(x: Integer, y: Integer, workArea: Bool) → Integer

Retorna a borda esquerda do monitor que contém um ponto da tela, da área total ou da área de trabalho. Um ponto fora de todos os monitores usa o monitor mais próximo.

Parâmetros

  • x: Integer — Posição horizontal na tela, em pixels.
  • y: Integer — Posição vertical na tela, em pixels.
  • workArea: Bool — true para a área de trabalho, que exclui a barra de tarefas e as barras de ferramentas encaixadas; false para o monitor inteiro.

Retorna

A borda esquerda em pixels da tela; negativa para um monitor à esquerda do principal.

3 exemplos: Encadeamento else-if, Encaixar a janela ativa na metade esquerda do seu monitor, Encaixar uma janela na célula de uma grade 3×2 sob o cursor

DisplayMonitorGetRectYFromName​

DisplayMonitorGetRectYFromName(name: Text, workArea: Bool) → Integer

Retorna a borda superior de um monitor conectado, encontrado pelo caminho de dispositivo salvo ou pelo nome de modelo, da área total ou da área de trabalho.

Parâmetros

  • name: Text — Um caminho de dispositivo do monitor (a opção confiável) ou um nome de modelo como DELL U2720Q. Não diferencia maiúsculas de minúsculas; uma correspondência exata de caminho de dispositivo prevalece sobre um nome de modelo.
  • workArea: Bool — true para a área de trabalho, que exclui a barra de tarefas e as barras de ferramentas encaixadas; false para o monitor inteiro.

Retorna

A borda superior em pixels da tela, ou 0 se nenhum monitor conectado corresponder ao nome. 0 também é uma borda real; por isso, verifique antes com DisplayMonitorExistsByName.

DisplayMonitorGetRectYFromPoint​

DisplayMonitorGetRectYFromPoint(x: Integer, y: Integer, workArea: Bool) → Integer

Retorna a borda superior do monitor que contém um ponto da tela, da área total ou da área de trabalho. Um ponto fora de todos os monitores usa o monitor mais próximo.

Parâmetros

  • x: Integer — Posição horizontal na tela, em pixels.
  • y: Integer — Posição vertical na tela, em pixels.
  • workArea: Bool — true para a área de trabalho, que exclui a barra de tarefas e as barras de ferramentas encaixadas; false para o monitor inteiro.

Retorna

A borda superior em pixels da tela; negativa para um monitor acima do principal.

2 exemplos: Encaixar a janela ativa na metade esquerda do seu monitor, Encaixar uma janela na célula de uma grade 3×2 sob o cursor

Engine​

EngineConsumePhysicalInput​

EngineConsumePhysicalInput(enable: Bool, timeoutSeconds: Integer) → Bool

Impede que a entrada real de mouse e teclado do usuário chegue a qualquer janela, ou encerra esse bloqueio. A entrada enviada por scripts continua funcionando, e o bloqueio termina sozinho após o tempo limite.

Parâmetros

  • enable: Bool — true para iniciar ou reiniciar o bloqueio da entrada real; false para encerrar o bloqueio, seja qual for o script que o iniciou.
  • timeoutSeconds: Integer — A duração máxima do bloqueio, em segundos; 1 ou mais quando enable é true. Valores maiores são reduzidos ao máximo definido na página de configurações Scripts (120 segundos por padrão). Ignorado quando enable é false.

Retorna

Sempre true. Com enable definido como true, um timeoutSeconds de 0 ou menos interrompe o script com um erro.

EngineDisable​

EngineDisable() → Bool · Simples

Desativa o mecanismo, da mesma forma que desativá-lo pelo ícone da bandeja, até que EngineEnable ou a bandeja o reative. A mudança ocorre logo depois que a chamada retorna. Não faz nada no Modo de segurança.

Parâmetros

Sem parâmetros.

Retorna

true se a solicitação foi enviada; false se o mecanismo ainda não terminou de iniciar.

1 exemplo: Estado do mecanismo

EngineDisableNextGesture​

EngineDisableNextGesture() → Bool · Simples

Deixa o próximo pressionamento de um botão de desenho passar direto para o aplicativo em vez de iniciar um gesto, uma única vez. Não tem efeito enquanto o mecanismo estiver desativado.

Parâmetros

Sem parâmetros.

Retorna

Sempre true.

1 exemplo: Deixar passar o próximo arrastar com o botão direito

EngineEnable​

EngineEnable() → Bool · Simples

Reativa o mecanismo depois de EngineDisable ou de uma desativação pelo ícone da bandeja. A mudança ocorre logo depois que a chamada retorna. Não faz nada no Modo de segurança.

Parâmetros

Sem parâmetros.

Retorna

true se a solicitação foi enviada; false se o mecanismo ainda não terminou de iniciar.

EngineExit​

EngineExit() → Bool · Simples

Fecha o mecanismo com um encerramento normal, igual a Sair no menu da bandeja: as janelas ocultas na bandeja são restauradas e a interface de configuração é fechada. O encerramento começa logo depois que a chamada retorna.

Parâmetros

Sem parâmetros.

Retorna

true se a solicitação de encerramento foi enviada; false se o mecanismo ainda não terminou de iniciar.

EngineIsDisabled​

EngineIsDisabled() → Bool

Retorna se o mecanismo está desativado agora, seja por EngineDisable ou pelo ícone da bandeja, seja automaticamente para o aplicativo em foco.

Parâmetros

Sem parâmetros.

Retorna

true se o mecanismo estiver desativado; false se estiver ativo.

1 exemplo: Estado do mecanismo

EngineIsSafeMode​

EngineIsSafeMode() → Bool

Retorna se o mecanismo foi iniciado no Modo de segurança. No Modo de segurança, só podem ser executados scripts iniciados pelo console de diagnóstico.

Parâmetros

Sem parâmetros.

Retorna

true no Modo de segurança; caso contrário, false.

1 exemplo: Estado do mecanismo

EngineReload​

EngineReload() → Bool · Simples

Recarrega a configuração do disco sem reiniciar, como Recarregar configuração no menu da bandeja. Aguarda até 3 segundos. Todos os outros scripts em execução são interrompidos; este continua.

Parâmetros

Sem parâmetros.

Retorna

true assim que a nova configuração estiver em uso; false se não foi possível carregá-la ou se o recarregamento levou mais de 3 segundos.

EngineStopAllActions​

EngineStopAllActions() → Bool · Simples

Pede que todas as ações e scripts em execução parem, inclusive o que fez a chamada. Nada é encerrado à força: cada script para no próximo passo, então quem chamou pode avançar um pouco antes.

Parâmetros

Sem parâmetros.

Retorna

Sempre true.

File​

FileAppendText​

FileAppendText(path: Text, text: Text) → Bool

Adiciona texto ao final de um arquivo de texto, criando o arquivo se ele não existir. Prático para logs. O texto é gravado em UTF-8 e nenhuma quebra de linha é adicionada automaticamente.

Parâmetros

  • path: Text — Caminho completo do arquivo. A pasta já deve existir.
  • text: Text — O texto a adicionar. Termine-o com '\n' para manter uma entrada por linha.

Retorna

true se o texto foi gravado; false se a pasta não existir, se o arquivo estiver bloqueado ou se o início do arquivo existente parecer conter dados binários.

1 exemplo: Acrescentar a um arquivo de log

FileCopy​

FileCopy(source: Text, destination: Text, overwrite: Bool) → Bool

Copia um arquivo de qualquer tipo para um novo caminho. A pasta de destino já deve existir.

Parâmetros

  • source: Text — Caminho completo do arquivo a copiar.
  • destination: Text — Caminho completo da nova cópia, incluindo o nome do arquivo.
  • overwrite: Bool — true para substituir um arquivo existente em destination; false para mantê-lo e retornar false.

Retorna

true se o arquivo foi copiado; false se a origem não existir, se o destino existir e overwrite for false, ou se a cópia falhar.

1 exemplo: Fazer backup de um arquivo antes de editá-lo

FileCreate​

FileCreate(path: Text, text: Text) → Bool

Cria um novo arquivo de texto com o conteúdo fornecido, gravado em UTF-8. Recusa se já existir algo nesse caminho; use FileEditText para substituir o conteúdo de um arquivo existente.

Parâmetros

  • path: Text — Caminho completo do novo arquivo. A pasta já deve existir.
  • text: Text — O conteúdo do arquivo. Texto vazio cria um arquivo vazio.

Retorna

true se o arquivo foi criado; false se já existir um arquivo ou uma pasta ali, ou se o arquivo não puder ser gravado.

2 exemplos: A data de hoje e um nome de arquivo com carimbo de data e hora, Acrescentar a um arquivo de log

FileDelete​

FileDelete(path: Text) → Bool

Exclui um arquivo permanentemente; ele não vai para a Lixeira. Um arquivo que já não existe conta como sucesso. Uma pasta nunca é excluída; para isso, use FolderDelete.

Parâmetros

  • path: Text — Caminho completo do arquivo a excluir.

Retorna

true se o arquivo não existe mais, inclusive quando nunca existiu; false se o caminho for uma pasta, ou se o arquivo estiver bloqueado ou o acesso for negado.

FileEditText​

FileEditText(path: Text, text: Text) → Bool

Substitui todo o conteúdo de um arquivo de texto existente, gravado em UTF-8. Recusa um arquivo que pareça conter dados binários. Use FileCreate para um novo arquivo.

Parâmetros

  • path: Text — Caminho completo de um arquivo de texto existente.
  • text: Text — O novo conteúdo, que substitui tudo no arquivo.

Retorna

true se o arquivo foi regravado; false se ele não existir, se o início dele parecer conter dados binários ou se não puder ser gravado.

1 exemplo: Fazer backup de um arquivo antes de editá-lo

FileExists​

FileExists(path: Text) → Bool

Verifica se existe um arquivo em um caminho. Uma pasta nesse caminho não conta; use FolderExists para pastas.

Parâmetros

  • path: Text — Caminho completo do arquivo a verificar.

Retorna

true se existir um arquivo ali; false se não existir nada ou se for uma pasta.

2 exemplos: Acrescentar a um arquivo de log, Fazer backup de um arquivo antes de editá-lo

FileGetCreationDate​

FileGetCreationDate(path: Text) → Text

Retorna quando um arquivo foi criado, como data e hora ISO 8601 em UTC que DateTimeFormat e as outras funções internas DateTime conseguem ler.

Parâmetros

  • path: Text — Caminho completo do arquivo.

Retorna

A hora de criação, como 2026-10-01T18:05:09Z, ou texto vazio se o arquivo não existir ou se o caminho for uma pasta.

FileGetModifiedDate​

FileGetModifiedDate(path: Text) → Text

Retorna quando o conteúdo de um arquivo foi alterado pela última vez, como data e hora ISO 8601 em UTC que DateTimeFormat e as outras funções internas DateTime conseguem ler.

Parâmetros

  • path: Text — Caminho completo do arquivo.

Retorna

A hora da última modificação, como 2026-10-01T18:05:09Z, ou texto vazio se o arquivo não existir ou se o caminho for uma pasta.

1 exemplo: Ler um arquivo e contar as suas linhas

FileGetProductVersion​

FileGetProductVersion(path: Text) → Text

Retorna a versão do produto armazenada em um arquivo de programa ou biblioteca, como um .exe ou .dll. É a versão do produto com o qual o arquivo é distribuído, que pode ser diferente de FileGetVersion.

Parâmetros

  • path: Text — Caminho completo do .exe, .dll ou outro arquivo com informações de versão.

Retorna

A versão como quatro números, como 10.0.22621.1, ou texto vazio se o arquivo não tiver informações de versão ou não existir.

FileGetSize​

FileGetSize(path: Text) → Integer

Retorna o tamanho de um arquivo em bytes, sem abrir nem ler o arquivo.

Parâmetros

  • path: Text — Caminho completo do arquivo.

Retorna

O tamanho em bytes, ou -1 se o arquivo não existir ou se o caminho for uma pasta.

1 exemplo: Ler um arquivo e contar as suas linhas

FileGetVersion​

FileGetVersion(path: Text) → Text

Retorna a versão do arquivo armazenada em um arquivo de programa ou biblioteca, como um .exe ou .dll, como mostrada na guia Detalhes das Propriedades dele.

Parâmetros

  • path: Text — Caminho completo do .exe, .dll ou outro arquivo com informações de versão.

Retorna

A versão como quatro números, como 10.0.22621.1, ou texto vazio se o arquivo não tiver informações de versão ou não existir.

FileMove​

FileMove(source: Text, destination: Text, overwrite: Bool) → Bool

Move um arquivo de qualquer tipo para um novo caminho, o que também pode dar a ele um novo nome, inclusive apenas uma mudança entre maiúsculas e minúsculas. A pasta de destino já deve existir.

Parâmetros

  • source: Text — Caminho completo do arquivo a mover.
  • destination: Text — Caminho completo do novo local do arquivo, incluindo o nome do arquivo.
  • overwrite: Bool — true para substituir em uma única etapa um arquivo existente em destination; false para mantê-lo e retornar false. Um destino que difere da origem apenas em maiúsculas e minúsculas não é um arquivo existente.

Retorna

true se o arquivo foi movido; false se a origem não existir, se o destino existir e overwrite for false, ou se a movimentação falhar.

FileReadText​

FileReadText(path: Text) → Text

Lê um arquivo de texto inteiro e retorna o conteúdo. Entende UTF-8, UTF-16 com marca de ordem de byte e arquivos na página de código herdada do sistema. Recusa arquivos binários.

Parâmetros

  • path: Text — Caminho completo do arquivo de texto.

Retorna

O conteúdo do arquivo, ou texto vazio se o arquivo não existir, não puder ser lido ou parecer conter dados binários.

2 exemplos: Ler um arquivo e contar as suas linhas, Fazer backup de um arquivo antes de editá-lo

FileRename​

FileRename(path: Text, newName: Text) → Bool

Renomeia um arquivo e o mantém na pasta atual. Uma mudança apenas entre maiúsculas e minúsculas, como report.txt para Report.txt, também funciona. Para mover um arquivo para outra pasta, use FileMove.

Parâmetros

  • path: Text — Caminho completo do arquivo a renomear.
  • newName: Text — Somente o novo nome do arquivo, como report-old.txt. Um nome que contenha barra ou barra invertida interrompe o script com um erro.

Retorna

true se o arquivo foi renomeado; false se ele não existir, se já existir outro arquivo ou pasta com o novo nome ou se a renomeação falhar.

Folder​

FolderCreate​

FolderCreate(path: Text) → Bool

Cria uma pasta, incluindo as pastas pai que estiverem faltando. Uma pasta que já existe conta como sucesso.

Parâmetros

  • path: Text — Caminho completo da pasta a criar.

Retorna

true se a pasta existir depois; false se houver um arquivo no caminho ou se a pasta não puder ser criada.

FolderDelete​

FolderDelete(path: Text, recursive: Bool) → Bool

Exclui uma pasta permanentemente; ela não vai para a Lixeira. Com recursive definido como true, tudo o que estiver dentro dela também é excluído. Uma pasta que já não existe conta como sucesso. Um arquivo nunca é excluído; para isso, use FileDelete.

Parâmetros

  • path: Text — Caminho completo da pasta a excluir.
  • recursive: Bool — true para excluir a pasta e tudo o que estiver dentro dela; false para excluí-la somente se estiver vazia.

Retorna

true se a pasta não existe mais; false se o caminho for um arquivo, se a pasta não estiver vazia e recursive for false, ou se algo dentro dela estiver bloqueado ou protegido.

FolderEnumerateAll​

FolderEnumerateAll(path: Text, recursive: Bool) → Integer

Lista os arquivos e as subpastas de uma pasta e retorna quantos são. Leia cada caminho completo com FolderGetEnumeratedPathAt. Subpastas que não podem ser acessadas são ignoradas.

Parâmetros

  • path: Text — Caminho completo da pasta a listar.
  • recursive: Bool — true para listar também tudo o que estiver dentro de todas as subpastas; false para listar somente o conteúdo direto da pasta.

Retorna

O número de entradas encontradas, ou -1 se a pasta não existir ou não puder ser lida.

1 exemplo: Contar os tipos de arquivo em uma pasta

FolderExists​

FolderExists(path: Text) → Bool

Verifica se existe uma pasta em um caminho. Um arquivo nesse caminho não conta; use FileExists para arquivos.

Parâmetros

  • path: Text — Caminho completo da pasta a verificar.

Retorna

true se existir uma pasta ali; false se não existir nada ou se for um arquivo.

FolderGetEnumeratedPathAt​

FolderGetEnumeratedPathAt(index: Integer) → Text

Retorna um caminho completo da lista criada pela última chamada a FolderEnumerateAll nesta execução do script.

Parâmetros

  • index: Integer — Posição na lista, de 0 à contagem retornada por FolderEnumerateAll menos 1.

Retorna

O caminho completo de um arquivo ou pasta, ou texto vazio se index estiver fora do intervalo ou se FolderEnumerateAll não tiver sido chamada.

1 exemplo: Contar os tipos de arquivo em uma pasta

FolderRename​

FolderRename(path: Text, newName: Text) → Bool

Renomeia uma pasta e a mantém, com seu conteúdo, na pasta pai atual. Uma mudança apenas entre maiúsculas e minúsculas também funciona.

Parâmetros

  • path: Text — Caminho completo da pasta a renomear.
  • newName: Text — Somente o novo nome da pasta. Um nome que contenha barra ou barra invertida interrompe o script com um erro.

Retorna

true se a pasta foi renomeada; false se ela não existir, se já existir outro arquivo ou pasta com o novo nome ou se a renomeação falhar, por exemplo porque um arquivo dentro dela está aberto.

FolderWatchCreate​

FolderWatchCreate(name: Text, path: Text, recursive: Bool, filterMask: Integer, script: Text) → Bool

Começa a monitorar uma pasta e executa um script para cada alteração que o Windows informar, como um arquivo criado, alterado, renomeado ou excluído. O monitoramento continua depois que este script termina.

Parâmetros

  • name: Text — Um nome para o monitoramento. Criar um monitoramento com um nome já em uso substitui esse monitoramento. Os nomes diferenciam maiúsculas de minúsculas.
  • path: Text — Caminho completo da pasta a monitorar.
  • recursive: Bool — true para monitorar também todas as subpastas; false para monitorar somente a própria pasta.
  • filterMask: Integer — Os tipos de alteração a informar: constantes FileNotify combinadas com |, como FileNotify.FileName | FileNotify.LastWrite.
  • script: Text — O script a executar para cada alteração, como Text. Ele lê a alteração com ContextGetWatchAction (created, deleted, modified, renamed-old-name, renamed-new-name ou overflow) e ContextGetWatchPath.

Retorna

true se o monitoramento estiver em execução; false se a pasta não existir, não puder ser aberta ou se filterMask for 0.

1 exemplo: Monitorar uma pasta

FolderWatchDelete​

FolderWatchDelete(name: Text) → Bool

Para um monitoramento de pasta criado com FolderWatchCreate, para que o script dele não seja mais executado.

Parâmetros

  • name: Text — O nome passado a FolderWatchCreate. Os nomes diferenciam maiúsculas de minúsculas.

Retorna

true se um monitoramento com esse nome foi encontrado e parado; false se não havia nenhum.

1 exemplo: Monitorar uma pasta

FolderWatchDeleteAll​

FolderWatchDeleteAll() → Bool

Para todos os monitoramentos de pasta criados com FolderWatchCreate, para que nenhum dos scripts deles seja mais executado.

Parâmetros

Sem parâmetros.

Retorna

Sempre true.

FolderWatchGetCount​

FolderWatchGetCount() → Integer

Retorna quantos monitoramentos de pasta estão em execução e tira um instantâneo dos nomes deles para FolderWatchGetEnumeratedNameAt.

Parâmetros

Sem parâmetros.

Retorna

O número de monitoramentos de pasta em execução, ou 0 se não houver nenhum.

FolderWatchGetEnumeratedNameAt​

FolderWatchGetEnumeratedNameAt(index: Integer) → Text

Retorna um nome de monitoramento do instantâneo tirado pela última chamada a FolderWatchGetCount nesta execução do script.

Parâmetros

  • index: Integer — Posição no instantâneo, de 0 à contagem menos 1. A ordem não tem significado.

Retorna

O nome do monitoramento, ou texto vazio se index estiver fora do intervalo ou se FolderWatchGetCount não tiver sido chamada.

GestureProfile​

GestureProfileEnumerateAll​

GestureProfileEnumerateAll() → Integer

Monta uma lista de todos os perfis de gestos da configuração e retorna quantos são. Leia cada um com GestureProfileGetEnumeratedIdAt e GestureProfileGetEnumeratedNameAt.

Parâmetros

Sem parâmetros.

Retorna

O número de perfis de gestos, ou 0 se não houver nenhum.

1 exemplo: Passar para o próximo perfil de gestos

GestureProfileGetActiveId​

GestureProfileGetActiveId() → Text

Retorna o id do perfil de gestos que está ativo agora.

Parâmetros

Sem parâmetros.

Retorna

O id do perfil ativo, ou texto vazio se nenhum perfil estiver ativo.

2 exemplos: Uma notificação do Windows, Passar para o próximo perfil de gestos

GestureProfileGetEnumeratedIdAt​

GestureProfileGetEnumeratedIdAt(index: Integer) → Text

Retorna o id de um perfil da lista que GestureProfileEnumerateAll montou por último neste script. Passe o id para GestureProfileSwitch.

Parâmetros

  • index: Integer — Posição na lista, a partir de zero, de 0 à contagem menos 1.

Retorna

O id do perfil, ou texto vazio se index estiver fora do intervalo ou se GestureProfileEnumerateAll não tiver sido chamada.

1 exemplo: Passar para o próximo perfil de gestos

GestureProfileGetEnumeratedNameAt​

GestureProfileGetEnumeratedNameAt(index: Integer) → Text

Retorna o nome de exibição de um perfil da lista que GestureProfileEnumerateAll montou por último neste script.

Parâmetros

  • index: Integer — Posição na lista, a partir de zero, de 0 à contagem menos 1.

Retorna

O nome do perfil, ou texto vazio se index estiver fora do intervalo ou se GestureProfileEnumerateAll não tiver sido chamada.

1 exemplo: Passar para o próximo perfil de gestos

GestureProfileSwitch​

GestureProfileSwitch(profileId: Text) → Bool · Simples

Muda para outro perfil de gestos, como escolhê-lo no menu da bandeja, e lembra a escolha após reiniciar. A mudança ocorre logo depois que a chamada retorna.

Parâmetros

  • profileId: Text — O id do perfil para o qual mudar, como um obtido com GestureProfileGetEnumeratedIdAt, ou texto vazio para nenhum perfil.

Retorna

true se a solicitação foi enviada; false para um id que nenhum perfil tem, e nada muda. A troca acontece logo depois que a chamada retorna; use GestureProfileGetActiveId para confirmá-la.

1 exemplo: Passar para o próximo perfil de gestos

Keyboard​

KeyboardGetKeyState​

KeyboardGetKeyState(key: Integer) → Integer

Retorna o estado bruto de uma tecla no Windows neste momento. Enquanto outra área de trabalho, como um aviso do UAC ou a tela de bloqueio, estiver na frente, todas as teclas são lidas como soltas. Para um simples sim ou não, use KeyboardIsKeyDown ou KeyboardIsKeyToggled.

Parâmetros

  • key: Integer — Uma constante VirtualKey, como VirtualKey.CapsLock, ou um código de tecla virtual de 0 a 255. Qualquer outro valor interrompe o script com um erro.

Retorna

Um Integer bruto: negativo (bit mais alto definido) quando a tecla está pressionada, e ímpar (bit mais baixo definido) quando uma tecla de bloqueio como Caps Lock está ativada.

1 exemplo: Bits de estado de tecla

KeyboardGetKeyStateAsync​

KeyboardGetKeyStateAsync(key: Integer) → Integer

Retorna o estado bruto de uma tecla no Windows neste exato momento, seja qual for a janela em foco.

Parâmetros

  • key: Integer — Uma constante VirtualKey, como VirtualKey.ShiftKey, ou um código de tecla virtual de 0 a 255. Qualquer outro valor interrompe o script com um erro.

Retorna

Um Integer bruto: negativo (bit mais alto definido) quando a tecla está pressionada agora. O bit mais baixo pode estar definido se a tecla foi pressionada desde uma verificação anterior, o que o Windows não garante.

KeyboardIsKeyDown​

KeyboardIsKeyDown(key: Integer) → Bool

Verifica se uma tecla está pressionada neste momento. Enquanto outra área de trabalho, como um aviso do UAC ou a tela de bloqueio, estiver na frente, todas as teclas são lidas como soltas.

Parâmetros

  • key: Integer — Uma constante VirtualKey, como VirtualKey.ControlKey, ou um código de tecla virtual de 0 a 255. Qualquer outro valor interrompe o script com um erro.

Retorna

true se a tecla estiver pressionada; false se estiver solta.

2 exemplos: Bits de estado de tecla, Mudar o comportamento enquanto Ctrl está pressionada

KeyboardIsKeyToggled​

KeyboardIsKeyToggled(key: Integer) → Bool

Verifica se uma tecla de bloqueio está ativada. Só tem significado para VirtualKey.CapsLock, VirtualKey.NumLock e VirtualKey.Scroll.

Parâmetros

  • key: Integer — Uma constante VirtualKey, como VirtualKey.CapsLock, ou um código de tecla virtual de 0 a 255. Qualquer outro valor interrompe o script com um erro.

Retorna

true se a tecla de bloqueio estiver ativada; false se estiver desativada.

1 exemplo: Bits de estado de tecla

KeyboardKeyDown​

KeyboardKeyDown(key: Integer) → Bool

Pressiona uma tecla e a mantém pressionada até que KeyboardKeyUp a solte. Com a configuração Enviar teclas de mídia e de navegador como comandos ativada, uma tecla de mídia, volume ou navegador envia o comando dela em vez disso.

Parâmetros

  • key: Integer — Uma constante VirtualKey, como VirtualKey.ShiftKey, ou um código de tecla virtual de 0 a 255. Qualquer outro valor interrompe o script com um erro.

Retorna

true se o pressionamento da tecla foi enviado; false se o Windows o bloqueou ou, para uma tecla enviada como comando, se nenhuma janela estiver em foco.

1 exemplo: Shift+clique

KeyboardKeyUp​

KeyboardKeyUp(key: Integer) → Bool

Solta uma tecla pressionada com KeyboardKeyDown. Para uma tecla de mídia, volume ou navegador enviada como comando, não faz nada, pois o comando já foi enviado no pressionamento.

Parâmetros

  • key: Integer — Uma constante VirtualKey, como VirtualKey.ShiftKey, ou um código de tecla virtual de 0 a 255. Qualquer outro valor interrompe o script com um erro.

Retorna

true se a liberação da tecla foi enviada, e sempre true para uma tecla enviada como comando; false se o Windows a bloqueou.

1 exemplo: Shift+clique

KeyboardPressKey​

KeyboardPressKey(key: Integer) → Bool · Simples

Pressiona e solta uma tecla, que pode ser qualquer tecla para a qual o Windows tenha um código, inclusive teclas de mídia. Com a configuração Enviar teclas de mídia e de navegador como comandos ativada, essas teclas enviam o comando delas em vez disso.

Parâmetros

  • key: Integer — Uma constante VirtualKey, como VirtualKey.MediaPlayPause, ou um código de tecla virtual de 0 a 255. Qualquer outro valor interrompe o script com um erro.

Retorna

true se o pressionamento da tecla foi enviado; false se o Windows o bloqueou ou, para uma tecla enviada como comando, se nenhuma janela estiver em foco.

3 exemplos: Constantes nomeadas vs. números brutos, Teclas de mídia, Mapear os botões de um dispositivo serial para teclas de mídia

KeyboardPressKeyCombo​

KeyboardPressKeyCombo(combo: Text) → Bool · Simples

Pressiona uma combinação de teclas como Ctrl+C: mantém os modificadores, pressiona e solta a tecla e depois solta os modificadores. Envia uma combinação por chamada.

Parâmetros

  • combo: Text — Símbolos modificadores opcionais (^ para Ctrl, + para Shift, @ para Windows, o sinal de porcentagem para Alt) seguidos de uma letra ou dígito, ou de um nome de tecla entre chaves, como {ENTER}, {F5} ou {LEFT}, em maiúsculas ou minúsculas. Exemplo: '^c' é Ctrl+C.

Retorna

true se os pressionamentos de tecla foram enviados; false se o Windows os bloqueou. Uma combinação que ela não entende interrompe o script com um erro.

4 exemplos: Combinações de teclas, Digitar uma assinatura, Converter o texto selecionado em maiúsculas, Pesquisar a seleção na Web

KeyboardTypeText​

KeyboardTypeText(text: Text) → Bool · Simples

Digita texto na janela em foco caractere por caractere, em qualquer idioma e inclusive emojis, seja qual for o layout do teclado. Aguarda o tempo da configuração Atraso de digitação antes de cada caractere.

Parâmetros

  • text: Text — O texto a digitar. Cada quebra de linha é enviada como um pressionamento de Enter. No script de uma expansão de texto, a tecla que encerrou o gatilho é digitada depois dele.

Retorna

true se todos os caracteres foram enviados ou se o texto estiver vazio; false se o Windows bloqueou alguns deles.

3 exemplos: Iniciar um programa, aguardar a janela dele e agir sobre ela, A data de hoje e um nome de arquivo com carimbo de data e hora, Digitar uma assinatura

Macro​

MacroClearTemporary​

MacroClearTemporary() → Bool

Descarta a macro gravada com MacroRecordTemporary.

Parâmetros

Sem parâmetros.

Retorna

true se havia uma macro gravada para descartar; false se não havia nenhuma.

MacroExpectFocusedWindow​

MacroExpectFocusedWindow(exeName: Text, windowClass: Text) → Bool

Aguarda até que a janela em primeiro plano pertença ao programa e à classe de janela indicados, até o tempo de espera de reprodução de macro definido nas configurações (2 segundos por padrão). Se nunca corresponder, mostra uma notificação e interrompe o script.

Parâmetros

  • exeName: Text — O nome do arquivo do programa, como notepad.exe. Não diferencia maiúsculas de minúsculas; texto vazio corresponde a qualquer programa.
  • windowClass: Text — O nome da classe da janela de nível superior, como Notepad. Não diferencia maiúsculas de minúsculas; texto vazio corresponde a qualquer classe.

Retorna

true quando a janela corresponde; false se foi pedido ao script que parasse durante a espera.

MacroExpectWindowAt​

MacroExpectWindowAt(x: Integer, y: Integer, exeName: Text, windowClass: Text) → Bool

Aguarda até que a janela de nível superior em um ponto da tela pertença ao programa e à classe de janela indicados, até o tempo de espera de reprodução de macro definido nas configurações (2 segundos por padrão). Se nunca corresponder, mostra uma notificação e interrompe o script.

Parâmetros

  • x: Integer — Posição horizontal na tela a verificar, em pixels da tela virtual.
  • y: Integer — Posição vertical na tela a verificar, em pixels da tela virtual.
  • exeName: Text — O nome do arquivo do programa, como notepad.exe. Não diferencia maiúsculas de minúsculas; texto vazio corresponde a qualquer programa.
  • windowClass: Text — O nome da classe da janela de nível superior, como Notepad. Não diferencia maiúsculas de minúsculas; texto vazio corresponde a qualquer classe.

Retorna

true quando a janela corresponde; false se foi pedido ao script que parasse durante a espera.

MacroGetTemporaryScript​

MacroGetTemporaryScript() → Text

Retorna a macro gravada com MacroRecordTemporary como texto de script Passos, para que um script possa salvá-la ou inspecioná-la.

Parâmetros

Sem parâmetros.

Retorna

O texto Passos da última gravação concluída, ou texto vazio se nada foi gravado ou se a gravação foi limpa. Enquanto uma nova gravação está em andamento, ainda retorna a anterior.

MacroPlayTemporary​

MacroPlayTemporary(timeoutSeconds: Integer) → Bool

Reproduz a macro gravada com MacroRecordTemporary e aguarda até que termine ou até que o tempo limite passe. A entrada real de mouse e teclado do usuário fica retida durante a reprodução.

Parâmetros

  • timeoutSeconds: Integer — O tempo máximo de espera, em segundos; 1 ou mais, ou o script é interrompido com um erro. Uma macro que ainda esteja em execução depois disso continua, mas a entrada real deixa de ficar retida.

Retorna

true se a macro foi reproduzida até o fim a tempo; false se nada foi gravado, se um passo ou verificação de janela falhou, se a reprodução foi interrompida ou se ela ainda estava em execução no tempo limite.

MacroRecordTemporary​

MacroRecordTemporary() → Bool

Começa a gravar a entrada de mouse e teclado em uma macro temporária mantida na memória; pressione Ctrl+Break para parar. Retorna imediatamente, antes de a gravação começar. Uma caixa de confirmação pode aparecer antes.

Parâmetros

Sem parâmetros.

Retorna

true se a solicitação de gravação foi enviada; false se uma gravação já estiver em andamento, iniciando ou solicitada, ou se o mecanismo ainda não terminou de iniciar.

Math​

MathAbs​

MathAbs(value: Any) → Any

Retorna o valor absoluto de um número, ou seja, o número sem o sinal de menos. Funciona com valores Integer e Real.

Parâmetros

  • value: Any — O número Integer ou Real.

Retorna

O valor absoluto, do mesmo tipo que value (Integer ou Real); 0.0 para um Real que seja NaN ou infinito. Um valor que não seja número interrompe a ação com um erro.

2 exemplos: Limitar um valor a um intervalo, Para que lado o traço foi?

MathAtan2​

MathAtan2(y: Any, x: Any) → Real

Retorna o ângulo, em radianos, da origem até o ponto (x, y). O y da tela cresce para baixo; por isso, para o ângulo de um traço no sentido matemático usual, passe a variação vertical com o sinal invertido.

Parâmetros

  • y: Any — A coordenada vertical do ponto. Integer ou Real. Observe que y vem primeiro.
  • x: Any — A coordenada horizontal do ponto. Integer ou Real.

Retorna

O ângulo em radianos, de -pi a pi, como Real; 0.0 se algum argumento for NaN ou infinito. Argumentos que não sejam números interrompem a ação com um erro.

MathCeil​

MathCeil(value: Real) → Integer

Arredonda um número para cima, até o número inteiro mais próximo. MathCeil(2.1) é 3; MathCeil(-2.1) é -2.

Parâmetros

  • value: Real — O número a arredondar para cima. Um Integer é aceito como está.

Retorna

O valor arredondado como Integer. 0 se value for NaN ou infinito; um valor além do intervalo de Integer resulta no maior ou no menor Integer.

1 exemplo: Arredondamento e funções internas de matemática com Real

MathClamp​

MathClamp(value: Any, min: Any, max: Any) → Any

Mantém um número dentro de um intervalo: retorna min se value estiver abaixo dele, max se value estiver acima dele e value nos demais casos. Funciona com valores Integer e Real.

Parâmetros

  • value: Any — O número a manter dentro do intervalo.
  • min: Any — O menor valor permitido. Não pode ser maior que max.
  • max: Any — O maior valor permitido.

Retorna

O que tiver sido escolhido entre value, min e max, mantendo o próprio tipo (Integer ou Real); 0.0 se algum argumento for NaN ou infinito. Valores que não sejam números, ou min maior que max, interrompem a ação com um erro.

1 exemplo: Limitar um valor a um intervalo

MathCos​

MathCos(radians: Real) → Real

Retorna o cosseno de um ângulo dado em radianos. Para converter graus, multiplique por MathGetPi() e divida por 180.

Parâmetros

  • radians: Real — O ângulo em radianos. Um Integer é aceito como está.

Retorna

O cosseno, de -1 a 1, como Real; 0.0 se radians for NaN ou infinito.

1 exemplo: Mover o mouse em círculo

MathFloor​

MathFloor(value: Real) → Integer

Arredonda um número para baixo, até o número inteiro mais próximo. MathFloor(2.9) é 2; MathFloor(-2.1) é -3.

Parâmetros

  • value: Real — O número a arredondar para baixo. Um Integer é aceito como está.

Retorna

O valor arredondado como Integer. 0 se value for NaN ou infinito; um valor além do intervalo de Integer resulta no maior ou no menor Integer.

1 exemplo: Arredondamento e funções internas de matemática com Real

MathGetE​

MathGetE() → Real

Retorna a constante matemática e (cerca de 2,71828), a base dos logaritmos naturais.

Parâmetros

Sem parâmetros.

Retorna

O valor de e como Real.

MathGetPi​

MathGetPi() → Real

Retorna a constante matemática pi (cerca de 3,14159). Use-a para converter entre graus e radianos.

Parâmetros

Sem parâmetros.

Retorna

O valor de pi como Real.

1 exemplo: Mover o mouse em círculo

MathLog​

MathLog(value: Real) → Real

Retorna o logaritmo natural (base e) de um número. Divida por MathLog(10.0) para obter o logaritmo na base 10.

Parâmetros

  • value: Real — O número, maior que 0. Um Integer é aceito como está.

Retorna

O logaritmo natural como Real, ou 0 se value for 0, negativo, NaN ou infinito.

MathMax​

MathMax(a: Any, b: Any) → Any

Retorna o maior de dois números. Funciona com valores Integer e Real.

Parâmetros

  • a: Any — O primeiro número.
  • b: Any — O segundo número.

Retorna

O maior entre a e b, mantendo o próprio tipo; a se forem iguais; 0.0 se algum deles for NaN ou infinito. Argumentos que não sejam números interrompem a ação com um erro.

MathMin​

MathMin(a: Any, b: Any) → Any

Retorna o menor de dois números. Funciona com valores Integer e Real.

Parâmetros

  • a: Any — O primeiro número.
  • b: Any — O segundo número.

Retorna

O menor entre a e b, mantendo o próprio tipo; a se forem iguais; 0.0 se algum deles for NaN ou infinito. Argumentos que não sejam números interrompem a ação com um erro.

1 exemplo: Aumentar o volume com uma indicação na tela

MathMod​

MathMod(value: Any, divisor: Any) → Any

Retorna o resto da divisão de value por divisor. O resultado tem o sinal do divisor; assim, MathMod(-30, 360) é 330: o certo para dar a volta em um ângulo ou percorrer um índice em ciclo.

Parâmetros

  • value: Any — O número a dividir. Integer ou Real.
  • divisor: Any — O número pelo qual dividir. Integer ou Real.

Retorna

O resto: um Integer quando ambos os argumentos são Integer; caso contrário, um Real. 0 se divisor for 0 ou se algum argumento for NaN ou infinito. Argumentos que não sejam números interrompem a ação com um erro.

MathPow​

MathPow(base: Real, exponent: Real) → Real

Eleva um número a uma potência, como ao quadrado ou ao cubo. MathPow(2.0, 10.0) é 1024.

Parâmetros

  • base: Real — O número a elevar. Um Integer é aceito como está.
  • exponent: Real — A potência a que elevá-lo. Pode ser negativa ou fracionária; 0.5 dá a raiz quadrada.

Retorna

O resultado como Real, ou 0 se algum argumento for NaN ou infinito ou se não houver resultado finito, por exemplo 0 elevado a uma potência negativa ou um resultado grande demais para ser armazenado.

MathRandom​

MathRandom(min: Integer, max: Integer) → Integer

Retorna um número inteiro aleatório entre min e max, ambos incluídos. MathRandom(1, 6) lança um dado.

Parâmetros

  • min: Integer — O menor resultado possível.
  • max: Integer — O maior resultado possível. Não pode ser menor que min.

Retorna

Um Integer aleatório de min a max. min maior que max interrompe a ação com um erro.

2 exemplos: while (true) com um sinalizador de saída, Números aleatórios e cara ou coroa

MathRound​

MathRound(value: Real) → Integer

Arredonda um número para o número inteiro mais próximo. As metades são arredondadas para longe do zero: 2.5 vira 3 e -2.5 vira -3.

Parâmetros

  • value: Real — O número a arredondar. Para manter duas casas decimais como número inteiro, arredonde value vezes 100.

Retorna

O valor arredondado como Integer. 0 se value for NaN ou infinito; um valor além do intervalo de Integer resulta no maior ou no menor Integer.

5 exemplos: Arredondamento e funções internas de matemática com Real, Comprimento do traço de um gesto, Mover o mouse em círculo, Formatar um Real sem seis casas decimais, Aumentar o volume com uma indicação na tela

MathSin​

MathSin(radians: Real) → Real

Retorna o seno de um ângulo dado em radianos. Para converter graus, multiplique por MathGetPi() e divida por 180.

Parâmetros

  • radians: Real — O ângulo em radianos. Um Integer é aceito como está.

Retorna

O seno, de -1 a 1, como Real; 0.0 se radians for NaN ou infinito.

1 exemplo: Mover o mouse em círculo

MathSqrt​

MathSqrt(value: Real) → Real

Retorna a raiz quadrada de um número. MathSqrt(dx * dx + dy * dy) é a distância entre dois pontos.

Parâmetros

  • value: Real — O número, 0 ou maior. Um Integer é aceito como está.

Retorna

A raiz quadrada como Real, ou 0 se value for negativo, NaN ou infinito.

2 exemplos: Arredondamento e funções internas de matemática com Real, Comprimento do traço de um gesto

MathTan​

MathTan(radians: Real) → Real

Retorna a tangente de um ângulo dado em radianos. Perto de um ângulo reto, o resultado fica muito grande.

Parâmetros

  • radians: Real — O ângulo em radianos. Um Integer é aceito como está.

Retorna

A tangente como Real; 0.0 se radians for NaN ou infinito.

Mouse​

MouseButtonDown​

MouseButtonDown(button: Integer) → Bool

Pressiona um botão do mouse na posição atual do cursor e o mantém pressionado até MouseButtonUp. Combine com MouseMoveTo para criar um arrasto por script.

Parâmetros

  • button: Integer — Uma constante MouseButton, como MouseButton.Primary. Primary e Secondary seguem a configuração de troca de botões do Windows; Left e Right são os botões físicos.

Retorna

true se o pressionamento do botão foi enviado; false se o Windows o bloqueou. Um botão desconhecido interrompe o script com um erro.

1 exemplo: Um arrastar por script

MouseButtonUp​

MouseButtonUp(button: Integer) → Bool

Solta um botão do mouse na posição atual do cursor, normalmente um pressionado com MouseButtonDown.

Parâmetros

  • button: Integer — Uma constante MouseButton, como MouseButton.Primary. Primary e Secondary seguem a configuração de troca de botões do Windows; Left e Right são os botões físicos.

Retorna

true se a liberação do botão foi enviada; false se o Windows a bloqueou. Um botão desconhecido interrompe o script com um erro.

1 exemplo: Um arrastar por script

MouseClick​

MouseClick(x: Integer, y: Integer, button: Integer) → Bool · Simples

Move o cursor até um ponto da tela e clica ali com um botão do mouse. Depois, o cursor permanece nesse ponto.

Parâmetros

  • x: Integer — Posição horizontal na tela onde clicar, em pixels.
  • y: Integer — Posição vertical na tela onde clicar, em pixels.
  • button: Integer — Uma constante MouseButton, como MouseButton.Primary. Primary e Secondary seguem a configuração de troca de botões do Windows; Left e Right são os botões físicos.

Retorna

true se o clique foi enviado; false se não foi possível mover o cursor até o ponto, caso em que nada é clicado, ou se o Windows bloqueou o clique. Um botão desconhecido interrompe o script com um erro.

2 exemplos: Clicar em algum lugar e devolver o cursor, Shift+clique

MouseClickAtClientPoint​

MouseClickAtClientPoint(window: Window, x: Integer, y: Integer, button: Integer) → Bool

Clica com um botão do mouse em um ponto medido a partir do canto superior esquerdo da área cliente de uma janela (o interior, sem barra de título e bordas). O cursor vai até lá e permanece.

Parâmetros

  • window: Window — A janela a partir de cuja área cliente x e y são medidos.
  • x: Integer — Distância da borda esquerda da área cliente, nos pixels da própria janela, que podem diferir dos pixels da tela em uma janela que o Windows dimensiona por DPI.
  • y: Integer — Distância da borda superior da área cliente, nos pixels da própria janela, que podem diferir dos pixels da tela em uma janela que o Windows dimensiona por DPI.
  • button: Integer — Uma constante MouseButton, como MouseButton.Primary. Primary e Secondary seguem a configuração de troca de botões do Windows; Left e Right são os botões físicos.

Retorna

true se o clique foi enviado; false se a janela for inválida ou não existir mais, ou se não foi possível mover o cursor até o ponto, caso em que nada é clicado, ou se o Windows bloqueou o clique. Um botão desconhecido interrompe o script com um erro.

1 exemplo: Clicar em um ponto dentro de uma janela

MouseDoubleClick​

MouseDoubleClick(x: Integer, y: Integer, button: Integer) → Bool · Simples

Move o cursor até um ponto da tela e clica duas vezes ali com um botão do mouse. Depois, o cursor permanece nesse ponto.

Parâmetros

  • x: Integer — Posição horizontal na tela onde clicar duas vezes, em pixels.
  • y: Integer — Posição vertical na tela onde clicar duas vezes, em pixels.
  • button: Integer — Uma constante MouseButton, como MouseButton.Primary. Primary e Secondary seguem a configuração de troca de botões do Windows; Left e Right são os botões físicos.

Retorna

true se os dois cliques foram enviados; false se não foi possível mover o cursor até o ponto, caso em que nada é clicado, ou se o Windows bloqueou os cliques. Um botão desconhecido interrompe o script com um erro.

MouseGetCursorX​

MouseGetCursorX() → Integer

Retorna a posição horizontal na tela do cursor do mouse.

Parâmetros

Sem parâmetros.

Retorna

A posição x do cursor em pixels da tela; negativa em um monitor à esquerda do principal.

8 exemplos: Encadeamento else-if, Mover o mouse em círculo, Ler a cor do pixel sob o cursor, Encaixar uma janela na célula de uma grade 3×2 sob o cursor, Descrever o que está sob o cursor, Clicar em algum lugar e devolver o cursor, Um arrastar por script, Shift+clique

MouseGetCursorY​

MouseGetCursorY() → Integer

Retorna a posição vertical na tela do cursor do mouse.

Parâmetros

Sem parâmetros.

Retorna

A posição y do cursor em pixels da tela; negativa em um monitor acima do principal.

8 exemplos: Encadeamento else-if, Mover o mouse em círculo, Ler a cor do pixel sob o cursor, Encaixar uma janela na célula de uma grade 3×2 sob o cursor, Descrever o que está sob o cursor, Clicar em algum lugar e devolver o cursor, Um arrastar por script, Shift+clique

MouseIsButtonDown​

MouseIsButtonDown(button: Integer) → Bool

Verifica se um botão do mouse está pressionado neste momento.

Parâmetros

  • button: Integer — Uma constante MouseButton, como MouseButton.Primary. Primary e Secondary seguem a configuração de troca de botões do Windows; Left e Right são os botões físicos.

Retorna

true se o botão estiver pressionado; false se estiver solto. Um botão desconhecido interrompe o script com um erro.

MouseLockToRect​

MouseLockToRect(x: Integer, y: Integer, width: Integer, height: Integer) → Bool

Confina o cursor do mouse a um retângulo da tela. O confinamento sobrevive ao script até que MouseUnlock seja chamada ou outro programa o altere; por isso, sempre desbloqueie ao terminar.

Parâmetros

  • x: Integer — Borda esquerda do retângulo, em pixels da tela.
  • y: Integer — Borda superior do retângulo, em pixels da tela.
  • width: Integer — Largura do retângulo, em pixels. Deve ser maior que 0.
  • height: Integer — Altura do retângulo, em pixels. Deve ser maior que 0.

Retorna

true se o cursor agora está confinado; false se width ou height não for positivo ou se o Windows recusou.

1 exemplo: Confinar o cursor a uma janela por 5 segundos

MouseMoveTo​

MouseMoveTo(x: Integer, y: Integer) → Bool · Simples

Move o cursor do mouse até um ponto da tela em qualquer monitor, como se o usuário movesse o mouse.

Parâmetros

  • x: Integer — Posição horizontal na tela, em pixels.
  • y: Integer — Posição vertical na tela, em pixels.

Retorna

true se o movimento foi enviado; false se o Windows o bloqueou.

3 exemplos: Mover o mouse em círculo, Clicar em algum lugar e devolver o cursor, Um arrastar por script

MouseScrollHorizontal​

MouseScrollHorizontal(amount: Integer) → Bool · Simples

Gira a roda horizontal do mouse na posição atual do cursor. Use MouseMoveTo antes para rolar em outro lugar.

Parâmetros

  • amount: Integer — Distância da roda, em que 120 é um entalhe: positivo rola para a direita, negativo rola para a esquerda. Valores menores rolam com mais precisão nos aplicativos que oferecem suporte.

Retorna

true se a rolagem foi enviada; false se o Windows a bloqueou.

1 exemplo: Rolar por entalhes

MouseScrollVertical​

MouseScrollVertical(amount: Integer) → Bool · Simples

Gira a roda vertical do mouse na posição atual do cursor. Use MouseMoveTo antes para rolar em outro lugar.

Parâmetros

  • amount: Integer — Distância da roda, em que 120 é um entalhe: positivo rola para cima, negativo rola para baixo. Valores menores rolam com mais precisão nos aplicativos que oferecem suporte.

Retorna

true se a rolagem foi enviada; false se o Windows a bloqueou.

1 exemplo: Rolar por entalhes

MouseUnlock​

MouseUnlock() → Bool

Libera o cursor do mouse de qualquer confinamento, seja ele definido por MouseLockToRect ou por outro programa.

Parâmetros

Sem parâmetros.

Retorna

true se o cursor estiver livre; false se o Windows recusou.

1 exemplo: Confinar o cursor a uma janela por 5 segundos

Multimedia​

MultimediaGetMute​

MultimediaGetMute(endpoint: Integer) → Bool

Informa se o dispositivo de reprodução ou microfone padrão escolhido por endpoint está com o som desativado no Windows.

Parâmetros

  • endpoint: Integer — O dispositivo a verificar: AudioEndpoint.Playback (alto-falantes ou fones de ouvido padrão), AudioEndpoint.Capture (microfone padrão) ou AudioEndpoint.Communications (o microfone que o Windows usa para chamadas). Qualquer outro valor interrompe a ação com um erro.

Retorna

true se o som do dispositivo estiver desativado; false se não estiver desativado ou se o dispositivo não existir (por exemplo, nenhum microfone conectado).

1 exemplo: Alternar o mudo do microfone

MultimediaGetVolume​

MultimediaGetVolume(endpoint: Integer) → Real

Retorna o volume principal do dispositivo de reprodução ou microfone padrão escolhido por endpoint, como Real de 0.0 a 1.0.

Parâmetros

  • endpoint: Integer — O dispositivo a ler: AudioEndpoint.Playback (alto-falantes ou fones de ouvido padrão), AudioEndpoint.Capture (microfone padrão) ou AudioEndpoint.Communications (o microfone que o Windows usa para chamadas). Qualquer outro valor interrompe a ação com um erro.

Retorna

O volume de 0.0 (sem som) a 1.0 (máximo), na mesma escala de MultimediaSetVolume; 0.0 se o dispositivo não existir.

1 exemplo: Aumentar o volume com uma indicação na tela

MultimediaPlayMp3File​

MultimediaPlayMp3File(path: Text) → Bool · Simples

Começa a reproduzir um arquivo MP3 e retorna imediatamente enquanto ele toca. Iniciar outro MP3 para o que ainda estiver tocando.

Parâmetros

  • path: Text — Caminho completo do arquivo .mp3, como C:/Music/done.mp3.

Retorna

true se a reprodução começou; false se o arquivo não existir, se o Windows não conseguir abri-lo ou reproduzi-lo em até 10 segundos, ou se parar tudo encerrou a espera.

MultimediaPlayWavFile​

MultimediaPlayWavFile(path: Text) → Bool · Simples

Começa a reproduzir um arquivo de som .wav e retorna imediatamente enquanto ele toca. Iniciar outro WAV para o que ainda estiver tocando. Só arquivos .wav funcionam; use MultimediaPlayMp3File para MP3.

Parâmetros

  • path: Text — Caminho completo do arquivo .wav, como C:/Windows/Media/chimes.wav.

Retorna

true se o arquivo existir e a reprodução tiver começado; false se não houver arquivo nesse caminho. Um arquivo que existe, mas não é um WAV reproduzível, retorna true e não toca nada.

1 exemplo: Tocar um som

MultimediaSetMute​

MultimediaSetMute(endpoint: Integer, muted: Bool) → Bool · Simples

Desativa ou reativa o som do dispositivo de reprodução ou microfone padrão escolhido por endpoint, como faz o botão de mudo do volume do Windows.

Parâmetros

  • endpoint: Integer — O dispositivo a alterar: AudioEndpoint.Playback (alto-falantes ou fones de ouvido padrão), AudioEndpoint.Capture (microfone padrão) ou AudioEndpoint.Communications (o microfone que o Windows usa para chamadas). Qualquer outro valor interrompe a ação com um erro.
  • muted: Bool — true para desativar o som do dispositivo; false para reativá-lo.

Retorna

true se o estado de mudo foi definido; false se o dispositivo não existir ou recusar a alteração.

1 exemplo: Uma alternância que sobrevive entre execuções

MultimediaSetVolume​

MultimediaSetVolume(endpoint: Integer, level: Real) → Bool · Simples

Define o volume principal do dispositivo de reprodução ou microfone padrão escolhido por endpoint com um nível exato.

Parâmetros

  • endpoint: Integer — O dispositivo a alterar: AudioEndpoint.Playback (alto-falantes ou fones de ouvido padrão), AudioEndpoint.Capture (microfone padrão) ou AudioEndpoint.Communications (o microfone que o Windows usa para chamadas). Qualquer outro valor interrompe a ação com um erro.
  • level: Real — O novo volume de 0.0 (sem som) a 1.0 (máximo); 0.5 corresponde a 50 no controle deslizante de volume do Windows. Valores fora de 0.0 a 1.0 são limitados a esse intervalo.

Retorna

true se o volume foi definido; false se o dispositivo não existir ou recusar a alteração.

2 exemplos: Aumentar o volume com uma indicação na tela, Transformar um botão giratório de Arduino em controle de volume

MultimediaToggleMute​

MultimediaToggleMute(endpoint: Integer) → Bool · Simples

Desativa o som do dispositivo de reprodução ou microfone padrão escolhido por endpoint se ele estiver ativo, ou o reativa se estiver desativado. Chame MultimediaGetMute depois para saber o novo estado.

Parâmetros

  • endpoint: Integer — O dispositivo a alternar: AudioEndpoint.Playback (alto-falantes ou fones de ouvido padrão), AudioEndpoint.Capture (microfone padrão) ou AudioEndpoint.Communications (o microfone que o Windows usa para chamadas). Qualquer outro valor interrompe a ação com um erro.

Retorna

true se o estado de mudo foi alternado; false se o dispositivo não existir ou recusar a alteração. Não é o novo estado de mudo.

1 exemplo: Alternar o mudo do microfone

Plugin​

PluginSendMessage​

PluginSendMessage(pluginName: Text, message: Text, timeoutSeconds: Integer) → Text

Envia uma mensagem de texto a um plug-in em execução que aceita comandos e aguarda a resposta dele. Um plug-in trata uma mensagem por vez; as mensagens enviadas enquanto ele está ocupado aguardam em uma fila.

Parâmetros

  • pluginName: Text — O nome de exibição do plug-in, comparado exatamente, inclusive maiúsculas e minúsculas.
  • message: Text — O texto a enviar. O significado fica a critério do plug-in.
  • timeoutSeconds: Integer — Quanto tempo aguardar a resposta, em segundos, de 0 a 10; qualquer outro valor interrompe o script com um erro. Com 0, a chamada retorna imediatamente com texto vazio.

Retorna

A resposta do plug-in, ou texto vazio se ele não respondeu a tempo. Um plug-in que não esteja em execução, uma fila cheia ou uma mensagem longa demais interrompe o script com um erro.

1 exemplo: Comunicar-se com um plug-in

Region​

RegionGetCellIndexAt​

RegionGetCellIndexAt(rectX: Integer, rectY: Integer, rectWidth: Integer, rectHeight: Integer, columns: Integer, rows: Integer, pointX: Integer, pointY: Integer) → Integer

Divide um retângulo em uma grade de colunas e linhas e retorna qual célula contém um ponto. As células são numeradas a partir de 0, da esquerda para a direita e depois de cima para baixo.

Parâmetros

  • rectX: Integer — Borda esquerda do retângulo a dividir, em pixels.
  • rectY: Integer — Borda superior do retângulo a dividir, em pixels.
  • rectWidth: Integer — Largura do retângulo, em pixels. Deve ser maior que 0.
  • rectHeight: Integer — Altura do retângulo, em pixels. Deve ser maior que 0.
  • columns: Integer — Número de colunas da grade. Deve ser maior que 0. Os pixels restantes vão, um para cada, às primeiras colunas.
  • rows: Integer — Número de linhas da grade. Deve ser maior que 0. Os pixels restantes vão, um para cada, às primeiras linhas.
  • pointX: Integer — Posição horizontal do ponto a localizar, nos mesmos pixels que rectX.
  • pointY: Integer — Posição vertical do ponto a localizar, nos mesmos pixels que rectY.

Retorna

O número da célula (linha vezes colunas, mais a coluna), ou -1 se o ponto estiver fora do retângulo ou se rectWidth, rectHeight, columns ou rows não for positivo.

1 exemplo: Encaixar uma janela na célula de uma grade 3×2 sob o cursor

RegionGetHeight​

RegionGetHeight(rectX: Integer, rectY: Integer, rectWidth: Integer, rectHeight: Integer, columns: Integer, rows: Integer, index: Integer) → Integer

Retorna a altura de uma célula quando um retângulo é dividido em uma grade de colunas e linhas. Os pixels restantes vão, um para cada, às primeiras linhas.

Parâmetros

  • rectX: Integer — Borda esquerda do retângulo a dividir, em pixels.
  • rectY: Integer — Borda superior do retângulo a dividir, em pixels.
  • rectWidth: Integer — Largura do retângulo, em pixels. Deve ser maior que 0.
  • rectHeight: Integer — Altura do retângulo, em pixels. Deve ser maior que 0.
  • columns: Integer — Número de colunas da grade. Deve ser maior que 0.
  • rows: Integer — Número de linhas da grade. Deve ser maior que 0.
  • index: Integer — Número da célula, a partir de zero, contado da esquerda para a direita e depois de cima para baixo, de 0 a columns vezes rows menos 1.

Retorna

A altura da célula em pixels, ou -1 se index estiver fora do intervalo ou se rectWidth, rectHeight, columns ou rows não for positivo.

1 exemplo: Encaixar uma janela na célula de uma grade 3×2 sob o cursor

RegionGetWidth​

RegionGetWidth(rectX: Integer, rectY: Integer, rectWidth: Integer, rectHeight: Integer, columns: Integer, rows: Integer, index: Integer) → Integer

Retorna a largura de uma célula quando um retângulo é dividido em uma grade de colunas e linhas. Os pixels restantes vão, um para cada, às primeiras colunas.

Parâmetros

  • rectX: Integer — Borda esquerda do retângulo a dividir, em pixels.
  • rectY: Integer — Borda superior do retângulo a dividir, em pixels.
  • rectWidth: Integer — Largura do retângulo, em pixels. Deve ser maior que 0.
  • rectHeight: Integer — Altura do retângulo, em pixels. Deve ser maior que 0.
  • columns: Integer — Número de colunas da grade. Deve ser maior que 0.
  • rows: Integer — Número de linhas da grade. Deve ser maior que 0.
  • index: Integer — Número da célula, a partir de zero, contado da esquerda para a direita e depois de cima para baixo, de 0 a columns vezes rows menos 1.

Retorna

A largura da célula em pixels, ou -1 se index estiver fora do intervalo ou se rectWidth, rectHeight, columns ou rows não for positivo.

1 exemplo: Encaixar uma janela na célula de uma grade 3×2 sob o cursor

RegionGetX​

RegionGetX(rectX: Integer, rectY: Integer, rectWidth: Integer, rectHeight: Integer, columns: Integer, rows: Integer, index: Integer) → Integer

Retorna a borda esquerda de uma célula quando um retângulo é dividido em uma grade de colunas e linhas. Os pixels restantes vão, um para cada, às primeiras colunas.

Parâmetros

  • rectX: Integer — Borda esquerda do retângulo a dividir, em pixels.
  • rectY: Integer — Borda superior do retângulo a dividir, em pixels.
  • rectWidth: Integer — Largura do retângulo, em pixels. Deve ser maior que 0.
  • rectHeight: Integer — Altura do retângulo, em pixels. Deve ser maior que 0.
  • columns: Integer — Número de colunas da grade. Deve ser maior que 0.
  • rows: Integer — Número de linhas da grade. Deve ser maior que 0.
  • index: Integer — Número da célula, a partir de zero, contado da esquerda para a direita e depois de cima para baixo, de 0 a columns vezes rows menos 1.

Retorna

A borda esquerda da célula, ou -1 se index estiver fora do intervalo ou se rectWidth, rectHeight, columns ou rows não for positivo. Uma célula real também pode começar em -1; por isso, verifique index antes.

1 exemplo: Encaixar uma janela na célula de uma grade 3×2 sob o cursor

RegionGetY​

RegionGetY(rectX: Integer, rectY: Integer, rectWidth: Integer, rectHeight: Integer, columns: Integer, rows: Integer, index: Integer) → Integer

Retorna a borda superior de uma célula quando um retângulo é dividido em uma grade de colunas e linhas. Os pixels restantes vão, um para cada, às primeiras linhas.

Parâmetros

  • rectX: Integer — Borda esquerda do retângulo a dividir, em pixels.
  • rectY: Integer — Borda superior do retângulo a dividir, em pixels.
  • rectWidth: Integer — Largura do retângulo, em pixels. Deve ser maior que 0.
  • rectHeight: Integer — Altura do retângulo, em pixels. Deve ser maior que 0.
  • columns: Integer — Número de colunas da grade. Deve ser maior que 0.
  • rows: Integer — Número de linhas da grade. Deve ser maior que 0.
  • index: Integer — Número da célula, a partir de zero, contado da esquerda para a direita e depois de cima para baixo, de 0 a columns vezes rows menos 1.

Retorna

A borda superior da célula, ou -1 se index estiver fora do intervalo ou se rectWidth, rectHeight, columns ou rows não for positivo. Uma célula real também pode começar em -1; por isso, verifique index antes.

1 exemplo: Encaixar uma janela na célula de uma grade 3×2 sob o cursor

Serial​

SerialClosePort​

SerialClosePort(port: Text) → Bool

Fecha uma porta COM aberta com SerialOpenPort, liberando-a para outros programas, como o Arduino IDE. As linhas recebidas ainda não lidas são descartadas.

Parâmetros

  • port: Text — O nome da porta passado a SerialOpenPort, como COM3. Maiúsculas e minúsculas não importam.

Retorna

true se a porta estava aberta e agora está fechada; false se ela não estava aberta ou se um monitor serial a ocupa (use SerialMonitorDelete).

1 exemplo: Fazer uma pergunta a um dispositivo serial

SerialEnumeratePorts​

SerialEnumeratePorts() → Integer

Localiza as portas seriais (COM) deste computador, como um Arduino, ESP32 ou adaptador USB-serial conectado via USB, e retorna quantas são. Leia cada nome com SerialGetEnumeratedPortAt.

Parâmetros

Sem parâmetros.

Retorna

O número de portas COM encontradas, ou 0 se não houver nenhuma.

1 exemplo: Listar as portas COM

SerialGetEnumeratedPortAt​

SerialGetEnumeratedPortAt(index: Integer) → Text

Retorna um nome de porta, como COM3, da lista criada pela última chamada a SerialEnumeratePorts nesta execução do script. O Gerenciador de Dispositivos mostra qual dispositivo está em qual porta.

Parâmetros

  • index: Integer — Posição na lista, de 0 à contagem menos 1. Os nomes são ordenados por número; assim, COM3 vem antes de COM10.

Retorna

O nome da porta, ou texto vazio se index estiver fora do intervalo ou se SerialEnumeratePorts não tiver sido chamada.

1 exemplo: Listar as portas COM

SerialGetTextLine​

SerialGetTextLine(port: Text, timeoutSeconds: Integer, baudRate: Integer) → Text

Aguarda a próxima linha completa de uma porta COM e a retorna, como a leitura de um sensor, a leitura de um código de barras ou a resposta de um dispositivo. Bloqueia o script por até timeoutSeconds; parar tudo encerra a espera.

Parâmetros

  • port: Text — O nome da porta, como COM3. Abra-a antes com SerialOpenPort para escolher as configurações e manter as linhas que chegarem antes; caso contrário, ela é aberta a baudRate só para esta espera.
  • timeoutSeconds: Integer — Espera máxima, em segundos. 0 aguarda até que chegue uma linha ou o script seja interrompido. Um valor negativo interrompe o script com um erro.
  • baudRate: Integer — Velocidade em bits por segundo, usada só quando esta chamada abre a porta por conta própria, por exemplo 9600 ou 115200; ignorada para uma porta aberta com SerialOpenPort. 0 ou menos interrompe o script com um erro.

Retorna

A linha sem o terminador, ou texto vazio se nenhuma linha chegou a tempo, se a porta não pôde ser aberta ou se o dispositivo foi desconectado. Interrompe o script com um erro se um monitor serial ocupar a porta.

2 exemplos: Fazer uma pergunta a um dispositivo serial, Manter a porta de um Arduino aberta e enviar comandos a ele

SerialMonitorCreate​

SerialMonitorCreate(name: Text, port: Text, baudRate: Integer, parity: Integer, dataBits: Integer, stopBits: Integer, terminator: Text, script: Text) → Bool

Abre uma porta COM e executa um script para cada linha que o dispositivo enviar, por exemplo para transformar uma caixa de botões Arduino ou um macro pad em atalhos. O monitor continua em execução depois que este script termina. Parar tudo interrompe o script em execução para uma linha e descarta as linhas em espera; o monitor continua em execução.

Parâmetros

  • name: Text — Um nome para o monitor. Reutilizar o nome do monitor atual desta porta o substitui; um nome que já monitora outra porta interrompe o script com um erro. Maiúsculas e minúsculas não importam.
  • port: Text — O nome da porta, como COM3. O Gerenciador de Dispositivos mostra em qual porta uma placa está.
  • baudRate: Integer — Velocidade em bits por segundo. Deve corresponder ao dispositivo, por exemplo o 9600 ou 115200 do Serial.begin de um sketch Arduino.
  • parity: Integer — Uma constante SerialParity. A maioria dos dispositivos, inclusive as placas Arduino, usa SerialParity.None.
  • dataBits: Integer — Bits por caractere, como número simples. Quase todos os dispositivos usam 8.
  • stopBits: Integer — Uma constante SerialStopBits, normalmente SerialStopBits.One. Use a constante: o número simples 1 significa um bit de parada e meio.
  • terminator: Text — O texto que termina cada linha: removido das linhas recebidas e adicionado a cada linha que SerialWriteTextLine envia. Texto vazio significa CR LF, que o Serial.println do Arduino envia. Use '\n' para dispositivos que terminam as linhas só com LF, ou '\r' para só CR.
  • script: Text — O script a executar para cada linha recebida, como Text. Ele lê a linha com ContextGetSerialTextLine. As linhas são executadas uma de cada vez, na ordem em que chegaram; até 256 linhas aguardam enquanto o script é executado e, além disso, as mais antigas são descartadas.

Retorna

true assim que o monitor estiver em execução; false se a porta não existir, estiver desconectada ou em uso por outro programa. Interrompe o script com um erro se a porta estiver aberta com SerialOpenPort ou monitorada com outro nome, ou se este nome já monitorar outra porta. Desconectar o dispositivo encerra o monitor e registra uma linha na guia Sistema do console.

2 exemplos: Mapear os botões de um dispositivo serial para teclas de mídia, Transformar um botão giratório de Arduino em controle de volume

SerialMonitorDelete​

SerialMonitorDelete(name: Text) → Bool

Para um monitor serial criado com SerialMonitorCreate e fecha a porta COM dele, para que outros programas possam usar a porta novamente. As linhas ainda não tratadas são descartadas; um script já em execução termina.

Parâmetros

  • name: Text — O nome passado a SerialMonitorCreate. Maiúsculas e minúsculas não importam.

Retorna

true se um monitor com esse nome foi encontrado e parado; false se não havia nenhum.

SerialMonitorDeleteAll​

SerialMonitorDeleteAll() → Bool

Para todos os monitores seriais e fecha as portas COM deles. As portas abertas com SerialOpenPort continuam abertas.

Parâmetros

Sem parâmetros.

Retorna

Sempre true.

SerialMonitorGetCount​

SerialMonitorGetCount() → Integer

Retorna quantos monitores seriais estão em execução e tira um instantâneo dos nomes deles para SerialMonitorGetEnumeratedNameAt.

Parâmetros

Sem parâmetros.

Retorna

O número de monitores seriais em execução, ou 0 se não houver nenhum.

SerialMonitorGetEnumeratedNameAt​

SerialMonitorGetEnumeratedNameAt(index: Integer) → Text

Retorna um nome de monitor do instantâneo tirado pela última chamada a SerialMonitorGetCount nesta execução do script.

Parâmetros

  • index: Integer — Posição no instantâneo, de 0 à contagem menos 1. A ordem não tem significado.

Retorna

O nome do monitor, ou texto vazio se index estiver fora do intervalo ou se SerialMonitorGetCount não tiver sido chamada.

SerialOpenPort​

SerialOpenPort(port: Text, baudRate: Integer, parity: Integer, dataBits: Integer, stopBits: Integer, terminator: Text) → Bool

Abre uma porta COM e a mantém aberta até SerialClosePort, coletando cada linha recebida para SerialGetTextLine. Abrir a porta liga os sinais DTR e RTS, o que reinicia muitas placas Arduino, assim como faz o Arduino IDE; por isso, abra uma vez e reutilize.

Parâmetros

  • port: Text — O nome da porta, como COM3. O Gerenciador de Dispositivos ou SerialEnumeratePorts o mostra. Texto vazio interrompe o script com um erro.
  • baudRate: Integer — Velocidade em bits por segundo. Deve corresponder ao dispositivo, por exemplo o 9600 ou 115200 do Serial.begin de um sketch Arduino.
  • parity: Integer — Uma constante SerialParity. A maioria dos dispositivos, inclusive as placas Arduino, usa SerialParity.None.
  • dataBits: Integer — Bits por caractere, como número simples. Quase todos os dispositivos usam 8.
  • stopBits: Integer — Uma constante SerialStopBits, normalmente SerialStopBits.One. Use a constante: o número simples 1 significa um bit de parada e meio.
  • terminator: Text — O texto que termina cada linha: removido das linhas recebidas e adicionado a cada linha que SerialWriteTextLine envia. Texto vazio significa CR LF, que o Serial.println do Arduino envia. Use '\n' para dispositivos que terminam as linhas só com LF, ou '\r' para só CR.

Retorna

true se a porta estiver aberta; false se ela não existir, estiver desconectada, estiver em uso por outro programa, como um monitor serial, ou rejeitar as configurações. Interrompe o script com um erro se o Input.Observer já tiver a porta aberta ou se um monitor serial a ocupar.

2 exemplos: Fazer uma pergunta a um dispositivo serial, Manter a porta de um Arduino aberta e enviar comandos a ele

SerialWriteTextLine​

SerialWriteTextLine(port: Text, text: Text, baudRate: Integer) → Bool

Envia uma linha de texto mais o final de linha da porta a uma porta COM, como um comando para um Arduino ou uma linha de G-code para uma impressora 3D. Funciona em uma porta aberta com SerialOpenPort ou ocupada por um monitor serial, para que o script de um monitor possa responder ao dispositivo. Uma porta que não esteja aberta é aberta a baudRate, 8-N-1, só para esta gravação.

Parâmetros

  • port: Text — O nome da porta, como COM3. Abra-a antes com SerialOpenPort para escolher as configurações e evitar reiniciar placas que são redefinidas quando a porta é aberta.
  • text: Text — A linha a enviar, codificada em UTF-8. Não adicione um final de linha: é adicionado o terminador com que a porta foi aberta, ou CR LF quando esta chamada abre a porta por conta própria.
  • baudRate: Integer — Velocidade em bits por segundo, usada só quando esta chamada abre a porta por conta própria, por exemplo 9600 ou 115200; ignorada para uma porta que já esteja aberta ou monitorada. 0 ou menos interrompe o script com um erro.

Retorna

true se a linha foi enviada; false se a porta não pôde ser aberta ou se a gravação falhou ou excedeu o tempo limite.

2 exemplos: Fazer uma pergunta a um dispositivo serial, Manter a porta de um Arduino aberta e enviar comandos a ele

Shell​

ShellEmptyRecycleBins​

ShellEmptyRecycleBins() → Bool · Simples

Exclui permanentemente tudo o que está na Lixeira de todas as unidades, sem pedir confirmação. Isso não pode ser desfeito.

Parâmetros

Sem parâmetros.

Retorna

true se as Lixeiras foram esvaziadas ou já estavam vazias; caso contrário, false.

ShellEnumerateProcessIdsByExeRegex​

ShellEnumerateProcessIdsByExeRegex(pattern: Text) → Integer

Localiza todos os processos em execução cujo nome de arquivo do programa, como notepad.exe, corresponda a uma expressão regular, e retorna quantos são. Leia cada ID de processo com ShellGetEnumeratedProcessIdAt.

Parâmetros

  • pattern: Text — Uma expressão regular, comparada sem diferenciar maiúsculas de minúsculas somente com o nome do arquivo, não com o caminho completo. Use ^ e $ para corresponder ao nome inteiro, como ^notepad[.]exe$.

Retorna

O número de processos correspondentes, ou 0 se nenhum corresponder. Um padrão inválido interrompe o script com um erro.

1 exemplo: Do processo à janela

ShellExpandEnvironmentVariables​

ShellExpandEnvironmentVariables(text: Text) → Text

Substitui cada variável de ambiente em text, escrita como um nome entre dois sinais de porcentagem, como USERPROFILE ou TEMP, pelo valor dela. Útil para montar caminhos que funcionem em qualquer PC.

Parâmetros

  • text: Text — Texto que contém nomes de variáveis de ambiente entre sinais de porcentagem, como um caminho na pasta de perfil do usuário.

Retorna

O texto com todas as variáveis conhecidas substituídas; as variáveis desconhecidas ficam como escritas. Texto vazio se a expansão falhar.

8 exemplos: A data de hoje e um nome de arquivo com carimbo de data e hora, Capturar a área que você circulou, Salvar uma imagem copiada em um arquivo, Acrescentar a um arquivo de log, Contar os tipos de arquivo em uma pasta, Fazer backup de um arquivo antes de editá-lo, Monitorar uma pasta, Expandir variáveis de ambiente

ShellGetEnumeratedProcessIdAt​

ShellGetEnumeratedProcessIdAt(index: Integer) → Integer

Retorna um ID de processo da lista criada pela última chamada a ShellEnumerateProcessIdsByExeRegex nesta execução do script.

Parâmetros

  • index: Integer — Posição na lista, de 0 à contagem menos 1.

Retorna

O ID do processo, ou 0 se index estiver fora do intervalo ou se ShellEnumerateProcessIdsByExeRegex não tiver sido chamada.

1 exemplo: Do processo à janela

ShellGetSystemMetricsByIndex​

ShellGetSystemMetricsByIndex(index: Integer) → Integer

Retorna uma medida ou configuração do sistema Windows pelo índice de GetSystemMetrics, como 0 para a largura da tela principal ou 80 para o número de monitores.

Parâmetros

  • index: Integer — Um número de índice SM_ do Windows, como 0 (SM_CXSCREEN) ou 1 (SM_CYSCREEN). Não há constantes nomeadas para eles.

Retorna

O valor que o Windows informa, muitas vezes em pixels, ou 0 para um índice desconhecido.

ShellRun​

ShellRun(command: Text) → Bool · Simples

Executa um programa ou abre um arquivo, uma pasta ou um endereço da Web, como ao digitá-lo na caixa Executar do Windows (Win+R). Não aguarda o programa terminar.

Parâmetros

  • command: Text — Um nome de programa como notepad.exe, um caminho ou um endereço da Web, opcionalmente seguido de argumentos. Coloque entre aspas simples um caminho que contenha espaços quando houver argumentos depois dele.

Retorna

true se o Windows o iniciou; false se não foi possível encontrá-lo ou iniciá-lo. Nenhuma caixa de erro do Windows é mostrada em caso de falha.

4 exemplos: Loop while: aguardar uma janela, com tempo limite, Iniciar um programa, aguardar a janela dele e agir sobre ela, Pesquisar na Web o texto selecionado, Pesquisar a seleção na Web

ShellRunOrActivate​

ShellRunOrActivate(exeName: Text) → Bool · Simples

Traz para a frente a janela de um programa se ele já estiver em execução, ou executa o comando caso contrário. Útil para um gesto que sempre leva você ao mesmo programa.

Parâmetros

  • exeName: Text — O nome do arquivo do programa, como notepad ou notepad.exe, ou o caminho completo, opcionalmente seguido de argumentos usados só quando ele precisa ser iniciado. As janelas em execução são comparadas pelo nome do arquivo da primeira palavra, com .exe adicionado quando não há extensão; coloque entre aspas simples um caminho que contenha espaços.

Retorna

true se uma janela foi trazida para a frente ou se o programa foi iniciado; false se o Windows se recusou a trazer a janela para a frente ou se a inicialização falhou.

1 exemplo: Iniciar um aplicativo ou alternar para ele

ShellRunProgram​

ShellRunProgram(path: Text, arguments: Text, verb: Any, windowStyle: Integer, waitForExit: Bool) → Bool

Executa um programa ou abre um arquivo com uma ação escolhida (verbo) e um estilo de janela, e pode aguardar até que ele seja fechado. Use ShellVerb.RunAs para executar um programa como administrador.

Parâmetros

  • path: Text — O programa, documento ou pasta a abrir, como notepad.exe ou um caminho completo de arquivo.
  • arguments: Text — Argumentos de linha de comando para o programa, ou texto vazio para nenhum.
  • verb: Any — Uma constante ShellVerb, como ShellVerb.Open ou ShellVerb.Print, ou qualquer verbo compatível com o tipo de arquivo, como Text. Texto vazio usa a ação padrão.
  • windowStyle: Integer — Uma constante WindowStyle: WindowStyle.Normal, WindowStyle.Minimized, WindowStyle.Maximized ou WindowStyle.Hidden. Qualquer outro valor interrompe o script com um erro. Alguns programas a ignoram.
  • waitForExit: Bool — true para bloquear o script até o programa ser fechado; parar tudo encerra a espera e deixa o programa em execução. false para continuar imediatamente.

Retorna

true se o Windows o iniciou (e, com waitForExit, se ele já foi fechado); false se não foi possível iniciá-lo, se a solicitação de administrador foi recusada ou se parar tudo encerrou a espera. Nenhuma caixa de erro do Windows é mostrada em caso de falha.

2 exemplos: Executar um programa com um verbo e um estilo de janela, Executar e aguardar o término

ShellRunStoreApp​

ShellRunStoreApp(packageName: Text) → Bool · Simples

Inicia um aplicativo da Microsoft Store instalado pelo nome do pacote, inteiro ou em parte, ou pelo nome no menu Iniciar, como Microsoft.WindowsCalculator ou Calculadora. Programas comuns da área de trabalho não são encontrados; use ShellRun para eles.

Parâmetros

  • packageName: Text — O nome da família de pacotes do aplicativo, inteiro ou em parte, ou o nome exato no menu Iniciar, comparado sem diferenciar maiúsculas de minúsculas. Um nome exato de família de pacotes tem prioridade, depois um nome exato no menu Iniciar, depois o primeiro aplicativo cujo nome de família de pacotes contém o texto.

Retorna

true se o aplicativo foi iniciado; false se packageName estiver vazio, se nenhum aplicativo da Store instalado corresponder ou se a inicialização falhar.

ShellShowToast​

ShellShowToast(title: Text, message: Text) → Bool · Simples

Mostra uma notificação do Windows (toast) com um título e uma mensagem. Aguarda só até o Windows aceitá-la, não até ela ser descartada.

Parâmetros

  • title: Text — A primeira linha da notificação, em negrito.
  • message: Text — O texto mostrado sob o título.

Retorna

true se a notificação foi mostrada; false se as notificações estiverem desativadas nas configurações Geral, se o Windows a recusou ou se parar tudo encerrou a espera.

9 exemplos: Fixar uma janela por cima, Capturar a área que você circulou, Salvar uma imagem copiada em um arquivo, Uma alternância que sobrevive entre execuções, Uma notificação do Windows, Alternar o mudo do microfone, Executar e aguardar o término, Passar para o próximo perfil de gestos, Estado do mecanismo

ShellTerminateProcess​

ShellTerminateProcess(processId: Integer) → Bool

Encerra um processo imediatamente, como Finalizar tarefa no Gerenciador de Tarefas. O trabalho não salvo nesse programa é perdido.

Parâmetros

  • processId: Integer — O ID do processo, por exemplo obtido com WindowGetProcessId ou ShellGetEnumeratedProcessIdAt. 0 ou menos, o próprio processo do Input.Observer e os processos de sistema do Windows interrompem o script com um erro.

Retorna

true se o processo foi encerrado; false se ele já tinha saído ou se o Windows negou o acesso, como no caso de um programa executado como administrador.

Snippet​

SnippetExecuteScript​

SnippetExecuteScript(name: Text) → Bool · Simples

Executa o snippet com este nome e aguarda até que ele termine. O snippet vê o contexto do gatilho de quem o chamou, mas tem as próprias variáveis.

Parâmetros

  • name: Text — O nome do snippet, comparado exatamente, inclusive maiúsculas e minúsculas.

Retorna

true se o snippet foi executado até o fim; false se nenhum snippet tiver esse nome, ou se o snippet estiver vazio, tiver um erro ou tiver sido interrompido.

1 exemplo: Snippets como funções reutilizáveis

SnippetGetScript​

SnippetGetScript(name: Text) → Text

Retorna o texto do script do snippet com este nome sem executá-lo, por exemplo para passar a TimerCreate.

Parâmetros

  • name: Text — O nome do snippet, comparado exatamente, inclusive maiúsculas e minúsculas.

Retorna

O texto do script do snippet, ou texto vazio se nenhum snippet tiver esse nome.

1 exemplo: Script de temporizador a partir de um snippet, sem escapes

Storage​

StorageClearAll​

StorageClearAll() → Bool

Remove todos os valores armazenados com StorageSetValue, de todas as ações. Os valores persistentes não são afetados.

Parâmetros

Sem parâmetros.

Retorna

Sempre true.

StorageClearAllPersistent​

StorageClearAllPersistent() → Bool

Remove todos os valores persistentes e os apaga de storage.toml, para que nenhum deles volte após reiniciar. Os valores armazenados com StorageSetValue não são afetados.

Parâmetros

Sem parâmetros.

Retorna

Sempre true.

StorageClearPersistentValue​

StorageClearPersistentValue(key: Text) → Bool

Remove um valor persistente e o apaga de storage.toml. Nada acontece se a chave não estiver armazenada.

Parâmetros

  • key: Text — O nome do valor a remover. Maiúsculas e minúsculas são diferenciadas.

Retorna

Sempre true, esteja a chave armazenada ou não.

StorageClearValue​

StorageClearValue(key: Text) → Bool

Remove um valor armazenado com StorageSetValue. Nada acontece se a chave não estiver armazenada.

Parâmetros

  • key: Text — O nome do valor a remover. Maiúsculas e minúsculas são diferenciadas.

Retorna

Sempre true, esteja a chave armazenada ou não.

StorageGetPersistentValue​

StorageGetPersistentValue(key: Text) → Any

Lê um valor salvo com StorageSetPersistentValue, inclusive um salvo antes da última reinicialização do Input.Observer.

Parâmetros

  • key: Text — O nome com o qual o valor foi salvo. Maiúsculas e minúsculas são diferenciadas.

Retorna

O valor armazenado com o tipo dele (Bool, Integer, Real ou Text), ou Integer 0 se a chave não estiver armazenada. Use StorageHasPersistentValue para distinguir uma chave ausente de um 0 armazenado.

1 exemplo: Um contador que sobrevive a uma reinicialização

StorageGetValue​

StorageGetValue(key: Text) → Any

Lê um valor armazenado com StorageSetValue por esta ou qualquer outra ação desde que o Input.Observer foi iniciado.

Parâmetros

  • key: Text — O nome com o qual o valor foi armazenado. Maiúsculas e minúsculas são diferenciadas.

Retorna

O valor armazenado com o tipo dele (Bool, Integer, Real, Text ou Window), ou Integer 0 se a chave não estiver armazenada. Use StorageHasValue para distinguir uma chave ausente de um 0 armazenado.

5 exemplos: && e || avaliam os dois lados, Um temporizador repetitivo que conta, Uma alternância que sobrevive entre execuções, Uma lista guardada no Storage, Snippets como funções reutilizáveis

StorageHasPersistentValue​

StorageHasPersistentValue(key: Text) → Bool

Verifica se há um valor persistente armazenado com um nome. Use-a para distinguir uma chave ausente de um 0, false ou texto vazio armazenado.

Parâmetros

  • key: Text — O nome a procurar. Maiúsculas e minúsculas são diferenciadas.

Retorna

true se houver um valor persistente armazenado em key; false caso contrário.

StorageHasValue​

StorageHasValue(key: Text) → Bool

Verifica se há um valor armazenado com um nome por StorageSetValue. Use-a para distinguir uma chave ausente de um 0, false ou texto vazio armazenado.

Parâmetros

  • key: Text — O nome a procurar. Maiúsculas e minúsculas são diferenciadas.

Retorna

true se houver um valor armazenado em key; false caso contrário.

StorageSetPersistentValue​

StorageSetPersistentValue(key: Text, value: Any) → Bool

Salva um valor com um nome que sobrevive a uma reinicialização, em storage.toml ao lado do arquivo de configuração. O arquivo é texto simples, nunca criptografado: não guarde senhas nem outros segredos nele.

Parâmetros

  • key: Text — O nome com o qual salvar, de até 256 caracteres. Maiúsculas e minúsculas são diferenciadas. Substitui qualquer valor já armazenado com esse nome.
  • value: Any — O valor a salvar: um Bool, Integer, Real ou Text (de até 32.768 caracteres). Ele volta com o mesmo tipo. Um Window não pode ser salvo.

Retorna

true assim que o valor estiver armazenado. false quando storage.toml existia mas não pôde ser lido na inicialização: o salvamento fica desativado até a próxima inicialização, e o valor é mantido só até o Input.Observer sair. Um valor de janela, uma chave com mais de 256 caracteres, um Text com mais de 32.768 caracteres ou uma nova chave além de 1.024 valores armazenados interrompe a ação com um erro.

1 exemplo: Um contador que sobrevive a uma reinicialização

StorageSetValue​

StorageSetValue(key: Text, value: Any) → Bool

Armazena um valor com um nome para que execuções posteriores desta ou de qualquer outra ação possam lê-lo. Os valores são mantidos até o Input.Observer sair; use StorageSetPersistentValue para manter um entre reinicializações.

Parâmetros

  • key: Text — O nome com o qual armazenar, com até 256 caracteres. Maiúsculas e minúsculas são diferenciadas. Substitui qualquer valor já armazenado com esse nome, seja qual for o tipo.
  • value: Any — O valor a armazenar: um Bool, Integer, Real, Text (até 32.768 caracteres) ou Window. Ele volta com o mesmo tipo.

Retorna

true assim que o valor estiver armazenado. Uma chave com mais de 256 caracteres, um Text com mais de 32.768 caracteres ou uma nova chave além de 1.024 valores armazenados interrompe a ação com um erro.

5 exemplos: && e || avaliam os dois lados, Um temporizador repetitivo que conta, Uma alternância que sobrevive entre execuções, Uma lista guardada no Storage, Snippets como funções reutilizáveis

String​

StringContains​

StringContains(text: Text, search: Text) → Bool

Verifica se um texto contém outro trecho de texto em qualquer posição. Maiúsculas e minúsculas devem coincidir; use StringToLower nos dois para uma verificação que não as diferencie.

Parâmetros

  • text: Text — O texto em que procurar.
  • search: Text — O texto a procurar.

Retorna

true se search ocorrer em text, ou se search estiver vazio; caso contrário, false.

1 exemplo: Comparações sem diferenciar maiúsculas de minúsculas

StringEndsWith​

StringEndsWith(text: Text, suffix: Text) → Bool

Verifica se um texto termina com determinado trecho de texto, como uma extensão de arquivo. Maiúsculas e minúsculas devem coincidir.

Parâmetros

  • text: Text — O texto a verificar.
  • suffix: Text — O final a procurar, como '.pdf'.

Retorna

true se text terminar com suffix, ou se suffix estiver vazio; caso contrário, false.

1 exemplo: Contar os tipos de arquivo em uma pasta

StringFormat​

StringFormat(format: Text, value0: Any, value1: Any) → Text

Monta um texto substituindo cada {0} em format por value0 e cada {1} por value1. É assim que se transforma um número, um Bool ou uma janela em Text.

Parâmetros

  • format: Text — O texto com os marcadores {0} e {1}. Não existe {2}; aninhe chamadas para mais valores. {0} é substituído primeiro; assim, um {1} dentro de value0 também é substituído.
  • value0: Any — O valor para {0}, de qualquer tipo.
  • value1: Any — O valor para {1}, de qualquer tipo. Passe texto vazio se format não tiver {1}.

Retorna

O texto de format com os marcadores substituídos. Um Real mostra seis casas decimais; true e false aparecem como palavras.

50 exemplos: Os cinco tipos de valor, Loops de contagem: crescente, decrescente e em saltos, Loops aninhados: uma tabuada, while (true) com um sinalizador de saída, Surpresas de precedência, && e || avaliam os dois lados, Igualdade entre tipos, Aritmética com tipos mistos resulta em 0, Comentários, instruções vazias e blocos, Divisão de Integer e de Real, e divisão por zero, Resto sem %, Arredondamento e funções internas de matemática com Real, Limitar um valor a um intervalo, Números aleatórios e cara ou coroa, Comprimento do traço de um gesto, Formatar um Real sem seis casas decimais, Máscaras de sinalizadores: ativar, desativar, inverter, testar, Ler a cor do pixel sob o cursor, Contar os bits ativos, Casos extremos de deslocamento, Trocar dois Integers, Bits de estado de tecla, Formatar mais de dois valores, Dividir e percorrer, Divisões aninhadas: pares chave=valor, Último índice de: uma extensão de arquivo, Preencher um número com zeros à esquerda, Contar as palavras da área de transferência, A ordenação de Text é ordinal, Constantes nomeadas vs. números brutos, Listar as janelas de nível superior visíveis, Minimizar todas as janelas de um aplicativo, Fechar janelas por padrão de título, após confirmação, Inspecionar os controles filhos de uma janela, Do processo à janela, Descrever o que está sob o cursor, Tudo o que o contexto do gatilho sabe, Acrescentar a um arquivo de log, Ler um arquivo e contar as suas linhas, Contar os tipos de arquivo em uma pasta, Um temporizador repetitivo que conta, Um contador que sobrevive a uma reinicialização, Uma lista guardada no Storage, Aumentar o volume com uma indicação na tela, Uma mensagem na tela atualizada ao vivo, Uma notificação do Windows, Listar os monitores, Estado do mecanismo, Snippets como funções reutilizáveis, Manter a porta de um Arduino aberta e enviar comandos a ele

StringFromNumber​

StringFromNumber(number: Any, decimals: Integer, invariantCulture: Bool) → Text

Transforma um número em texto, no formato regional do usuário com agrupamento de dígitos para exibição, ou em um formato fixo de máquina para arquivos e dispositivos.

Parâmetros

  • number: Any — O Integer ou Real a converter.
  • decimals: Integer — Quantos dígitos depois do separador decimal, de 0 a 15, arredondados; ou -1 para tantos quantos o valor precisar (nenhum para um Integer).
  • invariantCulture: Bool — true para texto de máquina: ponto como separador decimal, sem agrupamento, legível de volta com StringToNumber(text, true). false para o formato regional do usuário.

Retorna

O número como texto, como 1.234,50 ou 1234.5. Texto vazio se um Real não for um número finito. Um valor que não seja número, ou decimals fora do intervalo, interrompe a ação com um erro.

1 exemplo: Ler um número que alguém digitou

StringGetIndexOf​

StringGetIndexOf(text: Text, search: Text) → Integer

Localiza onde um trecho de texto ocorre pela primeira vez dentro de outro. Maiúsculas e minúsculas devem coincidir. As posições começam em 0.

Parâmetros

  • text: Text — O texto em que procurar.
  • search: Text — O texto a procurar.

Retorna

A posição, a partir de 0, da primeira ocorrência, 0 se search estiver vazio, ou -1 se search não ocorrer em text.

1 exemplo: && e || avaliam os dois lados

StringGetLength​

StringGetLength(text: Text) → Integer

Retorna o número de caracteres do texto, contando espaços e quebras de linha. As posições usadas por StringGetSubstring são contadas da mesma forma.

Parâmetros

  • text: Text — O texto a medir.

Retorna

A contagem de caracteres, ou 0 para texto vazio. Alguns emojis e caracteres raros contam como 2.

3 exemplos: Último índice de: uma extensão de arquivo, Preencher um número com zeros à esquerda, Inverter um Text

StringGetSplitPartAt​

StringGetSplitPartAt(index: Integer) → Text

Retorna uma parte da chamada mais recente a StringSplit nesta execução do script.

Parâmetros

  • index: Integer — O número da parte, a partir de 0, de 0 à contagem retornada por StringSplit menos 1.

Retorna

O texto da parte, ou texto vazio se index estiver fora do intervalo ou se StringSplit não tiver sido chamada nesta execução.

6 exemplos: break e continue, Dividir e percorrer, Divisões aninhadas: pares chave=valor, Contar as palavras da área de transferência, Juntar as linhas da área de transferência em uma só, Ler um arquivo e contar as suas linhas

StringGetSubstring​

StringGetSubstring(text: Text, start: Integer, length: Integer) → Text

Retorna parte de um texto: até length caracteres, começando na posição start. As posições começam em 0.

Parâmetros

  • text: Text — O texto do qual tirar a parte.
  • start: Integer — A posição, a partir de 0, do primeiro caractere a tirar. Não pode ser negativa.
  • length: Integer — O máximo de caracteres a tirar. Não pode ser negativo.

Retorna

A parte solicitada, mais curta se o texto terminar antes, ou texto vazio se start estiver no fim ou depois dele. Um start ou length negativo interrompe a ação com um erro.

4 exemplos: && e || avaliam os dois lados, Integer para texto hexadecimal, Último índice de: uma extensão de arquivo, Inverter um Text

StringIsNumber​

StringIsNumber(text: Text, invariantCulture: Bool) → Bool

Verifica se um texto é um número que StringToNumber consegue ler, como o que um usuário digitou em UIShowInputBox. Os espaços em volta do número são ignorados.

Parâmetros

  • text: Text — O texto a verificar.
  • invariantCulture: Bool — true para texto de máquina: ponto como separador decimal e sem agrupamento de dígitos. false para o formato regional do usuário, como uma pessoa o digitaria; os grupos de dígitos devem então seguir os tamanhos de grupo desse formato.

Retorna

true se text for um número no formato escolhido; caso contrário, false, inclusive para texto vazio.

2 exemplos: Ler um número que alguém digitou, Transformar um botão giratório de Arduino em controle de volume

StringRegexGetGroupAt​

StringRegexGetGroupAt(index: Integer) → Text

Retorna a correspondência inteira ou um grupo de captura da chamada bem-sucedida mais recente a StringRegexMatch nesta execução do script.

Parâmetros

  • index: Integer — 0 para a correspondência inteira; 1 em diante para os grupos de captura, na ordem em que os parênteses de abertura aparecem. Os grupos nomeados também são numerados.

Retorna

O texto correspondente, ou texto vazio se index estiver fora do intervalo, se o grupo não participou da correspondência ou se o último StringRegexMatch não encontrou correspondência.

1 exemplo: Extrair um valor de um texto copiado com uma expressão regular

StringRegexMatch​

StringRegexMatch(text: Text, pattern: Text) → Bool

Verifica se uma expressão regular (sintaxe PCRE2) corresponde a algum trecho do texto e memoriza a correspondência e os grupos dela para StringRegexGetGroupAt.

Parâmetros

  • text: Text — O texto em que procurar.
  • pattern: Text — A expressão regular. Diferencia maiúsculas de minúsculas; comece-a com (?i) para ignorá-las. Classes de caracteres como palavra e dígito seguem o Unicode.

Retorna

true se o padrão corresponder; false caso contrário. Um padrão inválido, ou que precise de passos demais neste texto, interrompe a ação com um erro.

1 exemplo: Extrair um valor de um texto copiado com uma expressão regular

StringRegexReplace​

StringRegexReplace(text: Text, pattern: Text, replacement: Text) → Text

Substitui cada correspondência de uma expressão regular (sintaxe PCRE2) no texto por uma substituição que pode incluir os grupos correspondentes.

Parâmetros

  • text: Text — O texto a alterar.
  • pattern: Text — A expressão regular. Diferencia maiúsculas de minúsculas; comece-a com (?i) para ignorá-las.
  • replacement: Text — O texto a colocar no lugar de cada correspondência. $1 ou ${1} insere o grupo 1, ${name} um grupo nomeado, $0 a correspondência inteira e $$ um cifrão literal.

Retorna

O texto com todas as correspondências substituídas, ou o texto inalterado se nada corresponder. Um padrão ou uma substituição inválidos, passos demais ou um resultado com mais de 16 milhões de caracteres interrompem a ação com um erro.

1 exemplo: Extrair um valor de um texto copiado com uma expressão regular

StringReplace​

StringReplace(text: Text, search: Text, replacement: Text) → Text

Substitui cada ocorrência de um trecho de texto por outro. Maiúsculas e minúsculas devem coincidir. A busca é por texto literal, não por um padrão.

Parâmetros

  • text: Text — O texto a alterar.
  • search: Text — O texto a localizar. Não pode estar vazio.
  • replacement: Text — O texto a colocar no lugar. Pode estar vazio para remover todas as ocorrências.

Retorna

O texto com todas as ocorrências substituídas, ou o texto inalterado se search não ocorrer. Um search vazio interrompe a ação com um erro.

3 exemplos: Contar as palavras da área de transferência, Preencher um modelo e colá-lo, Pesquisar a seleção na Web

StringSplit​

StringSplit(text: Text, delimiter: Text) → Integer

Divide o texto em partes em cada ocorrência de um delimitador e memoriza as partes para StringGetSplitPartAt. Delimitadores adjacentes, ou um em qualquer das pontas, geram partes vazias.

Parâmetros

  • text: Text — O texto a dividir.
  • delimiter: Text — O texto literal no qual dividir, como ',' ou uma quebra de linha. Não pode estar vazio.

Retorna

O número de partes, no mínimo 1. Um delimitador vazio interrompe a ação com um erro.

6 exemplos: break e continue, Dividir e percorrer, Divisões aninhadas: pares chave=valor, Contar as palavras da área de transferência, Juntar as linhas da área de transferência em uma só, Ler um arquivo e contar as suas linhas

StringStartsWith​

StringStartsWith(text: Text, prefix: Text) → Bool

Verifica se um texto começa com determinado trecho de texto. Maiúsculas e minúsculas devem coincidir.

Parâmetros

  • text: Text — O texto a verificar.
  • prefix: Text — O início a procurar.

Retorna

true se text começar com prefix, ou se prefix estiver vazio; caso contrário, false.

2 exemplos: break e continue, Ler um arquivo e contar as suas linhas

StringToLower​

StringToLower(text: Text) → Text

Converte o texto em minúsculas, seguindo as regras de maiúsculas e minúsculas do formato regional do Windows do usuário (por exemplo, o i com e sem ponto do turco).

Parâmetros

  • text: Text — O texto a converter.

Retorna

O texto em minúsculas, ou o texto inalterado se o Windows não conseguir convertê-lo.

4 exemplos: Comparações sem diferenciar maiúsculas de minúsculas, A ordenação de Text é ordinal, Deixar passar um desenho não reconhecido, Contar os tipos de arquivo em uma pasta

StringToNumber​

StringToNumber(text: Text, invariantCulture: Bool) → Any

Lê um número de um texto, como uma entrada do usuário, um arquivo ou um dispositivo serial. Os espaços em volta do número são ignorados; um expoente como 1.5e3 é permitido.

Parâmetros

  • text: Text — O texto a ler.
  • invariantCulture: Bool — true para texto de máquina: ponto como separador decimal e sem agrupamento de dígitos; assim, '1,5' não é um número. false para o formato regional do usuário, como uma pessoa o digitaria; os grupos de dígitos devem então seguir esse formato, de modo que '1.234,5' é lido em português (Brasil), mas '1.5' não.

Retorna

Um Integer se o texto não tiver separador decimal nem expoente e couber; caso contrário, um Real. 0 se o texto não for um número; verifique antes com StringIsNumber.

2 exemplos: Ler um número que alguém digitou, Transformar um botão giratório de Arduino em controle de volume

StringToUpper​

StringToUpper(text: Text) → Text

Converte o texto em maiúsculas, seguindo as regras de maiúsculas e minúsculas do formato regional do Windows do usuário (por exemplo, o i com e sem ponto do turco).

Parâmetros

  • text: Text — O texto a converter.

Retorna

O texto em maiúsculas, ou o texto inalterado se o Windows não conseguir convertê-lo.

2 exemplos: Converter o texto selecionado em maiúsculas, Fazer backup de um arquivo antes de editá-lo

StringTrim​

StringTrim(text: Text) → Text

Remove espaços, tabulações, quebras de linha e outros espaços em branco do início e do fim do texto. Os espaços em branco dentro do texto são mantidos.

Parâmetros

  • text: Text — O texto a aparar.

Retorna

O texto aparado, ou texto vazio se text tinha só espaços em branco.

6 exemplos: Contar as palavras da área de transferência, Juntar as linhas da área de transferência em uma só, Pesquisar na Web o texto selecionado, Pesquisar a seleção na Web, Ler um arquivo e contar as suas linhas, Mapear os botões de um dispositivo serial para teclas de mídia

StringUrlEncode​

StringUrlEncode(text: Text) → Text · Simples

Codifica o texto para que ele possa entrar em um endereço da Web, por exemplo um termo de pesquisa montado a partir do texto selecionado. Codifique só o valor, não o endereço inteiro.

Parâmetros

  • text: Text — O texto a codificar, como um termo de pesquisa.

Retorna

O texto codificado: letras, dígitos e - . _ ~ ficam como estão; todos os outros bytes do texto UTF-8 viram um escape com o sinal de porcentagem e dois dígitos hexadecimais. Um espaço vira o sinal de porcentagem seguido de 20, não um sinal de mais.

1 exemplo: Pesquisar na Web o texto selecionado

Style​

StyleGetCurrent​

StyleGetCurrent() → Text · Simples

Retorna a chave do estilo de rastro que o plug-in renderizador desenha agora, como neonglow, ou shuffle quando Aleatório está selecionado.

Parâmetros

Sem parâmetros.

Retorna

A chave do estilo, o estilo padrão do renderizador quando nada utilizável está selecionado, ou texto vazio quando nenhum renderizador está em execução ou ele ainda não informou seus estilos.

StyleNext​

StyleNext() → Bool · Simples

Seleciona o próximo estilo de rastro desbloqueado na lista do renderizador, voltando ao início depois do fim. O novo estilo é desenhado a partir do próximo gesto.

Parâmetros

Sem parâmetros.

Retorna

true se uma troca de estilo foi solicitada; false quando nenhum renderizador está em execução ou não há outro estilo a selecionar.

StyleSet​

StyleSet(key: Text) → Bool · Simples

Seleciona o estilo de rastro do renderizador com esta chave, desenhado a partir do próximo gesto. Um botão de desenho que tem um estilo próprio o mantém.

Parâmetros

  • key: Text — A chave do estilo, como neonglow ou auto; não diferencia maiúsculas de minúsculas. Use shuffle para um estilo diferente a cada gesto.

Retorna

true se a troca de estilo foi solicitada; false se nenhum renderizador estiver em execução, se nenhum estilo tiver essa chave ou se o estilo estiver bloqueado.

System​

SystemHibernate​

SystemHibernate() → Bool · Simples

Hiberna o computador sem perguntar. O script aguarda aqui e continua depois que o computador for ligado novamente. Não faz nada se a hibernação estiver desativada no Windows.

Parâmetros

Sem parâmetros.

Retorna

true depois que o computador hibernou e foi retomado; false se a hibernação não estiver disponível ou se o Windows recusou.

SystemLock​

SystemLock() → Bool · Simples

Bloqueia o computador e mostra a tela de entrada do Windows, como faz Windows+L. Os aplicativos continuam em execução.

Parâmetros

Sem parâmetros.

Retorna

true se o Windows bloqueou o computador; false se o Windows recusou, por exemplo porque uma política desativa o bloqueio.

SystemMonitorOff​

SystemMonitorOff() → Bool · Simples

Desliga os monitores. O próximo movimento do mouse ou pressionamento de tecla os liga de novo; por isso, um script iniciado por um gesto deve chamar UtilityWait(500) antes.

Parâmetros

Sem parâmetros.

Retorna

true assim que a solicitação foi enviada ao Windows; false se não pôde ser enviada.

SystemRestart​

SystemRestart(force: Bool) → Bool · Simples

Reinicia o computador sem pedir confirmação; o Windows fecha antes os aplicativos em execução. Mostre UIShowMessageBox antes se quiser confirmar.

Parâmetros

  • force: Bool — false permite que os aplicativos peçam para salvar o trabalho não salvo (só os aplicativos que não respondem são fechados à força); true fecha todos os aplicativos imediatamente e o trabalho não salvo é perdido.

Retorna

true se o Windows aceitou a solicitação de reinicialização (ele então prossegue sozinho); false se o Windows a recusou.

SystemShutDown​

SystemShutDown(force: Bool) → Bool · Simples

Desliga o computador sem pedir confirmação. Mostre UIShowMessageBox antes se quiser confirmar.

Parâmetros

  • force: Bool — false permite que os aplicativos peçam para salvar o trabalho não salvo (só os aplicativos que não respondem são fechados à força); true fecha todos os aplicativos imediatamente e o trabalho não salvo é perdido.

Retorna

true se o Windows aceitou a solicitação de desligamento (ele então prossegue sozinho); false se o Windows a recusou.

SystemSignOut​

SystemSignOut(force: Bool) → Bool · Simples

Encerra a sessão do usuário atual no Windows sem pedir confirmação, fechando todos os aplicativos e, com eles, o Input.Observer.

Parâmetros

  • force: Bool — false permite que os aplicativos peçam para salvar o trabalho não salvo (só os aplicativos que não respondem são fechados à força); true fecha todos os aplicativos imediatamente e o trabalho não salvo é perdido.

Retorna

true se o Windows aceitou a solicitação de saída (ele então prossegue sozinho); false se o Windows a recusou.

SystemSleep​

SystemSleep() → Bool · Simples

Coloca o computador em suspensão sem perguntar. O script aguarda aqui e continua depois que o computador despertar. Em um computador com Modern Standby, não faz nada; use SystemMonitorOff nesse caso.

Parâmetros

Sem parâmetros.

Retorna

true depois que o computador entrou em suspensão e despertou; false se este computador não tiver um estado de suspensão que um programa possa iniciar ou se o Windows recusou.

Timer​

TimerCreate​

TimerCreate(name: Text, startDelayMs: Integer, intervalMs: Integer, repeatCount: Integer, script: Text) → Bool

Cria um timer nomeado que executa um texto de script após um atraso e depois em um intervalo fixo, ou substitui o timer com esse nome. Os timers continuam em execução depois que o script termina, até serem excluídos ou o mecanismo sair.

Parâmetros

  • name: Text — Um nome para o timer, usado por TimerDelete. Diferencia maiúsculas de minúsculas; um timer existente com esse nome é substituído.
  • startDelayMs: Integer — Atraso antes da primeira execução, em milissegundos; 0 ou mais.
  • intervalMs: Integer — Tempo entre execuções, em milissegundos; 1 ou mais. Uma execução não aguarda a anterior terminar.
  • repeatCount: Integer — Quantas vezes executar no total; 0 repete até o timer ser excluído.
  • script: Text — O texto do script a executar a cada disparo. Ele é executado de forma independente, sem contexto de gatilho e sem nenhuma das variáveis deste script.

Retorna

true assim que o timer estiver definido. Um startDelayMs ou repeatCount negativo, ou um intervalMs menor que 1, interrompe o script com um erro.

2 exemplos: Um temporizador repetitivo que conta, Script de temporizador a partir de um snippet, sem escapes

TimerDelete​

TimerDelete(name: Text) → Bool

Remove o timer com este nome para que ele não seja executado novamente.

Parâmetros

  • name: Text — O nome do timer, conforme passado a TimerCreate. Diferencia maiúsculas de minúsculas.

Retorna

true se o timer existia e foi removido; false se não havia timer com esse nome.

1 exemplo: Listar e parar temporizadores

TimerDeleteAll​

TimerDeleteAll() → Bool

Remove todos os timers criados com TimerCreate, para que nenhum deles seja executado novamente.

Parâmetros

Sem parâmetros.

Retorna

Sempre true.

1 exemplo: Listar e parar temporizadores

TimerEnumerateAll​

TimerEnumerateAll() → Integer

Monta uma lista dos nomes de todos os timers atuais e retorna quantos são. Leia cada nome com TimerGetEnumeratedNameAt.

Parâmetros

Sem parâmetros.

Retorna

O número de timers, ou 0 se não houver nenhum.

1 exemplo: Listar e parar temporizadores

TimerGetEnumeratedNameAt​

TimerGetEnumeratedNameAt(index: Integer) → Text

Retorna um nome de timer da lista que TimerEnumerateAll montou por último neste script.

Parâmetros

  • index: Integer — Posição na lista, a partir de zero, de 0 à contagem menos 1. A ordem não tem significado.

Retorna

O nome do timer, ou texto vazio se index estiver fora do intervalo ou se TimerEnumerateAll não tiver sido chamada.

1 exemplo: Listar e parar temporizadores

Tray​

TrayMinimizeWindow​

TrayMinimizeWindow(window: Window) → Bool

Oculta uma janela e mostra um ícone na bandeja para ela, com o ícone e o título da própria janela. Clicar no ícone restaura a janela onde ela estava. Para um controle, a janela de nível superior dele é a que fica oculta.

Parâmetros

  • window: Window — A janela a ocultar, como ContextGetWindow().

Retorna

true se a solicitação foi aceita; false para uma janela nula ou que não existe mais.

1 exemplo: Esconder uma janela na bandeja

TrayRestoreAllWindows​

TrayRestoreAllWindows() → Bool

Restaura todas as janelas ocultadas com TrayMinimizeWindow e remove os ícones delas da bandeja.

Parâmetros

Sem parâmetros.

Retorna

true se a solicitação foi enviada; false se o mecanismo ainda não terminou de iniciar.

UI​

UIClearPrintLog​

UIClearPrintLog() → Bool

Limpa a guia Usuário do console de diagnóstico, onde aparece a saída de UtilityPrint, inclusive a saída guardada enquanto o console estava fechado.

Parâmetros

Sem parâmetros.

Retorna

Sempre true.

UICloseDisplayMessage​

UICloseDisplayMessage(sessionId: Integer) → Bool

Fecha uma mensagem na tela aberta por UIShowDisplayMessage. Não faz nada se essa mensagem já tiver sido fechada.

Parâmetros

  • sessionId: Integer — O id que UIShowDisplayMessage retornou para a mensagem a fechar.

Retorna

Sempre true, inclusive quando a mensagem já tinha sido fechada.

1 exemplo: Uma mensagem na tela atualizada ao vivo

UIGetCulture​

UIGetCulture() → Text

Retorna o idioma e a região que o Input.Observer usa para o próprio texto (menu da bandeja, mensagens, textos de erro), conforme definido por UISetCulture, pela configuração de idioma ou pelo Windows.

Parâmetros

Sem parâmetros.

Retorna

O nome da cultura como foi definido, como en-US ou es-ES, mesmo quando a tradução de outra região o substitui.

UISetCulture​

UISetCulture(culture: Text) → Bool

Muda o idioma que o Input.Observer usa para o próprio texto (menu da bandeja, mensagens, textos de erro) até ele sair ou a configuração de idioma mudar. Não altera a janela de configurações nem a configuração salva.

Parâmetros

  • culture: Text — Um nome de cultura como en-US, de-DE ou es-MX.

Retorna

true se a cultura foi aplicada; false, e o idioma continua como estava, se culture não for uma cultura que o Windows conhece ou se o Input.Observer não tiver tradução no idioma dela. Outra região de um idioma traduzido, como es-ES, é aceita.

UIShowConsole​

UIShowConsole() → Bool

Abre o console de diagnóstico, ou o traz para a frente se ele já estiver aberto, e aguarda até que esteja aberto. Se a configuração estiver protegida por senha, aguarda enquanto a senha é solicitada. Só o próprio botão de fechar do console o fecha.

Parâmetros

Sem parâmetros.

Retorna

true assim que o console estiver aberto; false se ele não abriu, por exemplo porque a solicitação de senha foi cancelada ou o estado salvo do console não pode ser lido.

UIShowDisplayMessage​

UIShowDisplayMessage(title: Text, message: Text, durationMs: Integer, opacity: Real, location: Any, titleFontFamily: Text, titleFontSizePt: Integer, titleBold: Bool, titleItalic: Bool, messageFontFamily: Text, messageFontSizePt: Integer, messageBold: Bool, messageItalic: Bool, foreColor: Text, backColor: Text, paddingPx: Integer, usePrimaryScreen: Bool, titleAlign: Integer, messageAlign: Integer) → Integer · Simples

Mostra um painel com uma linha de título e uma linha de mensagem em um lugar fixo da tela e retorna imediatamente. Vários podem ficar abertos juntos; guarde o id retornado para atualizar ou fechar este.

Parâmetros

  • title: Text — Texto da linha superior, desenhado com a fonte do título. Texto vazio omite a linha.
  • message: Text — Texto da segunda linha, desenhado com a fonte da mensagem. Texto longo quebra em mais linhas. Texto vazio omite a linha.
  • durationMs: Integer — Por quanto tempo o painel permanece, em milissegundos. 0 ou menos o mantém até que UICloseDisplayMessage o feche (o painel interno também fecha com um clique duplo).
  • opacity: Real — O quanto o painel é sólido, de 0.05 (quase invisível) a 1.0 (totalmente opaco). Valores fora desse intervalo são limitados a ele.
  • location: Any — Onde mostrá-lo: uma constante Location como Location.BottomCenter (posicionado dentro da área da tela não coberta pela barra de tarefas), ou o Text 'x,y' sem espaços indicando o canto superior esquerdo do painel em pixels da tela, como '100,200'. Qualquer outra coisa interrompe a ação com um erro.
  • titleFontFamily: Text — Nome da fonte da linha de título, como Segoe UI.
  • titleFontSizePt: Integer — Tamanho da fonte do título em pontos. Valores menores que 1 contam como 1.
  • titleBold: Bool — true para desenhar a linha de título em negrito.
  • titleItalic: Bool — true para desenhar a linha de título em itálico.
  • messageFontFamily: Text — Nome da fonte da linha de mensagem, como Segoe UI.
  • messageFontSizePt: Integer — Tamanho da fonte da mensagem em pontos. Valores menores que 1 contam como 1.
  • messageBold: Bool — true para desenhar a linha de mensagem em negrito.
  • messageItalic: Bool — true para desenhar a linha de mensagem em itálico.
  • foreColor: Text — Cor do texto das duas linhas: um nome de cor como white ou black, '#RRGGBB', ou 'R,G,B' com cada número de 0 a 255 e sem espaços. Qualquer outra coisa interrompe a ação com um erro.
  • backColor: Text — Cor de fundo, nas mesmas formas que foreColor, como '#F7F7F5'. Use opacity, não a cor, para deixar o painel translúcido.
  • paddingPx: Integer — Espaço vazio em volta do texto, em pixels com escala de exibição de 100 por cento; ele cresce com a escala de exibição. Valores menores que 0 contam como 0.
  • usePrimaryScreen: Bool — true para posicionar um Location no monitor principal; false para usar o monitor em que o ponteiro do mouse está agora. Ignorado para um local 'x,y'.
  • titleAlign: Integer — Como a linha de título é alinhada: TextAlign.Left, TextAlign.Center ou TextAlign.Right. Qualquer outro valor interrompe a ação com um erro.
  • messageAlign: Integer — Como a linha de mensagem é alinhada: TextAlign.Left, TextAlign.Center ou TextAlign.Right. Qualquer outro valor interrompe a ação com um erro.

Retorna

O id de sessão da mensagem, sempre maior que 0, para UIUpdateDisplayMessage e UICloseDisplayMessage. Um id é retornado mesmo quando as mensagens estão desativadas nas configurações e nada aparece.

2 exemplos: Aumentar o volume com uma indicação na tela, Uma mensagem na tela atualizada ao vivo

UIShowInputBox​

UIShowInputBox(prompt: Text, title: Text, defaultText: Text) → Text · Simples

Mostra uma caixa que pede ao usuário que digite uma linha de texto, com os botões OK e Cancelar. Bloqueia o script até a caixa fechar e depois devolve o foco à janela que o tinha.

Parâmetros

  • prompt: Text — A pergunta mostrada acima do campo de texto. Um texto com mais de 2000 caracteres é cortado.
  • title: Text — Título mostrado na barra de título da caixa.
  • defaultText: Text — Texto que já está no campo quando a caixa abre, selecionado para que digitar o substitua. Use texto vazio para um campo vazio.

Retorna

O texto digitado quando o usuário clica em OK (até 4096 caracteres), ou texto vazio com Cancelar, Esc ou o botão de fechar. Um OK com o campo vazio também retorna texto vazio.

2 exemplos: Ler um número que alguém digitou, Um gesto, várias opções

UIShowMenu​

UIShowMenu(items: Text) → Integer · Simples

Mostra um menu pop-up no ponteiro do mouse, para que um gesto ou uma tecla de atalho possa oferecer várias opções. Bloqueia o script até o usuário escolher um item ou descartar o menu.

Parâmetros

  • items: Text — Os itens do menu, um por linha. Uma linha com apenas - é um separador; linhas em branco são ignoradas. De 1 a 100 itens, ou a ação é interrompida com um erro; um item com mais de 260 caracteres é cortado. Coloque & antes de uma letra para torná-la a tecla de atalho do item; && mostra um único &.

Retorna

A posição, a partir de 0, do item escolhido, contando só os itens (não os separadores), ou -1 se o menu foi descartado ou não pôde ser mostrado.

1 exemplo: Um gesto, várias opções

UIShowMessageBox​

UIShowMessageBox(message: Text, title: Text, buttons: Text, icon: Text) → Text · Simples

Mostra uma caixa de mensagem padrão do Windows na frente das outras janelas e aguarda o usuário pressionar um botão. Bloqueia o script até a caixa fechar.

Parâmetros

  • message: Text — O texto da mensagem mostrado na caixa.
  • title: Text — Título mostrado na barra de título da caixa.
  • buttons: Text — Os botões a mostrar, escritos exatamente assim: OK, OKCancel, YesNo, YesNoCancel, RetryCancel ou AbortRetryIgnore. Qualquer outra coisa interrompe a ação com um erro.
  • icon: Text — O ícone a mostrar, escrito exatamente assim: None, Information, Warning, Error ou Question. Qualquer outra coisa interrompe a ação com um erro.

Retorna

O botão pressionado: OK, Cancel, Yes, No, Retry, Abort ou Ignore (fechar a caixa com Esc ou com o botão de fechar retorna Cancel quando há um botão Cancelar). Texto vazio se a caixa não pôde ser mostrada.

3 exemplos: Ler um número que alguém digitou, Fechar janelas por padrão de título, após confirmação, Fazer uma pergunta

UIShowSettings​

UIShowSettings() → Bool · Simples

Abre a janela de configuração do Input.Observer, ou a traz para a frente se ela já estiver aberta. Retorna sem aguardar a janela terminar de carregar.

Parâmetros

Sem parâmetros.

Retorna

true se a janela de configuração foi trazida para a frente ou iniciada; false se Input.Observer.UI.exe não existir, não puder ser iniciado ou se o mecanismo não responder em 3 segundos.

UIUpdateDisplayMessage​

UIUpdateDisplayMessage(sessionId: Integer, title: Text, message: Text, durationMs: Integer, opacity: Real, location: Any, titleFontFamily: Text, titleFontSizePt: Integer, titleBold: Bool, titleItalic: Bool, messageFontFamily: Text, messageFontSizePt: Integer, messageBold: Bool, messageItalic: Bool, foreColor: Text, backColor: Text, paddingPx: Integer, usePrimaryScreen: Bool, titleAlign: Integer, messageAlign: Integer) → Bool

Substitui tudo em um painel aberto de UIShowDisplayMessage (texto, posição, fontes, cores e duração) por novos valores. A duração recomeça a partir desta chamada.

Parâmetros

  • sessionId: Integer — O id que UIShowDisplayMessage retornou para a mensagem a alterar.
  • title: Text — Novo texto da linha superior, desenhado com a fonte do título. Texto vazio omite a linha.
  • message: Text — Novo texto da segunda linha, desenhado com a fonte da mensagem. Texto longo quebra em mais linhas. Texto vazio omite a linha.
  • durationMs: Integer — Por quanto tempo o painel permanece a partir de agora, em milissegundos. 0 ou menos o mantém até que UICloseDisplayMessage o feche (o painel interno também fecha com um clique duplo).
  • opacity: Real — O quanto o painel é sólido, de 0.05 (quase invisível) a 1.0 (totalmente opaco). Valores fora desse intervalo são limitados a ele.
  • location: Any — Onde mostrá-lo: uma constante Location como Location.BottomCenter (posicionado dentro da área da tela não coberta pela barra de tarefas), ou o Text 'x,y' sem espaços indicando o canto superior esquerdo do painel em pixels da tela, como '100,200'. Qualquer outra coisa interrompe a ação com um erro.
  • titleFontFamily: Text — Nome da fonte da linha de título, como Segoe UI.
  • titleFontSizePt: Integer — Tamanho da fonte do título em pontos. Valores menores que 1 contam como 1.
  • titleBold: Bool — true para desenhar a linha de título em negrito.
  • titleItalic: Bool — true para desenhar a linha de título em itálico.
  • messageFontFamily: Text — Nome da fonte da linha de mensagem, como Segoe UI.
  • messageFontSizePt: Integer — Tamanho da fonte da mensagem em pontos. Valores menores que 1 contam como 1.
  • messageBold: Bool — true para desenhar a linha de mensagem em negrito.
  • messageItalic: Bool — true para desenhar a linha de mensagem em itálico.
  • foreColor: Text — Cor do texto das duas linhas: um nome de cor como white ou black, '#RRGGBB', ou 'R,G,B' com cada número de 0 a 255 e sem espaços. Qualquer outra coisa interrompe a ação com um erro.
  • backColor: Text — Cor de fundo, nas mesmas formas que foreColor, como '#F7F7F5'. Use opacity, não a cor, para deixar o painel translúcido.
  • paddingPx: Integer — Espaço vazio em volta do texto, em pixels com escala de exibição de 100 por cento; ele cresce com a escala de exibição. Valores menores que 0 contam como 0.
  • usePrimaryScreen: Bool — true para posicionar um Location no monitor principal; false para usar o monitor em que o ponteiro do mouse está agora. Ignorado para um local 'x,y'.
  • titleAlign: Integer — Como a linha de título é alinhada: TextAlign.Left, TextAlign.Center ou TextAlign.Right. Qualquer outro valor interrompe a ação com um erro.
  • messageAlign: Integer — Como a linha de mensagem é alinhada: TextAlign.Left, TextAlign.Center ou TextAlign.Right. Qualquer outro valor interrompe a ação com um erro.

Retorna

Sempre true, inclusive quando a mensagem já tinha sido fechada (a chamada então não faz nada).

1 exemplo: Uma mensagem na tela atualizada ao vivo

Utility​

UtilityGetTickCount​

UtilityGetTickCount() → Integer

Retorna o número de milissegundos desde que o Windows foi iniciado. Subtraia duas leituras para medir o tempo decorrido, por exemplo para detectar um gatilho duplo. Não é um relógio; use DateTimeGetNow para a hora do dia.

Parâmetros

Sem parâmetros.

Retorna

Milissegundos desde que o Windows foi iniciado, como Integer.

UtilityLockAcquire​

UtilityLockAcquire(name: Text, timeoutSeconds: Integer) → Integer

Obtém um bloqueio nomeado para que só uma ação por vez execute um trecho de script. Bloqueia o script até o bloqueio ficar livre ou timeoutSeconds passar. O bloqueio é liberado automaticamente quando o script termina.

Parâmetros

  • name: Text — O nome do bloqueio, de 1 a 255 caracteres, compartilhado por todas as ações; maiúsculas e minúsculas são iguais. Obter de novo um bloqueio que este script já tem é permitido e exige mais um UtilityLockRelease.
  • timeoutSeconds: Integer — O tempo máximo de espera, em segundos. 0, ou mais de 24 dias, aguarda até o bloqueio ficar livre ou a ação ser interrompida. Um valor negativo interrompe a ação com um erro.

Retorna

LockResult.Acquired, LockResult.TimedOut (também quando a ação é interrompida durante a espera) ou, imediatamente, LockResult.Pinned se o bloqueio estiver fixado.

1 exemplo: Deixar só uma ação executar um trecho por vez

UtilityLockAcquirePinned​

UtilityLockAcquirePinned(name: Text, timeoutSeconds: Integer) → Integer

Obtém um bloqueio nomeado e o fixa, para que continue obtido depois que o script terminar. Só UtilityLockRelease desta mesma execução do script, ou um recarregamento da configuração, o libera. Bloqueia como UtilityLockAcquire.

Parâmetros

  • name: Text — O nome do bloqueio, de 1 a 255 caracteres, compartilhado por todas as ações; maiúsculas e minúsculas são iguais. Um bloqueio que este script já tem passa a ficar fixado.
  • timeoutSeconds: Integer — O tempo máximo de espera, em segundos. 0, ou mais de 24 dias, aguarda até o bloqueio ficar livre ou a ação ser interrompida. Um valor negativo interrompe a ação com um erro.

Retorna

LockResult.Acquired, LockResult.TimedOut (também quando a ação é interrompida durante a espera) ou, imediatamente, LockResult.Pinned se o bloqueio já estiver fixado.

UtilityLockGetState​

UtilityLockGetState(name: Text) → Integer

Informa se um bloqueio nomeado está livre, mantido por este script, mantido por outra ação ou fixado. Nunca aguarda.

Parâmetros

  • name: Text — O nome do bloqueio, de 1 a 255 caracteres; maiúsculas e minúsculas são iguais.

Retorna

LockState.Free, LockState.HeldByMe, LockState.HeldByOther ou LockState.Pinned. Um bloqueio fixado informa LockState.Pinned mesmo para o script que o fixou.

UtilityLockRelease​

UtilityLockRelease(name: Text) → Bool

Libera um bloqueio nomeado que este script mantém, ou remove a fixação dele. Um bloqueio obtido várias vezes é liberado após o mesmo número de liberações.

Parâmetros

  • name: Text — O nome do bloqueio, de 1 a 255 caracteres; maiúsculas e minúsculas são iguais.

Retorna

true se este script mantinha o bloqueio; false, sem fazer nada, se ninguém o mantém ou se outra ação o mantém.

1 exemplo: Deixar só uma ação executar um trecho por vez

UtilityPrint​

UtilityPrint(text: Text) → Bool

Escreve uma linha de texto na seção Usuário do console de diagnóstico, ou na saída da seção Script quando o script é executado de lá. As linhas impressas enquanto o console está fechado aparecem quando ele for aberto novamente.

Parâmetros

  • text: Text — O texto a escrever. Transforme antes um número em Text com StringFormat ou StringFromNumber.

Retorna

Sempre true.

70 exemplos: Olá, console, Os cinco tipos de valor, Valor verdadeiro de cada tipo, Encadeamento else-if, Loops de contagem: crescente, decrescente e em saltos, Loops aninhados: uma tabuada, Loop while: aguardar uma janela, com tempo limite, while (true) com um sinalizador de saída, break e continue, Surpresas de precedência, && e || avaliam os dois lados, Igualdade entre tipos, Aritmética com tipos mistos resulta em 0, Comentários, instruções vazias e blocos, Divisão de Integer e de Real, e divisão por zero, Resto sem %, Arredondamento e funções internas de matemática com Real, Limitar um valor a um intervalo, Números aleatórios e cara ou coroa, Comprimento do traço de um gesto, Formatar um Real sem seis casas decimais, Máscaras de sinalizadores: ativar, desativar, inverter, testar, Ler a cor do pixel sob o cursor, Integer para texto hexadecimal, Contar os bits ativos, Casos extremos de deslocamento, Trocar dois Integers, Bits de estado de tecla, Sequências de escape e caminhos do Windows, Formatar mais de dois valores, Dividir e percorrer, Divisões aninhadas: pares chave=valor, Último índice de: uma extensão de arquivo, Ler um número que alguém digitou, Iniciar um programa, aguardar a janela dele e agir sobre ela, Extrair um valor de um texto copiado com uma expressão regular, Preencher um número com zeros à esquerda, Inverter um Text, Contar as palavras da área de transferência, Comparações sem diferenciar maiúsculas de minúsculas, A ordenação de Text é ordinal, A data de hoje e um nome de arquivo com carimbo de data e hora, Constantes nomeadas vs. números brutos, Listar as janelas de nível superior visíveis, Minimizar todas as janelas de um aplicativo, Inspecionar os controles filhos de uma janela, Do processo à janela, Descrever o que está sob o cursor, Tudo o que o contexto do gatilho sabe, Para que lado o traço foi?, Ramificar conforme o botão do traço, Salvar uma imagem copiada em um arquivo, Ler um arquivo e contar as suas linhas, Contar os tipos de arquivo em uma pasta, Monitorar uma pasta, Um temporizador repetitivo que conta, Listar e parar temporizadores, Um contador que sobrevive a uma reinicialização, Uma lista guardada no Storage, Deixar só uma ação executar um trecho por vez, Fazer uma pergunta, Expandir variáveis de ambiente, Passar o trabalho ao AutoHotkey, Listar os monitores, Estado do mecanismo, Snippets como funções reutilizáveis, Comunicar-se com um plug-in, Fazer uma pergunta a um dispositivo serial, Listar as portas COM, Manter a porta de um Arduino aberta e enviar comandos a ele

UtilityWait​

UtilityWait(milliseconds: Integer) → Bool · Simples

Pausa o script por um número de milissegundos, por exemplo para dar tempo a uma janela ou à área de transferência. A espera termina antes se a ação for interrompida.

Parâmetros

  • milliseconds: Integer — Quanto tempo aguardar, em milissegundos, de 0 a 60000 (um minuto). Valores maiores aguardam um minuto; valores negativos não aguardam.

Retorna

Sempre true.

10 exemplos: Loop while: aguardar uma janela, com tempo limite, Mover o mouse em círculo, Preencher um modelo e colá-lo, Clicar em algum lugar e devolver o cursor, Um arrastar por script, Confinar o cursor a uma janela por 5 segundos, Teclas de mídia, Converter o texto selecionado em maiúsculas, Pesquisar a seleção na Web, Uma mensagem na tela atualizada ao vivo

Window​

WindowCenterToScreen​

WindowCenterToScreen(window: Window) → Bool · Simples

Move uma janela para que fique centralizada na área de trabalho (a tela menos a barra de tarefas) do monitor em que está, mantendo o tamanho dela.

Parâmetros

  • window: Window — A janela a centralizar.

Retorna

true se a janela foi movida; false se a janela for nula ou estiver fechada, ou se ela se recusou a se mover.

2 exemplos: Loop while: aguardar uma janela, com tempo limite, Lembrar e restaurar a posição de uma janela

WindowClipToScreen​

WindowClipToScreen(window: Window) → Bool

Reduz e move uma janela só o necessário para que nenhuma borda ultrapasse a área de trabalho (a tela menos a barra de tarefas) do monitor em que está. Uma janela totalmente fora da área de trabalho é primeiro movida para dentro dela no tamanho atual.

Parâmetros

  • window: Window — A janela a ajustar à área de trabalho.

Retorna

true se a janela foi posicionada, inclusive quando já estava dentro da área de trabalho; false se a janela for nula ou estiver fechada, ou se ela recusou a alteração.

WindowClose​

WindowClose(window: Window) → Bool · Simples

Pede que uma janela seja fechada, como se o usuário clicasse no botão de fechar dela. O programa pode pedir para salvar alterações ou recusar; use WindowWaitClose para aguardar até que ela desapareça.

Parâmetros

  • window: Window — A janela a fechar.

Retorna

true se a solicitação de fechamento foi enviada, o que não significa que a janela foi fechada; false se a janela for nula ou estiver fechada, ou se pertencer a um programa executado com privilégios mais altos, como administrador.

3 exemplos: Fechar janelas por padrão de título, após confirmação, Ramificar conforme o botão do traço, Mudar o comportamento enquanto Ctrl está pressionada

WindowContainsTitle​

WindowContainsTitle(window: Window, text: Text) → Bool

Verifica se o título de uma janela contém um texto, ignorando maiúsculas e minúsculas.

Parâmetros

  • window: Window — A janela cujo título verificar.
  • text: Text — O texto a procurar em qualquer posição do título. Maiúsculas e minúsculas são ignoradas.

Retorna

true se o título contiver text, e sempre true quando text estiver vazio; caso contrário, false, inclusive para uma janela nula ou fechada.

WindowControlFromPoint​

WindowControlFromPoint(x: Integer, y: Integer) → Window

Retorna a janela mais interna em um ponto da tela, como um botão, uma caixa de texto ou outro controle dentro da janela de um programa. Janelas ocultas e desabilitadas são ignoradas.

Parâmetros

  • x: Integer — Posição horizontal na tela, em pixels da tela virtual.
  • y: Integer — Posição vertical na tela, em pixels da tela virtual.

Retorna

O controle ou a janela sob o ponto, ou uma janela nula se não houver nenhum.

1 exemplo: Descrever o que está sob o cursor

WindowEnsureVisible​

WindowEnsureVisible(window: Window) → Bool

Desliza uma janela para que fique inteiramente na área de trabalho do monitor em que está, sem redimensioná-la. Uma janela maior que a área de trabalho é alinhada ao canto superior esquerdo da área de trabalho.

Parâmetros

  • window: Window — A janela a trazer inteiramente para a tela.

Retorna

true se a janela foi posicionada, inclusive quando já estava totalmente visível; false se a janela for nula ou estiver fechada, ou se ela se recusou a se mover.

WindowFindAllByModuleRegex​

WindowFindAllByModuleRegex(pattern: Text) → Integer

Localiza todas as janelas de nível superior, inclusive as ocultas, cujo caminho do arquivo do programa corresponda a uma expressão regular, e guarda a lista para WindowGetEnumeratedAt. Substitui qualquer lista de janelas anterior.

Parâmetros

  • pattern: Text — Uma expressão regular comparada, sem diferenciar maiúsculas de minúsculas, com o caminho completo do programa dono de cada janela, como 'notepad[.]exe$'.

Retorna

O número de janelas correspondentes, ou 0 se nenhuma corresponder. Um padrão inválido interrompe a ação com um erro.

1 exemplo: Minimizar todas as janelas de um aplicativo

WindowFindAllByTitleRegex​

WindowFindAllByTitleRegex(pattern: Text) → Integer

Localiza todas as janelas de nível superior, inclusive as ocultas, cujo título corresponda a uma expressão regular, e guarda a lista para WindowGetEnumeratedAt. Substitui qualquer lista de janelas anterior.

Parâmetros

  • pattern: Text — Uma expressão regular comparada com o título de cada janela, sem diferenciar maiúsculas de minúsculas. Ela corresponde em qualquer posição do título, a menos que seja ancorada com ^ ou $.

Retorna

O número de janelas correspondentes, ou 0 se nenhuma corresponder. Um padrão inválido interrompe a ação com um erro.

1 exemplo: Fechar janelas por padrão de título, após confirmação

WindowFindByClassName​

WindowFindByClassName(className: Text) → Window

Localiza a janela de nível superior visível mais à frente cujo nome de classe contenha o texto indicado, ignorando maiúsculas e minúsculas.

Parâmetros

  • className: Text — Texto a procurar no nome da classe, como 'Notepad'. Parte de um nome já corresponde; texto vazio corresponde à janela visível mais à frente.

Retorna

A janela encontrada, ou uma janela nula se nenhuma janela de nível superior visível corresponder.

WindowFindByTitle​

WindowFindByTitle(title: Text) → Window

Localiza a janela de nível superior visível mais à frente cujo título contenha o texto indicado, ignorando maiúsculas e minúsculas.

Parâmetros

  • title: Text — Texto a procurar em qualquer posição do título. Maiúsculas e minúsculas são ignoradas; texto vazio corresponde à janela visível mais à frente.

Retorna

A janela encontrada, ou uma janela nula se nenhuma janela de nível superior visível corresponder.

4 exemplos: Valor verdadeiro de cada tipo, Loop while: aguardar uma janela, com tempo limite, Igualdade entre tipos, Clicar em um ponto dentro de uma janela

WindowFitToScreen​

WindowFitToScreen(window: Window) → Bool · Simples

Redimensiona e move uma janela para que suas bordas visíveis preencham a área de trabalho (a tela menos a barra de tarefas) do monitor em que está, sem maximizá-la.

Parâmetros

  • window: Window — A janela a ajustar à área de trabalho.

Retorna

true se a janela foi redimensionada; false se a janela for nula ou estiver fechada, ou se ela recusou a alteração.

WindowFromPoint​

WindowFromPoint(x: Integer, y: Integer) → Window

Retorna a janela de nível superior em um ponto da tela, como a janela do programa sob o mouse, em vez do controle dentro dela.

Parâmetros

  • x: Integer — Posição horizontal na tela, em pixels da tela virtual.
  • y: Integer — Posição vertical na tela, em pixels da tela virtual.

Retorna

A janela de nível superior sob o ponto, ou uma janela nula se não houver nenhuma.

WindowFromProcessId​

WindowFromProcessId(processId: Integer) → Window

Retorna a janela principal de um programa em execução: a janela de nível superior visível mais à frente pertencente a esse processo.

Parâmetros

  • processId: Integer — O ID do processo, conforme retornado por WindowGetProcessId ou ShellGetEnumeratedProcessIdAt.

Retorna

A janela, ou uma janela nula se o processo não tiver janela de nível superior visível ou se processId for 0.

1 exemplo: Do processo à janela

WindowGetActive​

WindowGetActive() → Window

Retorna a janela em primeiro plano: a janela de nível superior em que o usuário está trabalhando no momento.

Parâmetros

Sem parâmetros.

Retorna

A janela ativa, ou uma janela nula se nenhuma janela estiver ativa naquele momento, por exemplo enquanto o foco está mudando.

4 exemplos: Os cinco tipos de valor, Formatar mais de dois valores, Comparações sem diferenciar maiúsculas de minúsculas, Encaixar a janela ativa na metade esquerda do seu monitor

WindowGetAllChildren​

WindowGetAllChildren(window: Window, directOnly: Bool) → Integer

Lista as janelas filhas (controles) dentro de uma janela e guarda a lista para WindowGetEnumeratedAt. Substitui qualquer lista de janelas anterior.

Parâmetros

  • window: Window — A janela cujas janelas filhas listar.
  • directOnly: Bool — true somente para os filhos diretos da janela; false para todos os descendentes em qualquer nível.

Retorna

O número de janelas filhas encontradas, ou 0 se não houver nenhuma ou se a janela for nula.

1 exemplo: Inspecionar os controles filhos de uma janela

WindowGetAllProps​

WindowGetAllProps(window: Window) → Integer

Lista todas as propriedades armazenadas em uma janela, por este mecanismo, pelo próprio programa ou por outro software, e guarda a lista para WindowGetEnumeratedPropNameAt e WindowGetEnumeratedPropValueAt.

Parâmetros

  • window: Window — A janela cujas propriedades listar.

Retorna

O número de propriedades encontradas, ou 0 se não houver nenhuma ou se a janela for nula.

WindowGetAllTopLevel​

WindowGetAllTopLevel() → Integer

Lista todas as janelas de nível superior da Área de Trabalho, da frente para trás, inclusive as ocultas e camufladas, e guarda a lista para WindowGetEnumeratedAt. Substitui qualquer lista de janelas anterior.

Parâmetros

Sem parâmetros.

Retorna

O número de janelas de nível superior encontradas.

1 exemplo: Listar as janelas de nível superior visíveis

WindowGetAlpha​

WindowGetAlpha(window: Window) → Integer

Retorna o nível de transparência de uma janela, conforme definido por WindowSetAlpha ou pelo próprio programa.

Parâmetros

  • window: Window — A janela a ler.

Retorna

Um valor de 0 (totalmente transparente) a 255 (totalmente opaco). 255 para uma janela sem transparência definida e para uma janela nula ou fechada.

1 exemplo: Alternar a transparência da janela em ciclo

WindowGetClassName​

WindowGetClassName(window: Window) → Text

Retorna o nome de classe de uma janela, o nome de tipo que o Windows usa para ela, como 'Notepad' ou 'Button'. Útil para reconhecer janelas cujos títulos mudam.

Parâmetros

  • window: Window — A janela a ler.

Retorna

O nome da classe, ou texto vazio se a janela for nula ou estiver fechada.

2 exemplos: Inspecionar os controles filhos de uma janela, Descrever o que está sob o cursor

WindowGetControlText​

WindowGetControlText(window: Window) → Text

Lê o texto de um controle em qualquer programa, como uma caixa de texto, uma barra de status ou a mensagem de uma caixa de diálogo. Funciona somente com controles clássicos do Windows. Bloqueia o script por até 2 segundos se o programa não responder.

Parâmetros

  • window: Window — O controle ou a janela a ler, por exemplo obtido com WindowControlFromPoint ou WindowGetEnumeratedAt.

Retorna

O texto do controle, até cerca de um milhão de caracteres, ou texto vazio se ele não tiver texto, se a janela for nula ou estiver fechada, ou se o programa não respondeu. A caixa de senha de outro programa dá texto vazio.

WindowGetDpi​

WindowGetDpi(window: Window) → Integer

Retorna o DPI do monitor em que uma janela está: 96 com escala de exibição de 100 por cento, 144 com 150 por cento.

Parâmetros

  • window: Window — A janela a verificar.

Retorna

O DPI, ou 0 se a janela for nula ou estiver fechada.

WindowGetEnabled​

WindowGetEnabled(window: Window) → Bool

Verifica se uma janela aceita entrada de mouse e teclado. Uma janela ou um controle desabilitado normalmente aparece esmaecido.

Parâmetros

  • window: Window — A janela a verificar.

Retorna

true se a janela estiver habilitada; false se estiver desabilitada, for nula ou estiver fechada.

WindowGetEnumeratedAt​

WindowGetEnumeratedAt(index: Integer) → Window

Retorna uma janela da lista montada pela chamada mais recente a WindowGetAllTopLevel, WindowGetAllChildren, WindowFindAllByTitleRegex ou WindowFindAllByModuleRegex.

Parâmetros

  • index: Integer — Posição na lista, de 0 até a contagem retornada pela chamada de listagem menos 1.

Retorna

A janela nessa posição, ou uma janela nula se index estiver fora do intervalo.

4 exemplos: Listar as janelas de nível superior visíveis, Minimizar todas as janelas de um aplicativo, Fechar janelas por padrão de título, após confirmação, Inspecionar os controles filhos de uma janela

WindowGetEnumeratedPropNameAt​

WindowGetEnumeratedPropNameAt(index: Integer) → Text

Retorna o nome de uma propriedade da lista montada pela chamada mais recente a WindowGetAllProps.

Parâmetros

  • index: Integer — Posição na lista, de 0 até a contagem retornada por WindowGetAllProps menos 1.

Retorna

O nome da propriedade, ou texto vazio se index estiver fora do intervalo.

WindowGetEnumeratedPropValueAt​

WindowGetEnumeratedPropValueAt(index: Integer) → Integer

Retorna o valor inteiro bruto de uma propriedade da lista montada pela chamada mais recente a WindowGetAllProps. Uma propriedade definida com WindowSetPropertyText mostra aqui um número interno, não o texto.

Parâmetros

  • index: Integer — Posição na lista, de 0 até a contagem retornada por WindowGetAllProps menos 1.

Retorna

O valor da propriedade, ou 0 se index estiver fora do intervalo.

WindowGetExecutableFolder​

WindowGetExecutableFolder(window: Window) → Text

Retorna a pasta que contém o programa dono de uma janela, sem o nome do arquivo e sem separador no final. Use WindowGetExecutableName para o nome do arquivo, ou WindowGetExecutableFullPath para ambos.

Parâmetros

  • window: Window — A janela cujo programa localizar.

Retorna

O caminho da pasta, ou texto vazio se a janela for nula ou estiver fechada ou se o programa não puder ser consultado.

WindowGetExecutableFullPath​

WindowGetExecutableFullPath(window: Window) → Text

Retorna o caminho completo do programa dono de uma janela, pasta e nome do arquivo juntos, como o caminho de notepad.exe na pasta do Windows. Use WindowGetExecutableFolder ou WindowGetExecutableName para uma das partes.

Parâmetros

  • window: Window — A janela cujo programa localizar.

Retorna

O caminho completo, ou texto vazio se a janela for nula ou estiver fechada ou se o programa não puder ser consultado.

WindowGetExecutableName​

WindowGetExecutableName(window: Window) → Text

Retorna o nome do arquivo do programa dono de uma janela, como 'notepad.exe'.

Parâmetros

  • window: Window — A janela cujo programa identificar.

Retorna

O nome do arquivo do programa, ou texto vazio se a janela for nula ou estiver fechada ou se o programa não puder ser consultado.

2 exemplos: Comparações sem diferenciar maiúsculas de minúsculas, Listar as janelas de nível superior visíveis

WindowGetHeight​

WindowGetHeight(window: Window) → Integer

Retorna a altura visível de uma janela, sem a borda invisível de redimensionamento que o Windows adiciona em volta da maioria das janelas.

Parâmetros

  • window: Window — A janela a medir.

Retorna

A altura em pixels, ou 0 se a janela for nula ou estiver fechada.

3 exemplos: Formatar mais de dois valores, Encaixar a janela ativa na metade esquerda do seu monitor, Confinar o cursor a uma janela por 5 segundos

WindowGetLastFocus​

WindowGetLastFocus() → Window

Retorna a janela ou o controle que recebeu o foco do teclado mais recentemente em qualquer lugar da Área de Trabalho. Muitas vezes é um controle, como uma caixa de texto, e não a janela de nível superior dele.

Parâmetros

Sem parâmetros.

Retorna

A última janela ou o último controle com foco, ou uma janela nula se o foco não mudou desde que o mecanismo foi iniciado.

WindowGetMovableAncestor​

WindowGetMovableAncestor(window: Window) → Window

Retorna a janela mais próxima que pode ser arrastada: a própria janela ou o primeiro pai acima dela que tenha um menu de sistema. Transforma um controle sob o mouse na janela a mover.

Parâmetros

  • window: Window — A janela ou o controle de onde começar.

Retorna

A própria janela ou o primeiro pai com menu de sistema, ou uma janela nula se nenhum tiver um ou se a janela for nula.

WindowGetParent​

WindowGetParent(window: Window) → Window

Retorna a janela que contém um controle. Para uma janela pop-up, como uma caixa de diálogo, pode ser a janela proprietária dela.

Parâmetros

  • window: Window — A janela ou o controle cujo pai obter.

Retorna

A janela pai ou proprietária, ou uma janela nula se não houver nenhuma ou se a janela for nula ou estiver fechada.

WindowGetProcessId​

WindowGetProcessId(window: Window) → Integer

Retorna o ID do processo (o programa em execução) dono de uma janela, o mesmo número que o Gerenciador de Tarefas mostra.

Parâmetros

  • window: Window — A janela cujo processo identificar.

Retorna

O ID do processo, ou 0 se a janela for nula ou estiver fechada.

WindowGetPropertyInteger​

WindowGetPropertyInteger(window: Window, name: Text) → Integer

Lê um inteiro nomeado armazenado em uma janela, por exemplo um armazenado antes com WindowSetPropertyInteger para lembrar algo sobre essa janela.

Parâmetros

  • window: Window — A janela da qual ler.
  • name: Text — O nome da propriedade.

Retorna

O valor armazenado, ou 0 se a propriedade não existir ou se a janela for nula. Um 0 armazenado parece igual a uma propriedade ausente.

2 exemplos: Fixar uma janela por cima, Lembrar e restaurar a posição de uma janela

WindowGetPropertyText​

WindowGetPropertyText(window: Window, name: Text) → Text

Lê um valor de texto nomeado que este mecanismo armazenou em uma janela com WindowSetPropertyText.

Parâmetros

  • window: Window — A janela da qual ler.
  • name: Text — O nome da propriedade.

Retorna

O texto armazenado, ou texto vazio se a propriedade não existir, não tiver sido armazenada como texto por este mecanismo, tiver sido sobrescrita desde então ou se a janela for nula.

WindowGetRoot​

WindowGetRoot(window: Window) → Window

Retorna a janela de nível superior que contém uma janela ou um controle, como a janela do programa em volta de um botão.

Parâmetros

  • window: Window — A janela ou o controle de onde começar.

Retorna

A janela de nível superior, que é a própria janela se ela já for de nível superior; uma janela nula se a janela for nula ou estiver fechada.

1 exemplo: Descrever o que está sob o cursor

WindowGetTitle​

WindowGetTitle(window: Window) → Text

Retorna o texto da barra de título de uma janela. Para controles de outros programas, normalmente fica vazio; use WindowGetControlText para eles.

Parâmetros

  • window: Window — A janela a ler.

Retorna

O título, ou texto vazio se a janela não tiver título, for nula ou estiver fechada.

9 exemplos: Comparações sem diferenciar maiúsculas de minúsculas, Um gesto, várias opções, Fixar uma janela por cima, Listar as janelas de nível superior visíveis, Inspecionar os controles filhos de uma janela, Do processo à janela, Descrever o que está sob o cursor, Tudo o que o contexto do gatilho sabe, Uma lista guardada no Storage

WindowGetVisible​

WindowGetVisible(window: Window) → Bool

Verifica se uma janela está configurada para ser mostrada. Uma janela visível ainda pode estar minimizada, coberta por outras janelas, fora da tela ou em outra área de trabalho virtual.

Parâmetros

  • window: Window — A janela a verificar.

Retorna

true se a janela e todos os pais dela estiverem sendo mostrados; false se ela estiver oculta, for nula ou estiver fechada.

1 exemplo: Listar as janelas de nível superior visíveis

WindowGetWidth​

WindowGetWidth(window: Window) → Integer

Retorna a largura visível de uma janela, sem a borda invisível de redimensionamento que o Windows adiciona em volta da maioria das janelas.

Parâmetros

  • window: Window — A janela a medir.

Retorna

A largura em pixels, ou 0 se a janela for nula ou estiver fechada.

3 exemplos: Formatar mais de dois valores, Encaixar a janela ativa na metade esquerda do seu monitor, Confinar o cursor a uma janela por 5 segundos

WindowGetX​

WindowGetX(window: Window) → Integer

Retorna a posição na tela da borda esquerda visível de uma janela, sem a borda invisível de redimensionamento. Para uma janela minimizada, é uma posição de estacionamento fora da tela.

Parâmetros

  • window: Window — A janela a localizar.

Retorna

A borda esquerda, em pixels da tela virtual, ou 0 se a janela for nula ou estiver fechada.

4 exemplos: Formatar mais de dois valores, Encaixar a janela ativa na metade esquerda do seu monitor, Lembrar e restaurar a posição de uma janela, Confinar o cursor a uma janela por 5 segundos

WindowGetY​

WindowGetY(window: Window) → Integer

Retorna a posição na tela da borda superior visível de uma janela, sem a borda invisível de redimensionamento. Para uma janela minimizada, é uma posição de estacionamento fora da tela.

Parâmetros

  • window: Window — A janela a localizar.

Retorna

A borda superior, em pixels da tela virtual, ou 0 se a janela for nula ou estiver fechada.

4 exemplos: Formatar mais de dois valores, Encaixar a janela ativa na metade esquerda do seu monitor, Lembrar e restaurar a posição de uma janela, Confinar o cursor a uma janela por 5 segundos

WindowHide​

WindowHide(window: Window) → Bool

Oculta uma janela completamente, inclusive o botão dela na barra de tarefas. O mecanismo volta a mostrá-la quando sai, e Mostrar janelas ocultas no menu da bandeja a traz de volta a qualquer momento.

Parâmetros

  • window: Window — A janela a ocultar.

Retorna

true se a janela foi ocultada ou já estava oculta; false se ela for nula ou estiver fechada, se for a Área de Trabalho, a barra de tarefas ou uma das janelas do próprio mecanismo, ou se já houver 256 janelas ocultas sendo acompanhadas.

WindowIsCloaked​

WindowIsCloaked(window: Window) → Bool

Verifica se o Windows mantém uma janela fora de vista mesmo que ela conte como mostrada, por exemplo uma janela em outra área de trabalho virtual ou um aplicativo da Store suspenso. Útil para ignorar essas janelas em uma lista.

Parâmetros

  • window: Window — A janela a verificar.

Retorna

true se a janela estiver camuflada; false se não estiver, ou se a janela for nula ou estiver fechada.

1 exemplo: Listar as janelas de nível superior visíveis

WindowIsMaximized​

WindowIsMaximized(window: Window) → Bool

Verifica se uma janela está maximizada, por exemplo antes de decidir se chama WindowRestore ou WindowMaximize.

Parâmetros

  • window: Window — A janela a verificar.

Retorna

true se a janela estiver maximizada; false se não estiver, ou se a janela for nula ou estiver fechada.

1 exemplo: Alternar a maximização da janela do gesto

WindowIsMinimized​

WindowIsMinimized(window: Window) → Bool

Verifica se uma janela está minimizada na barra de tarefas, por exemplo antes de decidir se chama WindowRestore.

Parâmetros

  • window: Window — A janela a verificar.

Retorna

true se a janela estiver minimizada; false se não estiver, ou se a janela for nula ou estiver fechada.

WindowMapClientPointToScreenX​

WindowMapClientPointToScreenX(window: Window, x: Integer, y: Integer) → Integer

Converte um ponto na área cliente de uma janela (o interior da janela, abaixo da barra de título e dentro das bordas) em uma posição na tela e retorna a parte horizontal dela.

Parâmetros

  • window: Window — A janela em cuja área cliente o ponto está.
  • x: Integer — Posição horizontal a partir da borda esquerda da área cliente, em pixels.
  • y: Integer — Posição vertical a partir da borda superior da área cliente, em pixels.

Retorna

A posição X na tela, em pixels da tela virtual, ou 0 se a janela for nula ou estiver fechada.

WindowMapClientPointToScreenY​

WindowMapClientPointToScreenY(window: Window, x: Integer, y: Integer) → Integer

Converte um ponto na área cliente de uma janela (o interior da janela, abaixo da barra de título e dentro das bordas) em uma posição na tela e retorna a parte vertical dela.

Parâmetros

  • window: Window — A janela em cuja área cliente o ponto está.
  • x: Integer — Posição horizontal a partir da borda esquerda da área cliente, em pixels.
  • y: Integer — Posição vertical a partir da borda superior da área cliente, em pixels.

Retorna

A posição Y na tela, em pixels da tela virtual, ou 0 se a janela for nula ou estiver fechada.

WindowMapScreenPointToClientX​

WindowMapScreenPointToClientX(window: Window, x: Integer, y: Integer) → Integer

Converte uma posição na tela em um ponto relativo à área cliente de uma janela (o interior da janela, abaixo da barra de título e dentro das bordas) e retorna a parte horizontal dele.

Parâmetros

  • window: Window — A janela a partir de cuja área cliente medir.
  • x: Integer — Posição horizontal na tela, em pixels da tela virtual.
  • y: Integer — Posição vertical na tela, em pixels da tela virtual.

Retorna

A posição X a partir da borda esquerda da área cliente, em pixels; negativa se o ponto estiver à esquerda dela. 0 se a janela for nula ou estiver fechada.

1 exemplo: Descrever o que está sob o cursor

WindowMapScreenPointToClientY​

WindowMapScreenPointToClientY(window: Window, x: Integer, y: Integer) → Integer

Converte uma posição na tela em um ponto relativo à área cliente de uma janela (o interior da janela, abaixo da barra de título e dentro das bordas) e retorna a parte vertical dele.

Parâmetros

  • window: Window — A janela a partir de cuja área cliente medir.
  • x: Integer — Posição horizontal na tela, em pixels da tela virtual.
  • y: Integer — Posição vertical na tela, em pixels da tela virtual.

Retorna

A posição Y a partir da borda superior da área cliente, em pixels; negativa se o ponto estiver acima dela. 0 se a janela for nula ou estiver fechada.

1 exemplo: Descrever o que está sob o cursor

WindowMaximize​

WindowMaximize(window: Window) → Bool · Simples

Maximiza uma janela para que ela preencha o monitor em que está e a ativa. Uma janela ocultada com WindowHide é mostrada e deixa de ser acompanhada como oculta.

Parâmetros

  • window: Window — A janela a maximizar.

Retorna

true se a janela estiver maximizada depois; false se a janela for nula ou estiver fechada, ou se não foi maximizada.

2 exemplos: Um gesto, várias opções, Alternar a maximização da janela do gesto

WindowMinimize​

WindowMinimize(window: Window) → Bool · Simples

Minimiza uma janela na barra de tarefas. O Windows então ativa a próxima janela. Uma janela ocultada com WindowHide é mostrada minimizada e deixa de ser acompanhada como oculta.

Parâmetros

  • window: Window — A janela a minimizar.

Retorna

true se a janela estiver minimizada depois; false se a janela for nula ou estiver fechada, ou se não foi minimizada.

4 exemplos: Um gesto, várias opções, Minimizar todas as janelas de um aplicativo, Ramificar conforme o botão do traço, Mudar o comportamento enquanto Ctrl está pressionada

WindowMoveTo​

WindowMoveTo(window: Window, x: Integer, y: Integer) → Bool

Move uma janela para que o canto superior esquerdo visível dela fique em uma posição da tela, mantendo o tamanho. Usa as mesmas coordenadas que WindowGetX e WindowGetY; uma janela maximizada não é restaurada antes.

Parâmetros

  • window: Window — A janela a mover.
  • x: Integer — Nova borda esquerda do quadro visível, em pixels da tela virtual.
  • y: Integer — Nova borda superior do quadro visível, em pixels da tela virtual.

Retorna

true se a janela foi movida; false se a janela for nula ou estiver fechada, ou se ela se recusou a se mover.

3 exemplos: Encaixar a janela ativa na metade esquerda do seu monitor, Encaixar uma janela na célula de uma grade 3×2 sob o cursor, Lembrar e restaurar a posição de uma janela

WindowRemoveProp​

WindowRemoveProp(window: Window, name: Text) → Integer

Remove uma propriedade nomeada de uma janela, tenha ela sido armazenada com WindowSetPropertyInteger, WindowSetPropertyText ou por outro software.

Parâmetros

  • window: Window — A janela da qual remover a propriedade.
  • name: Text — O nome da propriedade.

Retorna

O valor bruto da propriedade removida, ou 0 se ela não existia ou se a janela for nula. Para uma propriedade de texto, é um número interno, não o texto.

2 exemplos: Fixar uma janela por cima, Lembrar e restaurar a posição de uma janela

WindowResizeTo​

WindowResizeTo(window: Window, width: Integer, height: Integer) → Bool

Redimensiona o quadro visível de uma janela, mantendo o canto superior esquerdo no lugar. Usa o mesmo tamanho que WindowGetWidth e WindowGetHeight; uma janela maximizada não é restaurada antes.

Parâmetros

  • window: Window — A janela a redimensionar.
  • width: Integer — Nova largura visível, em pixels.
  • height: Integer — Nova altura visível, em pixels.

Retorna

true se a janela foi redimensionada; false se a janela for nula ou estiver fechada, ou se ela recusou a alteração.

2 exemplos: Encaixar a janela ativa na metade esquerda do seu monitor, Encaixar uma janela na célula de uma grade 3×2 sob o cursor

WindowRestore​

WindowRestore(window: Window) → Bool · Simples

Devolve uma janela minimizada ou maximizada ao tamanho e à posição normais e a ativa. Uma janela ocultada com WindowHide é mostrada e deixa de ser acompanhada como oculta.

Parâmetros

  • window: Window — A janela a restaurar.

Retorna

true se a janela terminar no tamanho normal, nem minimizada nem maximizada; false se a janela for nula ou estiver fechada, ou se não chegou a esse estado. Uma janela minimizada que estava maximizada antes volta a ficar maximizada, o que conta como false.

3 exemplos: Alternar a maximização da janela do gesto, Encaixar a janela ativa na metade esquerda do seu monitor, Encaixar uma janela na célula de uma grade 3×2 sob o cursor

WindowSendToBottom​

WindowSendToBottom(window: Window) → Bool · Simples

Move uma janela para trás de todas as outras janelas sem ativá-la. Uma janela que estava sempre visível perde essa configuração.

Parâmetros

  • window: Window — A janela a enviar para trás.

Retorna

true se a janela foi movida para trás; false se a janela for nula ou estiver fechada, ou se ela recusou a alteração.

WindowSendToMonitorAt​

WindowSendToMonitorAt(window: Window, x: Integer, y: Integer, mouseFollows: Bool) → Bool

Move uma janela para o monitor que contém um ponto da tela, mantendo o tamanho e a posição relativa à área de trabalho. Uma janela maximizada termina maximizada no novo monitor; se isso a ativar, a janela que estava ativa antes recebe o foco de volta quando o Windows permite.

Parâmetros

  • window: Window — A janela a mover.
  • x: Integer — Posição horizontal de qualquer ponto no monitor de destino, em pixels da tela virtual. Um ponto fora de todos os monitores escolhe o monitor mais próximo.
  • y: Integer — Posição vertical de qualquer ponto no monitor de destino, em pixels da tela virtual.
  • mouseFollows: Bool — true para mover o ponteiro do mouse para o mesmo ponto relativo no novo monitor quando a janela se move; false para deixá-lo onde está.

Retorna

true se a janela foi movida; false se a janela for nula ou estiver fechada, ou se ela se recusou a se mover.

WindowSendToMonitorIndex​

WindowSendToMonitorIndex(window: Window, index: Integer, mouseFollows: Bool) → Bool

Move uma janela para um monitor escolhido pela posição na lista da chamada mais recente a DisplayMonitorEnumeratedAll, mantendo o tamanho e a posição relativa. Uma janela maximizada continua maximizada; se maximizá-la novamente a ativar, a janela que estava ativa antes recebe o foco de volta quando o Windows permite.

Parâmetros

  • window: Window — A janela a mover.
  • index: Integer — Posição na lista de monitores, começando em 0. Os monitores são ordenados da esquerda para a direita e depois de cima para baixo.
  • mouseFollows: Bool — true para mover o ponteiro do mouse para o mesmo ponto relativo no novo monitor quando a janela se move; false para deixá-lo onde está.

Retorna

true se a janela foi movida; false se a janela for nula ou estiver fechada, se index estiver fora do intervalo ou DisplayMonitorEnumeratedAll não tiver sido executada neste script, ou se a janela se recusou a se mover.

1 exemplo: Enviar uma janela para um monitor específico

WindowSendToMonitorName​

WindowSendToMonitorName(window: Window, name: Text, mouseFollows: Bool) → Bool

Move uma janela para o monitor com determinado caminho de dispositivo ou nome amigável, mantendo o tamanho e a posição relativa. Uma janela maximizada continua maximizada; se maximizá-la novamente a ativar, a janela que estava ativa antes recebe o foco de volta quando o Windows permite. Útil para layouts que sobrevivem a conectar e desconectar uma dock.

Parâmetros

  • window: Window — A janela a mover.
  • name: Text — O caminho de dispositivo ou o nome amigável do monitor, conforme retornado por DisplayMonitorGetDevicePathFromPoint ou DisplayMonitorGetFriendlyNameFromPoint. O caminho de dispositivo é a opção confiável. Maiúsculas e minúsculas são ignoradas.
  • mouseFollows: Bool — true para mover o ponteiro do mouse para o mesmo ponto relativo no novo monitor quando a janela se move; false para deixá-lo onde está.

Retorna

true se a janela foi movida; false se nenhum monitor conectado tiver esse nome, se a janela for nula ou estiver fechada, ou se a janela se recusou a se mover.

WindowSendToNextScreen​

WindowSendToNextScreen(window: Window, mouseFollows: Bool) → Bool · Simples

Move uma janela para o próximo monitor, da esquerda para a direita e depois de cima para baixo, voltando do último para o primeiro, mantendo o tamanho e a posição relativa. Uma janela maximizada continua maximizada; se maximizá-la novamente a ativar, a janela que estava ativa antes recebe o foco de volta quando o Windows permite.

Parâmetros

  • window: Window — A janela a mover.
  • mouseFollows: Bool — true para mover o ponteiro do mouse para o mesmo ponto relativo no novo monitor quando a janela se move; false para deixá-lo onde está.

Retorna

true se a janela foi movida, inclusive quando há só um monitor; false se a janela for nula ou estiver fechada, ou se ela se recusou a se mover.

2 exemplos: Jogar uma janela para o próximo monitor, Enviar uma janela para um monitor específico

WindowSendToPreviousScreen​

WindowSendToPreviousScreen(window: Window, mouseFollows: Bool) → Bool · Simples

Move uma janela para o monitor anterior, da direita para a esquerda e depois de baixo para cima, voltando do primeiro para o último, mantendo o tamanho e a posição relativa. Uma janela maximizada continua maximizada; se maximizá-la novamente a ativar, a janela que estava ativa antes recebe o foco de volta quando o Windows permite.

Parâmetros

  • window: Window — A janela a mover.
  • mouseFollows: Bool — true para mover o ponteiro do mouse para o mesmo ponto relativo no novo monitor quando a janela se move; false para deixá-lo onde está.

Retorna

true se a janela foi movida, inclusive quando há só um monitor; false se a janela for nula ou estiver fechada, ou se ela se recusou a se mover.

WindowSetActive​

WindowSetActive(window: Window) → Bool

Traz uma janela para a frente e dá a ela o foco do teclado, restaurando-a antes se estiver minimizada e mostrando-a se estiver oculta. Uma janela ocultada com WindowHide deixa de ser acompanhada como oculta. O Windows pode recusar e, em vez disso, piscar o botão dela na barra de tarefas.

Parâmetros

  • window: Window — A janela a ativar.

Retorna

true se a janela se tornou a janela em primeiro plano; false se o Windows recusou, ou se a janela for nula ou estiver fechada.

2 exemplos: Iniciar um programa, aguardar a janela dele e agir sobre ela, Clicar em um ponto dentro de uma janela

WindowSetAlpha​

WindowSetAlpha(window: Window, alpha: Integer) → Bool

Define o quanto uma janela é transparente, de totalmente transparente a totalmente opaca. Em 255, a janela deixa de ser uma janela em camadas, o que também remove qualquer transparência que o próprio programa tenha definido. As janelas de programas executados como administrador não podem ser alteradas, a menos que o mecanismo também seja.

Parâmetros

  • window: Window — A janela a alterar.
  • alpha: Integer — Opacidade de 0 (totalmente transparente) a 255 (totalmente opaca). Valores fora desse intervalo são limitados a ele.

Retorna

true se a transparência foi aplicada; false se a janela for nula ou estiver fechada, ou se a alteração foi recusada.

1 exemplo: Alternar a transparência da janela em ciclo

WindowSetBounds​

WindowSetBounds(window: Window, x: Integer, y: Integer, width: Integer, height: Integer) → Bool

Move e redimensiona uma janela em uma única etapa, usando as mesmas coordenadas de quadro visível que WindowGetX, WindowGetY, WindowGetWidth e WindowGetHeight. Evita a cintilação de WindowMoveTo seguida de WindowResizeTo.

Parâmetros

  • window: Window — A janela a mover e redimensionar.
  • x: Integer — Nova borda esquerda do quadro visível, em pixels da tela virtual.
  • y: Integer — Nova borda superior do quadro visível, em pixels da tela virtual.
  • width: Integer — Nova largura visível, em pixels.
  • height: Integer — Nova altura visível, em pixels.

Retorna

true se a alteração foi aplicada; false se a janela for nula ou estiver fechada, ou se ela recusou a alteração.

WindowSetEnabled​

WindowSetEnabled(window: Window, enabled: Bool) → Bool

Habilita ou desabilita uma janela ou um controle. Uma janela desabilitada ignora cliques do mouse e pressionamentos de tecla até ser habilitada novamente.

Parâmetros

  • window: Window — A janela ou o controle a alterar.
  • enabled: Bool — true para habilitar a janela; false para desabilitá-la.

Retorna

true assim que a solicitação é feita; false se a janela for nula ou estiver fechada.

WindowSetPropertyInteger​

WindowSetPropertyInteger(window: Window, name: Text, value: Integer) → Bool

Armazena um inteiro nomeado em uma janela, por exemplo para lembrar algo sobre essa janela entre ações. O mecanismo remove as propriedades que armazenou quando sai.

Parâmetros

  • window: Window — A janela na qual armazenar o valor.
  • name: Text — O nome da propriedade. Escolha um nome característico para que não entre em conflito com propriedades que o próprio programa usa.
  • value: Integer — O inteiro a armazenar.

Retorna

true se o valor foi armazenado; false se a janela for nula ou estiver fechada.

2 exemplos: Fixar uma janela por cima, Lembrar e restaurar a posição de uma janela

WindowSetPropertyText​

WindowSetPropertyText(window: Window, name: Text, value: Text) → Bool

Armazena um valor de texto nomeado em uma janela, lido de volta com WindowGetPropertyText. O mecanismo mantém o texto exatamente como foi passado, inclusive maiúsculas e minúsculas, e ele pode estar vazio. O mecanismo remove as propriedades que armazenou quando sai.

Parâmetros

  • window: Window — A janela na qual armazenar o texto.
  • name: Text — O nome da propriedade. Escolha um nome característico para que não entre em conflito com propriedades que o próprio programa usa.
  • value: Text — O texto a armazenar, com no máximo 1.024 caracteres.

Retorna

true se o texto foi armazenado; false se a janela for nula ou estiver fechada, se 512 valores de texto já estiverem armazenados ou se a propriedade não pôde ser definida. Um texto com mais de 1.024 caracteres interrompe a ação com um erro.

WindowSetTitle​

WindowSetTitle(window: Window, title: Text) → Bool

Altera o texto da barra de título de uma janela. O programa pode alterá-lo de volta a qualquer momento. Um programa que não responde em 1 segundo fica inalterado.

Parâmetros

  • window: Window — A janela a renomear.
  • title: Text — O texto do novo título.

Retorna

true se o título foi definido; false se a janela for nula ou estiver fechada, se não respondeu em 1 segundo ou se o programa recusou.

1 exemplo: Um gesto, várias opções

WindowSetTopmost​

WindowSetTopmost(window: Window, topmost: Bool) → Bool · Simples

Mantém uma janela acima de todas as janelas normais, ou a devolve à ordem de empilhamento normal, sem ativá-la.

Parâmetros

  • window: Window — A janela a alterar.
  • topmost: Bool — true para manter a janela sempre visível; false para devolvê-la à ordem de empilhamento normal.

Retorna

true se a alteração foi aplicada; false se a janela for nula ou estiver fechada, ou se pertencer a um programa executado com privilégios mais altos.

1 exemplo: Fixar uma janela por cima

WindowShow​

WindowShow(window: Window) → Bool

Mostra novamente uma janela oculta, como uma ocultada com WindowHide, no tamanho e na posição atuais. O mecanismo deixa de acompanhá-la como oculta.

Parâmetros

  • window: Window — A janela a mostrar.

Retorna

true se a solicitação para mostrar foi feita; false se a janela for nula ou estiver fechada.

WindowToggleTopmost​

WindowToggleTopmost(window: Window) → Bool · Simples

Alterna uma janela entre sempre visível e a ordem de empilhamento normal, sem ativá-la.

Parâmetros

  • window: Window — A janela a alterar.

Retorna

true se a alteração foi aplicada; false se a janela for nula ou estiver fechada, ou se ela recusou a alteração. Não informa em qual estado a janela está agora.

WindowWaitClose​

WindowWaitClose(window: Window, timeoutMs: Integer) → Bool

Aguarda até que uma janela seja fechada, verificando a cada 50 milissegundos. Bloqueia o script por até timeoutMs; parar todas as ações encerra a espera antes.

Parâmetros

  • window: Window — A janela a aguardar.
  • timeoutMs: Integer — Tempo máximo de espera, em milissegundos, de 0 a 60000. Valores maiores contam como 60000; 0 verifica uma vez sem aguardar.

Retorna

true assim que a janela estiver fechada, imediatamente se ela já estiver fechada ou for nula; false se ainda estiver aberta quando o tempo acabar ou se a espera for interrompida.

1 exemplo: Iniciar um programa, aguardar a janela dele e agir sobre ela

WindowWaitFor​

WindowWaitFor(pattern: Text, timeoutMs: Integer) → Window

Aguarda até que apareça uma janela de nível superior visível cujo título corresponda a uma expressão regular, verificando a cada 50 milissegundos. Bloqueia o script por até timeoutMs; útil logo depois de iniciar um programa.

Parâmetros

  • pattern: Text — Uma expressão regular comparada com os títulos das janelas, sem diferenciar maiúsculas de minúsculas, como 'Notepad$'. Ela corresponde em qualquer posição do título, a menos que seja ancorada com ^ ou $.
  • timeoutMs: Integer — Tempo máximo de espera, em milissegundos, de 0 a 60000. Valores maiores contam como 60000; 0 verifica uma vez sem aguardar.

Retorna

A janela correspondente mais à frente, ou uma janela nula se nenhuma apareceu a tempo ou se a espera foi interrompida. Um padrão inválido interrompe a ação com um erro.

1 exemplo: Iniciar um programa, aguardar a janela dele e agir sobre ela