Dialoghi e comandi
UI per gli script, sul modello di Aseprite: Dialog{ title = ... } costruisce una finestra a partire da widget (label, entry, number, slider, check, radio, combobox, color, shades, button, separator, file) e plugin:newCommand aggiunge comandi ai menu, alla palette dei comandi e all'editor delle scorciatoie da tastiera. La finestra è disegnata dall'editor, solo come testo, con una barra del titolo che nomina lo script e la contrassegna come "script". Le callback (onclick, onchange, onclose) girano nello script, una alla volta, ciascuna come un unico passo di annullamento; uno script con un dialogo aperto resta vivo, inattivo, mentre l'utente continua a disegnare, e fermarlo chiude i suoi dialoghi. Non supportati: widget canvas e dlg:repaint. (18 funzioni)
Dialog(opts) — pura
Crea un dialogo: una finestra che lo script disegna nell'editor, costruita con i metodi dlg: e aperta con dlg:show. La finestra nomina sempre lo script ed è contrassegnata come "script" così da non poter passare per una parte dell'editor, e tutto ciò che uno script ci mette è semplice testo. Aggiungi widget con i metodi dlg: (si concatenano), poi dlg:show{ wait = false } per una finestra che resta aperta mentre l'utente continua a disegnare, oppure dlg:show{ wait = true } (predefinito) per fermare lo script finché non viene chiusa. Uno script con un dialogo aperto resta vivo, inattivo; fermare lo script lo chiude. Le callback (onclick, onchange, onclose) girano nello script; ciascuna è un unico passo di annullamento. Si possono aprire al massimo 4 dialoghi e 10 ogni 10 secondi; al massimo 100 widget ciascuno.
opts(table) — Una stringa di titolo, oppure una tabella. Dialog("Title") equivale a Dialog{ title = "Title" }.title(string) — Mostrato in cima al dialogo (max 80 caratteri). Solo testo.onclose(function(ev)) — Chiamata, nello script, quando l'utente chiude il dialogo.
Restituisce (table): Il dialogo. dlg.data è una tabella dei valori correnti dei widget che hanno un id.
dlg:button(opts?) — pura
Aggiunge un pulsante. Senza onclick, premerlo chiude il dialogo e imposta dlg.data.<id> a true (così dopo dlg:show{ wait = true } puoi capire quale pulsante lo ha chiuso).
opts(table, facoltativo)id(string) — Dà un nome al widget: il suo valore si legge come dlg.data.<id> ed è la destinazione di dlg:modify. Lettere, cifre e _ , iniziando con una lettera; unico nel dialogo.label(string) — Testo mostrato a sinistra del widget; un widget con un'etichetta inizia una sua riga.visible(boolean; predefinito true) — Mostra il widget.enabled(boolean; predefinito true) — Lascia che l'utente lo modifichi.text(string) — Il testo del pulsante.focus(boolean; predefinito false) — Parte con il focus della tastiera qui.onclick(function(ev)) — Chiamata, nello script, quando l'utente lo preme, con ev = { id }. Tutto ciò che cambia nel documento è un unico passo di annullamento.
Restituisce (table): Il dialogo, per concatenare le chiamate.
dlg:check(opts?) — pura
Aggiunge una casella di controllo. Il suo valore è dlg.data.<id> (un booleano).
opts(table, facoltativo)id(string) — Dà un nome al widget: il suo valore si legge come dlg.data.<id> ed è la destinazione di dlg:modify. Lettere, cifre e _ , iniziando con una lettera; unico nel dialogo.label(string) — Testo mostrato a sinistra del widget; un widget con un'etichetta inizia una sua riga.visible(boolean; predefinito true) — Mostra il widget.enabled(boolean; predefinito true) — Lascia che l'utente lo modifichi.text(string) — Il testo accanto alla casella.selected(boolean; predefinito false) — Parte selezionata.onchange(function(ev)) — Chiamata, nello script, ogni volta che l'utente cambia il valore, con ev = { id, value }. Una raffica di modifiche (trascinando uno slider) può arrivare come la sola ultima. Tutto ciò che cambia nel documento è un unico passo di annullamento.
Restituisce (table): Il dialogo, per concatenare le chiamate.
dlg:close() — pura
Chiude il dialogo (dallo script, ad es. nell'onclick di un pulsante). Uno script termina quando il suo chunk principale è finito e nessun dialogo è aperto.
Restituisce (table): Il dialogo, per concatenare le chiamate.
dlg:color(opts?) — pura
Aggiunge un campo colore che apre il selettore colori completo, con la palette dello sprite e i colori recenti. Il suo valore è dlg.data.<id> (una stringa "#rrggbb" o "#rrggbbaa").
opts(table, facoltativo)id(string) — Dà un nome al widget: il suo valore si legge come dlg.data.<id> ed è la destinazione di dlg:modify. Lettere, cifre e _ , iniziando con una lettera; unico nel dialogo.label(string) — Testo mostrato a sinistra del widget; un widget con un'etichetta inizia una sua riga.visible(boolean; predefinito true) — Mostra il widget.enabled(boolean; predefinito true) — Lascia che l'utente lo modifichi.color(color ("#rgb", "#rrggbb[aa]" or { r, g, b, a }); predefinito "#000000") — Il colore iniziale.onchange(function(ev)) — Chiamata, nello script, ogni volta che l'utente cambia il valore, con ev = { id, value }. Una raffica di modifiche (trascinando uno slider) può arrivare come la sola ultima. Tutto ciò che cambia nel documento è un unico passo di annullamento.
Restituisce (table): Il dialogo, per concatenare le chiamate.
dlg:combobox(opts?) — pura
Aggiunge un elenco a discesa. Il suo valore è dlg.data.<id> (il testo dell'opzione scelta).
opts(table, facoltativo)id(string) — Dà un nome al widget: il suo valore si legge come dlg.data.<id> ed è la destinazione di dlg:modify. Lettere, cifre e _ , iniziando con una lettera; unico nel dialogo.label(string) — Testo mostrato a sinistra del widget; un widget con un'etichetta inizia una sua riga.visible(boolean; predefinito true) — Mostra il widget.enabled(boolean; predefinito true) — Lascia che l'utente lo modifichi.options(a list of strings (max 200)) — Le scelte.option(string; predefinito the first option) — La scelta iniziale.onchange(function(ev)) — Chiamata, nello script, ogni volta che l'utente cambia il valore, con ev = { id, value }. Una raffica di modifiche (trascinando uno slider) può arrivare come la sola ultima. Tutto ciò che cambia nel documento è un unico passo di annullamento.
Restituisce (table): Il dialogo, per concatenare le chiamate.
dlg:entry(opts?) — pura
Aggiunge una casella di testo. Il suo valore è dlg.data.<id> (una stringa).
opts(table, facoltativo)id(string) — Dà un nome al widget: il suo valore si legge come dlg.data.<id> ed è la destinazione di dlg:modify. Lettere, cifre e _ , iniziando con una lettera; unico nel dialogo.label(string) — Testo mostrato a sinistra del widget; un widget con un'etichetta inizia una sua riga.visible(boolean; predefinito true) — Mostra il widget.enabled(boolean; predefinito true) — Lascia che l'utente lo modifichi.text(string; predefinito "") — Il testo iniziale.focus(boolean; predefinito false) — Parte con il focus della tastiera qui.onchange(function(ev)) — Chiamata, nello script, ogni volta che l'utente cambia il valore, con ev = { id, value }. Una raffica di modifiche (trascinando uno slider) può arrivare come la sola ultima. Tutto ciò che cambia nel documento è un unico passo di annullamento.
Restituisce (table): Il dialogo, per concatenare le chiamate.
dlg:file(opts?) — pura
Aggiunge un selettore di file (solo apertura: il selettore file del browser). dlg.data.<id> è il nome del file scelto; il contenuto del file si raggiunge tramite ev.file in onchange (e dlg.files.<id>): { name, size, type, text }, dove text è impostato solo per i file di testo piccoli (fino a 256 KiB). Le immagini e gli altri file binari non sono leggibili.
opts(table, facoltativo)id(string) — Dà un nome al widget: il suo valore si legge come dlg.data.<id> ed è la destinazione di dlg:modify. Lettere, cifre e _ , iniziando con una lettera; unico nel dialogo.label(string) — Testo mostrato a sinistra del widget; un widget con un'etichetta inizia una sua riga.visible(boolean; predefinito true) — Mostra il widget.enabled(boolean; predefinito true) — Lascia che l'utente lo modifichi.filename(string) — Un nome da mostrare prima che venga scelto un file.title(string; predefinito "Choose file...") — Il testo del pulsante del selettore.filetypes(a list of extensions without the dot, e.g. { "png", "gpl" }) — I file che il selettore propone.onchange(function(ev)) — Chiamata, nello script, ogni volta che l'utente cambia il valore, con ev = { id, value }. Una raffica di modifiche (trascinando uno slider) può arrivare come la sola ultima. Tutto ciò che cambia nel documento è un unico passo di annullamento.
Restituisce (table): Il dialogo, per concatenare le chiamate.
dlg:label(opts?) — pura
Aggiunge una riga di testo (più righe con \n, fino a 20).
opts(table, facoltativo)id(string) — Dà un nome al widget: il suo valore si legge come dlg.data.<id> ed è la destinazione di dlg:modify. Lettere, cifre e _ , iniziando con una lettera; unico nel dialogo.label(string) — Testo mostrato a sinistra del widget; un widget con un'etichetta inizia una sua riga.visible(boolean; predefinito true) — Mostra il widget.enabled(boolean; predefinito true) — Lascia che l'utente lo modifichi.text(string) — Il testo.
Restituisce (table): Il dialogo, per concatenare le chiamate.
dlg:modify(opts?) — pura
Cambia un widget (o il titolo del dialogo) mentre il dialogo è aperto o prima che venga mostrato. I valori vengono controllati e limitati, e dlg.data li segue. Assegnare dlg.data = { id = value, ... } fa lo stesso per più valori.
opts(table, facoltativo)id(string) — Il widget da cambiare. Senza, il dialogo stesso (solo title).title(string) — Il titolo del dialogo (senza id), oppure il testo del pulsante di un widget file.text(string) — Un nuovo testo (il valore di un entry o number; il testo di un label, check, radio o button).value(a number, string or boolean to match the widget) — Un nuovo valore di qualsiasi widget con valore (il numero di uno slider, ...).selected(boolean) — Un nuovo stato per un check o radio.option(string) — Una nuova scelta per un combobox.options(a list of strings) — Nuove scelte per un combobox.color(color ("#rgb", "#rrggbb[aa]" or { r, g, b, a })) — Un nuovo colore per un widget color.colors(a list of colors) — Nuovi campioni per shades.min(number) — Un nuovo valore minimo (number, slider).max(number) — Un nuovo valore massimo (number, slider).label(string) — Una nuova etichetta.visible(boolean) — Mostra o nasconde il widget.enabled(boolean) — Abilita o disabilita il widget.
Restituisce (table): Il dialogo, per concatenare le chiamate.
dlg:newrow() — pura
Inizia una nuova riga: i widget aggiunti dopo vanno sotto invece che accanto al precedente.
Restituisce (table): Il dialogo, per concatenare le chiamate.
dlg:number(opts?) — pura
Aggiunge una casella numerica. Il suo valore è dlg.data.<id> (un numero).
opts(table, facoltativo)id(string) — Dà un nome al widget: il suo valore si legge come dlg.data.<id> ed è la destinazione di dlg:modify. Lettere, cifre e _ , iniziando con una lettera; unico nel dialogo.label(string) — Testo mostrato a sinistra del widget; un widget con un'etichetta inizia una sua riga.visible(boolean; predefinito true) — Mostra il widget.enabled(boolean; predefinito true) — Lascia che l'utente lo modifichi.text(number; predefinito 0) — Il valore iniziale.min(number) — Valore minimo.max(number) — Valore massimo.decimals(integer 0–6; predefinito 0) — Cifre decimali mantenute.onchange(function(ev)) — Chiamata, nello script, ogni volta che l'utente cambia il valore, con ev = { id, value }. Una raffica di modifiche (trascinando uno slider) può arrivare come la sola ultima. Tutto ciò che cambia nel documento è un unico passo di annullamento.
Restituisce (table): Il dialogo, per concatenare le chiamate.
dlg:radio(opts?) — pura
Aggiunge un pulsante di opzione. I pulsanti di opzione affiancati in una riga formano un gruppo in cui uno è selezionato; il valore di ciascuno è dlg.data.<id> (un booleano).
opts(table, facoltativo)id(string) — Dà un nome al widget: il suo valore si legge come dlg.data.<id> ed è la destinazione di dlg:modify. Lettere, cifre e _ , iniziando con una lettera; unico nel dialogo.label(string) — Testo mostrato a sinistra del widget; un widget con un'etichetta inizia una sua riga.visible(boolean; predefinito true) — Mostra il widget.enabled(boolean; predefinito true) — Lascia che l'utente lo modifichi.text(string) — Il testo accanto al pulsante.selected(boolean; predefinito false) — Parte selezionato.onchange(function(ev)) — Chiamata, nello script, ogni volta che l'utente cambia il valore, con ev = { id, value }. Una raffica di modifiche (trascinando uno slider) può arrivare come la sola ultima. Tutto ciò che cambia nel documento è un unico passo di annullamento.
Restituisce (table): Il dialogo, per concatenare le chiamate.
dlg:separator(opts?) — pura
Aggiunge una linea orizzontale, con testo facoltativo, su una riga a sé.
opts(table, facoltativo)id(string) — Dà un nome al widget: il suo valore si legge come dlg.data.<id> ed è la destinazione di dlg:modify. Lettere, cifre e _ , iniziando con una lettera; unico nel dialogo.label(string) — Testo mostrato a sinistra del widget; un widget con un'etichetta inizia una sua riga.visible(boolean; predefinito true) — Mostra il widget.enabled(boolean; predefinito true) — Lascia che l'utente lo modifichi.text(string) — Testo mostrato accanto alla linea.
Restituisce (table): Il dialogo, per concatenare le chiamate.
dlg:shades(opts?) — pura
Aggiunge una fila di campioni di colore tra cui scegliere. Premerne uno chiama onclick con ev = { id, color }.
opts(table, facoltativo)id(string) — Dà un nome al widget: il suo valore si legge come dlg.data.<id> ed è la destinazione di dlg:modify. Lettere, cifre e _ , iniziando con una lettera; unico nel dialogo.label(string) — Testo mostrato a sinistra del widget; un widget con un'etichetta inizia una sua riga.visible(boolean; predefinito true) — Mostra il widget.enabled(boolean; predefinito true) — Lascia che l'utente lo modifichi.colors(a list of colors (max 512)) — I campioni.onclick(function(ev)) — Chiamata, nello script, quando l'utente lo preme, con ev = { id }. Tutto ciò che cambia nel documento è un unico passo di annullamento.
Restituisce (table): Il dialogo, per concatenare le chiamate.
dlg:show(opts?) — pura
Apre il dialogo. Dopo non si possono aggiungere widget; cambiali con dlg:modify.
opts(table, facoltativo)wait(boolean; predefinito true) — true: il dialogo è modale (lo studio è oscurato e bloccato) e lo script si ferma qui finché non viene chiuso; le modifiche fatte prima sono un passo di annullamento a sé, il resto dello script uno nuovo. false: il dialogo è una finestra mobile; show ritorna subito e lo script resta vivo, inattivo, finché il dialogo non viene chiuso.
Restituisce (table): Il dialogo, per concatenare le chiamate.
dlg:slider(opts?) — pura
Aggiunge uno slider. Il suo valore è dlg.data.<id> (un numero).
opts(table, facoltativo)id(string) — Dà un nome al widget: il suo valore si legge come dlg.data.<id> ed è la destinazione di dlg:modify. Lettere, cifre e _ , iniziando con una lettera; unico nel dialogo.label(string) — Testo mostrato a sinistra del widget; un widget con un'etichetta inizia una sua riga.visible(boolean; predefinito true) — Mostra il widget.enabled(boolean; predefinito true) — Lascia che l'utente lo modifichi.min(number; predefinito 0) — Valore minimo.max(number; predefinito 100) — Valore massimo.value(number; predefinito min) — Il valore iniziale.onchange(function(ev)) — Chiamata, nello script, ogni volta che l'utente cambia il valore, con ev = { id, value }. Una raffica di modifiche (trascinando uno slider) può arrivare come la sola ultima. Tutto ciò che cambia nel documento è un unico passo di annullamento.
Restituisce (table): Il dialogo, per concatenare le chiamate.
plugin:newCommand(opts) — pura
Registra un comando, come fa un plugin di Aseprite. Definisci una funzione globale init(plugin) e chiama questo metodo al suo interno: function init(plugin) plugin:newCommand{ id = "outline", title = "Thick Outline", group = "edit_fx", onclick = function() ... end } end. Installa lo script da Script > Comandi script...: il suo init gira una volta, senza accesso al documento, per vedere cosa registra, e poi i comandi compaiono nei menu, nella palette dei comandi e nell'editor delle scorciatoie da tastiera (dove si può assegnare loro una scorciatoia). Eseguirne uno avvia lo script (il suo livello superiore gira di nuovo, poi init, poi l'onclick del comando), quindi tieni il livello superiore a sole definizioni. Fino a 32 comandi per script.
opts(table)id(string) — L'id del comando all'interno dello script: una lettera, poi lettere, cifre, _ o - (max 48). Il suo id azione, usato per le scorciatoie da tastiera, è script.<scriptId>.<id>.title(string) — Il testo nel menu e nella palette dei comandi (max 60 caratteri).group(string) — Dove va il comando nei menu: file, file_import, edit, edit_transform, edit_fx, edit_adjustments, sprite, layer, frame, select o view. Senza, va sotto Script > <nome dello script>. Un comando in un menu integrato viene mostrato con il nome dello script.onclick(function(ev)) — Chiamata, nello script, quando il comando viene eseguito. Tutto ciò che cambia nel documento è un unico passo di annullamento.
Non restituisce nulla.
In Markdown: dialogs.md.