# API de scripts Lua do pxstud.io — Diálogos e comandos > Parte da referência de scripts Lua do pxstud.io, cuja visão geral (https://pxstud.io/pt-br/docs/scripting.md) explica as convenções. Os grupos de opções e os tipos a que ela remete estão em https://pxstud.io/pt-br/docs/scripting/option-groups.md e https://pxstud.io/pt-br/docs/scripting/types.md. Tudo em um único arquivo (em inglês): https://pxstud.io/llms-full.txt. O índice de todo o site (em inglês): https://pxstud.io/llms.txt. ### Diálogos e comandos Interface de script, nos moldes do Aseprite: Dialog{ title = ... } monta uma janela a partir de widgets (label, entry, number, slider, check, radio, combobox, color, shades, button, separator, file) e plugin:newCommand adiciona comandos aos menus, à paleta de comandos e ao editor de Atalhos de teclado. A janela é desenhada pelo editor, somente com texto, com uma barra de título que nomeia o script e a marca como "script". Os callbacks (onclick, onchange, onclose) rodam no script, um de cada vez, cada um como um único passo de desfazer; um script com um diálogo aberto continua vivo, ocioso, enquanto o usuário segue desenhando, e interrompê-lo fecha os diálogos dele. Não há suporte para widgets de canvas nem para dlg:repaint. #### `Dialog(opts)` — pura Cria um diálogo: uma janela que o script desenha no editor, montada com os métodos dlg: e aberta com dlg:show. A janela sempre nomeia o script e é marcada como "script" para que não possa se passar por parte do editor, e tudo o que um script coloca nela é texto simples. Adicione widgets com os métodos dlg: (eles se encadeiam) e depois use dlg:show{ wait = false } para uma janela que fica aberta enquanto o usuário segue desenhando, ou dlg:show{ wait = true } (o padrão) para parar o script até que ela seja fechada. Um script com um diálogo aberto continua vivo, ocioso; interromper o script o fecha. Os callbacks (onclick, onchange, onclose) rodam no script; cada um é um único passo de desfazer. No máximo 4 diálogos podem estar abertos e 10 abertos a cada 10 segundos; no máximo 100 widgets cada. - `opts` (table) — Uma string de título ou uma tabela. Dialog("Title") é Dialog{ title = "Title" }. - `title` (string) — Exibido no topo do diálogo (máx. 80 caracteres). Somente texto. - `onclose` (function(ev)) — Chamado, no script, quando o usuário fecha o diálogo. Retorna (table): O diálogo. dlg.data é uma tabela com os valores atuais dos widgets que têm id. #### `dlg:button(opts?)` — pura Adiciona um botão. Sem um onclick, pressioná-lo fecha o diálogo e define dlg.data. como true (assim, depois de dlg:show{ wait = true }, você sabe qual botão o fechou). - `opts` (table, opcional) - `id` (string) — Dá nome ao widget: o valor dele é lido como dlg.data. e ele é o alvo de dlg:modify. Letras, dígitos e _ , começando com uma letra; único no diálogo. - `label` (string) — Texto exibido à esquerda do widget; um widget com label começa a própria linha. - `visible` (boolean; padrão true) — Exibe o widget. - `enabled` (boolean; padrão true) — Deixa o usuário alterá-lo. - `text` (string) — O texto do botão. - `focus` (boolean; padrão false) — Começa com o foco do teclado aqui. - `onclick` (function(ev)) — Chamado, no script, quando o usuário o pressiona, com ev = { id }. Tudo o que ele altera no documento é um único passo de desfazer. Retorna (table): O diálogo, para encadeamento. #### `dlg:check(opts?)` — pura Adiciona uma caixa de seleção. O valor dela é dlg.data. (um booleano). - `opts` (table, opcional) - `id` (string) — Dá nome ao widget: o valor dele é lido como dlg.data. e ele é o alvo de dlg:modify. Letras, dígitos e _ , começando com uma letra; único no diálogo. - `label` (string) — Texto exibido à esquerda do widget; um widget com label começa a própria linha. - `visible` (boolean; padrão true) — Exibe o widget. - `enabled` (boolean; padrão true) — Deixa o usuário alterá-lo. - `text` (string) — O texto ao lado da caixa. - `selected` (boolean; padrão false) — Começa marcada. - `onchange` (function(ev)) — Chamado, no script, cada vez que o usuário altera o valor, com ev = { id, value }. Uma rajada de alterações (arrastar um slider) pode chegar como apenas a última. Tudo o que ele altera no documento é um único passo de desfazer. Retorna (table): O diálogo, para encadeamento. #### `dlg:close()` — pura Fecha o diálogo (a partir do script, p. ex. no onclick de um botão). Um script termina quando o chunk principal acaba e nenhum diálogo está aberto. Retorna (table): O diálogo, para encadeamento. #### `dlg:color(opts?)` — pura Adiciona um campo de cor que abre o seletor de cores completo, com a paleta do sprite e as cores recentes. O valor dele é dlg.data. (uma string "#rrggbb" ou "#rrggbbaa"). - `opts` (table, opcional) - `id` (string) — Dá nome ao widget: o valor dele é lido como dlg.data. e ele é o alvo de dlg:modify. Letras, dígitos e _ , começando com uma letra; único no diálogo. - `label` (string) — Texto exibido à esquerda do widget; um widget com label começa a própria linha. - `visible` (boolean; padrão true) — Exibe o widget. - `enabled` (boolean; padrão true) — Deixa o usuário alterá-lo. - `color` (color ("#rgb", "#rrggbb[aa]" or { r, g, b, a }); padrão "#000000") — A cor inicial. - `onchange` (function(ev)) — Chamado, no script, cada vez que o usuário altera o valor, com ev = { id, value }. Uma rajada de alterações (arrastar um slider) pode chegar como apenas a última. Tudo o que ele altera no documento é um único passo de desfazer. Retorna (table): O diálogo, para encadeamento. #### `dlg:combobox(opts?)` — pura Adiciona uma lista suspensa. O valor dela é dlg.data. (o texto da opção escolhida). - `opts` (table, opcional) - `id` (string) — Dá nome ao widget: o valor dele é lido como dlg.data. e ele é o alvo de dlg:modify. Letras, dígitos e _ , começando com uma letra; único no diálogo. - `label` (string) — Texto exibido à esquerda do widget; um widget com label começa a própria linha. - `visible` (boolean; padrão true) — Exibe o widget. - `enabled` (boolean; padrão true) — Deixa o usuário alterá-lo. - `options` (a list of strings (max 200)) — As opções. - `option` (string; padrão the first option) — A opção inicial. - `onchange` (function(ev)) — Chamado, no script, cada vez que o usuário altera o valor, com ev = { id, value }. Uma rajada de alterações (arrastar um slider) pode chegar como apenas a última. Tudo o que ele altera no documento é um único passo de desfazer. Retorna (table): O diálogo, para encadeamento. #### `dlg:entry(opts?)` — pura Adiciona uma caixa de texto. O valor dela é dlg.data. (uma string). - `opts` (table, opcional) - `id` (string) — Dá nome ao widget: o valor dele é lido como dlg.data. e ele é o alvo de dlg:modify. Letras, dígitos e _ , começando com uma letra; único no diálogo. - `label` (string) — Texto exibido à esquerda do widget; um widget com label começa a própria linha. - `visible` (boolean; padrão true) — Exibe o widget. - `enabled` (boolean; padrão true) — Deixa o usuário alterá-lo. - `text` (string; padrão "") — O texto inicial. - `focus` (boolean; padrão false) — Começa com o foco do teclado aqui. - `onchange` (function(ev)) — Chamado, no script, cada vez que o usuário altera o valor, com ev = { id, value }. Uma rajada de alterações (arrastar um slider) pode chegar como apenas a última. Tudo o que ele altera no documento é um único passo de desfazer. Retorna (table): O diálogo, para encadeamento. #### `dlg:file(opts?)` — pura Adiciona um seletor de arquivo (somente abrir: o seletor de arquivos do navegador). dlg.data. é o nome do arquivo escolhido; o conteúdo do arquivo é acessado por ev.file no onchange (e por dlg.files.): { name, size, type, text }, em que text só é definido para arquivos de texto pequenos (até 256 KiB). Imagens e outros arquivos binários não podem ser lidos. - `opts` (table, opcional) - `id` (string) — Dá nome ao widget: o valor dele é lido como dlg.data. e ele é o alvo de dlg:modify. Letras, dígitos e _ , começando com uma letra; único no diálogo. - `label` (string) — Texto exibido à esquerda do widget; um widget com label começa a própria linha. - `visible` (boolean; padrão true) — Exibe o widget. - `enabled` (boolean; padrão true) — Deixa o usuário alterá-lo. - `filename` (string) — Um nome a exibir antes de um arquivo ser escolhido. - `title` (string; padrão "Choose file...") — O texto do botão do seletor. - `filetypes` (a list of extensions without the dot, e.g. { "png", "gpl" }) — Os arquivos que o seletor oferece. - `onchange` (function(ev)) — Chamado, no script, cada vez que o usuário altera o valor, com ev = { id, value }. Uma rajada de alterações (arrastar um slider) pode chegar como apenas a última. Tudo o que ele altera no documento é um único passo de desfazer. Retorna (table): O diálogo, para encadeamento. #### `dlg:label(opts?)` — pura Adiciona uma linha de texto (várias com \n, até 20 linhas). - `opts` (table, opcional) - `id` (string) — Dá nome ao widget: o valor dele é lido como dlg.data. e ele é o alvo de dlg:modify. Letras, dígitos e _ , começando com uma letra; único no diálogo. - `label` (string) — Texto exibido à esquerda do widget; um widget com label começa a própria linha. - `visible` (boolean; padrão true) — Exibe o widget. - `enabled` (boolean; padrão true) — Deixa o usuário alterá-lo. - `text` (string) — O texto. Retorna (table): O diálogo, para encadeamento. #### `dlg:modify(opts?)` — pura Altera um widget (ou o título do diálogo) enquanto o diálogo está aberto ou antes de ele ser exibido. Os valores são verificados e limitados, e dlg.data acompanha. Atribuir dlg.data = { id = value, ... } faz o mesmo para vários valores. - `opts` (table, opcional) - `id` (string) — O widget a alterar. Sem ele, o próprio diálogo (somente title). - `title` (string) — O título do diálogo (sem id) ou o texto do botão de um widget file. - `text` (string) — Um novo texto (o valor de um entry ou number; o texto de um label, check, radio ou button). - `value` (a number, string or boolean to match the widget) — Um novo valor de qualquer widget de valor (o número de um slider, ...). - `selected` (boolean) — Um novo estado para um check ou radio. - `option` (string) — Uma nova escolha para um combobox. - `options` (a list of strings) — Novas opções para um combobox. - `color` (color ("#rgb", "#rrggbb[aa]" or { r, g, b, a })) — Uma nova cor para um widget color. - `colors` (a list of colors) — Novas amostras para shades. - `min` (number) — Um novo menor valor (number, slider). - `max` (number) — Um novo maior valor (number, slider). - `label` (string) — Um novo label. - `visible` (boolean) — Exibe ou oculta o widget. - `enabled` (boolean) — Ativa ou desativa o widget. Retorna (table): O diálogo, para encadeamento. #### `dlg:newrow()` — pura Começa uma nova linha: os widgets adicionados em seguida ficam abaixo, em vez de ao lado do anterior. Retorna (table): O diálogo, para encadeamento. #### `dlg:number(opts?)` — pura Adiciona uma caixa numérica. O valor dela é dlg.data. (um número). - `opts` (table, opcional) - `id` (string) — Dá nome ao widget: o valor dele é lido como dlg.data. e ele é o alvo de dlg:modify. Letras, dígitos e _ , começando com uma letra; único no diálogo. - `label` (string) — Texto exibido à esquerda do widget; um widget com label começa a própria linha. - `visible` (boolean; padrão true) — Exibe o widget. - `enabled` (boolean; padrão true) — Deixa o usuário alterá-lo. - `text` (number; padrão 0) — O valor inicial. - `min` (number) — Menor valor. - `max` (number) — Maior valor. - `decimals` (integer 0–6; padrão 0) — Casas decimais mantidas. - `onchange` (function(ev)) — Chamado, no script, cada vez que o usuário altera o valor, com ev = { id, value }. Uma rajada de alterações (arrastar um slider) pode chegar como apenas a última. Tudo o que ele altera no documento é um único passo de desfazer. Retorna (table): O diálogo, para encadeamento. #### `dlg:radio(opts?)` — pura Adiciona um botão de opção. Botões de opção lado a lado em uma linha formam um grupo em que um é selecionado; o valor de cada um é dlg.data. (um booleano). - `opts` (table, opcional) - `id` (string) — Dá nome ao widget: o valor dele é lido como dlg.data. e ele é o alvo de dlg:modify. Letras, dígitos e _ , começando com uma letra; único no diálogo. - `label` (string) — Texto exibido à esquerda do widget; um widget com label começa a própria linha. - `visible` (boolean; padrão true) — Exibe o widget. - `enabled` (boolean; padrão true) — Deixa o usuário alterá-lo. - `text` (string) — O texto ao lado do botão. - `selected` (boolean; padrão false) — Começa selecionado. - `onchange` (function(ev)) — Chamado, no script, cada vez que o usuário altera o valor, com ev = { id, value }. Uma rajada de alterações (arrastar um slider) pode chegar como apenas a última. Tudo o que ele altera no documento é um único passo de desfazer. Retorna (table): O diálogo, para encadeamento. #### `dlg:separator(opts?)` — pura Adiciona uma linha horizontal, com texto opcional, na própria linha. - `opts` (table, opcional) - `id` (string) — Dá nome ao widget: o valor dele é lido como dlg.data. e ele é o alvo de dlg:modify. Letras, dígitos e _ , começando com uma letra; único no diálogo. - `label` (string) — Texto exibido à esquerda do widget; um widget com label começa a própria linha. - `visible` (boolean; padrão true) — Exibe o widget. - `enabled` (boolean; padrão true) — Deixa o usuário alterá-lo. - `text` (string) — Texto exibido ao lado da linha. Retorna (table): O diálogo, para encadeamento. #### `dlg:shades(opts?)` — pura Adiciona uma fileira de amostras de cor para escolher. Pressionar uma chama onclick com ev = { id, color }. - `opts` (table, opcional) - `id` (string) — Dá nome ao widget: o valor dele é lido como dlg.data. e ele é o alvo de dlg:modify. Letras, dígitos e _ , começando com uma letra; único no diálogo. - `label` (string) — Texto exibido à esquerda do widget; um widget com label começa a própria linha. - `visible` (boolean; padrão true) — Exibe o widget. - `enabled` (boolean; padrão true) — Deixa o usuário alterá-lo. - `colors` (a list of colors (max 512)) — As amostras. - `onclick` (function(ev)) — Chamado, no script, quando o usuário o pressiona, com ev = { id }. Tudo o que ele altera no documento é um único passo de desfazer. Retorna (table): O diálogo, para encadeamento. #### `dlg:show(opts?)` — pura Abre o diálogo. Não é possível adicionar widgets depois; altere-os com dlg:modify. - `opts` (table, opcional) - `wait` (boolean; padrão true) — true: o diálogo é modal (o estúdio fica esmaecido e bloqueado) e o script para aqui até que ele seja fechado; as alterações feitas antes formam um passo de desfazer próprio, e o resto do script, um novo. false: o diálogo é uma janela flutuante; show retorna na hora e o script continua vivo, ocioso, até o diálogo ser fechado. Retorna (table): O diálogo, para encadeamento. #### `dlg:slider(opts?)` — pura Adiciona um slider. O valor dele é dlg.data. (um número). - `opts` (table, opcional) - `id` (string) — Dá nome ao widget: o valor dele é lido como dlg.data. e ele é o alvo de dlg:modify. Letras, dígitos e _ , começando com uma letra; único no diálogo. - `label` (string) — Texto exibido à esquerda do widget; um widget com label começa a própria linha. - `visible` (boolean; padrão true) — Exibe o widget. - `enabled` (boolean; padrão true) — Deixa o usuário alterá-lo. - `min` (number; padrão 0) — Menor valor. - `max` (number; padrão 100) — Maior valor. - `value` (number; padrão min) — O valor inicial. - `onchange` (function(ev)) — Chamado, no script, cada vez que o usuário altera o valor, com ev = { id, value }. Uma rajada de alterações (arrastar um slider) pode chegar como apenas a última. Tudo o que ele altera no documento é um único passo de desfazer. Retorna (table): O diálogo, para encadeamento. #### `plugin:newCommand(opts)` — pura Registra um comando, do jeito que um plugin do Aseprite faz. Defina uma função global init(plugin) e chame isto dentro dela: function init(plugin) plugin:newCommand{ id = "outline", title = "Thick Outline", group = "edit_fx", onclick = function() ... end } end. Instale o script em Scripts > Comandos de scripts...: o init dele roda uma vez, sem acesso ao documento, para ver o que ele registra, e os comandos então aparecem nos menus, na paleta de comandos e no editor de Atalhos de teclado (onde é possível dar um atalho a eles). Executar um deles inicia o script (o nível superior roda de novo, depois o init e depois o onclick do comando), então mantenha o nível superior só com definições. Até 32 comandos por script. - `opts` (table) - `id` (string) — O id do comando dentro do script: uma letra, depois letras, dígitos, _ ou - (máx. 48). O id de ação dele, usado para atalhos de teclado, é script... - `title` (string) — O texto do menu e da paleta de comandos (máx. 60 caracteres). - `group` (string) — Onde o comando fica nos menus: file, file_import, edit, edit_transform, edit_fx, edit_adjustments, sprite, layer, frame, select ou view. Sem um, ele fica em Scripts > . Um comando em um menu integrado é exibido com o nome do script. - `onclick` (function(ev)) — Chamado, no script, quando o comando é executado. Tudo o que ele altera no documento é um único passo de desfazer. Não retorna nada.