Diálogos e comandos

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.<id> 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.<id> 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.<id> (um booleano).

• opts (table, opcional)
  • id (string) — Dá nome ao widget: o valor dele é lido como dlg.data.<id> 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.<id> (uma string "#rrggbb" ou "#rrggbbaa").

• opts (table, opcional)
  • id (string) — Dá nome ao widget: o valor dele é lido como dlg.data.<id> 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.<id> (o texto da opção escolhida).

• opts (table, opcional)
  • id (string) — Dá nome ao widget: o valor dele é lido como dlg.data.<id> 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.<id> (uma string).

• opts (table, opcional)
  • id (string) — Dá nome ao widget: o valor dele é lido como dlg.data.<id> 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.<id> é o nome do arquivo escolhido; o conteúdo do arquivo é acessado por ev.file no onchange (e por dlg.files.<id>): { 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.<id> 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.<id> 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.<id> (um número).

• opts (table, opcional)
  • id (string) — Dá nome ao widget: o valor dele é lido como dlg.data.<id> 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.<id> (um booleano).

• opts (table, opcional)
  • id (string) — Dá nome ao widget: o valor dele é lido como dlg.data.<id> 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.<id> 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.<id> 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.<id> (um número).

• opts (table, opcional)
  • id (string) — Dá nome ao widget: o valor dele é lido como dlg.data.<id> 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.<scriptId>.<id>.
  • 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 > <nome do script>. 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.

Em Markdown: dialogs.md.