Boîtes de dialogue et commandes
L'interface des scripts, sur le modèle d'Aseprite : Dialog{ title = ... } construit une fenêtre à partir de widgets (label, entry, number, slider, check, radio, combobox, color, shades, button, separator, file) et plugin:newCommand ajoute des commandes aux menus, à la palette de commandes et à l'éditeur de raccourcis clavier. La fenêtre est dessinée par l'éditeur, en texte seulement, avec une barre de titre qui nomme le script et porte la mention "script". Les callbacks (onclick, onchange, onclose) s'exécutent dans le script, un à la fois, chacun en une seule étape d'annulation ; un script dont une boîte de dialogue est ouverte reste actif, au repos, pendant que l'utilisateur continue de dessiner, et l'arrêter ferme ses boîtes de dialogue. Non pris en charge : les widgets de canevas et dlg:repaint. (18 fonctions)
Dialog(opts) — pure
Crée une boîte de dialogue : une fenêtre que le script dessine dans l'éditeur, construite avec les méthodes dlg: et ouverte avec dlg:show. La fenêtre nomme toujours le script et porte la mention "script" pour ne pas passer pour une partie de l'éditeur, et tout ce qu'un script y met est du texte brut. Ajoute des widgets avec les méthodes dlg: (elles s'enchaînent), puis dlg:show{ wait = false } pour une fenêtre qui reste ouverte pendant que l'utilisateur continue de dessiner, ou dlg:show{ wait = true } (par défaut) pour arrêter le script jusqu'à sa fermeture. Un script dont une boîte de dialogue est ouverte reste actif, au repos ; arrêter le script la ferme. Les callbacks (onclick, onchange, onclose) s'exécutent dans le script ; chacun est une seule étape d'annulation. Au plus 4 boîtes de dialogue peuvent être ouvertes et 10 ouvertes par tranche de 10 secondes ; au plus 100 widgets chacune.
opts(table) — Une chaîne de titre, ou une table. Dialog("Title") équivaut à Dialog{ title = "Title" }.title(string) — Affiché en haut de la boîte de dialogue (80 caractères au maximum). Texte seulement.onclose(function(ev)) — Appelé, dans le script, quand l'utilisateur ferme la boîte de dialogue.
Renvoie (table) : La boîte de dialogue. dlg.data est une table des valeurs actuelles des widgets qui ont un id.
dlg:button(opts?) — pure
Ajoute un bouton. Sans onclick, appuyer dessus ferme la boîte de dialogue et met dlg.data.<id> à true (donc après dlg:show{ wait = true } tu peux savoir quel bouton l'a fermée).
opts(table, facultatif)id(string) — Nomme le widget : sa valeur se lit avec dlg.data.<id> et il est la cible de dlg:modify. Lettres, chiffres et _ , en commençant par une lettre ; unique dans la boîte de dialogue.label(string) — Texte affiché à gauche du widget ; un widget avec un label commence sa propre ligne.visible(boolean; par défaut true) — Affiche le widget.enabled(boolean; par défaut true) — Laisse l'utilisateur le modifier.text(string) — Le texte du bouton.focus(boolean; par défaut false) — Démarre avec le focus clavier ici.onclick(function(ev)) — Appelé, dans le script, quand l'utilisateur appuie dessus, avec ev = { id }. Tout ce qu'il modifie dans le document forme une seule étape d'annulation.
Renvoie (table) : La boîte de dialogue, pour l'enchaînement.
dlg:check(opts?) — pure
Ajoute une case à cocher. Sa valeur est dlg.data.<id> (un booléen).
opts(table, facultatif)id(string) — Nomme le widget : sa valeur se lit avec dlg.data.<id> et il est la cible de dlg:modify. Lettres, chiffres et _ , en commençant par une lettre ; unique dans la boîte de dialogue.label(string) — Texte affiché à gauche du widget ; un widget avec un label commence sa propre ligne.visible(boolean; par défaut true) — Affiche le widget.enabled(boolean; par défaut true) — Laisse l'utilisateur le modifier.text(string) — Le texte à côté de la case.selected(boolean; par défaut false) — Démarre cochée.onchange(function(ev)) — Appelé, dans le script, chaque fois que l'utilisateur change la valeur, avec ev = { id, value }. Une rafale de changements (en faisant glisser un slider) peut n'arriver que sous la forme du dernier. Tout ce qu'il modifie dans le document forme une seule étape d'annulation.
Renvoie (table) : La boîte de dialogue, pour l'enchaînement.
dlg:close() — pure
Ferme la boîte de dialogue (depuis le script, p. ex. dans le onclick d'un bouton). Un script se termine quand son bloc principal est terminé et qu'aucune boîte de dialogue n'est ouverte.
Renvoie (table) : La boîte de dialogue, pour l'enchaînement.
dlg:color(opts?) — pure
Ajoute un champ de couleur qui ouvre le sélecteur de couleur complet, avec la palette du sprite et les couleurs récentes. Sa valeur est dlg.data.<id> (une chaîne "#rrggbb" ou "#rrggbbaa").
opts(table, facultatif)id(string) — Nomme le widget : sa valeur se lit avec dlg.data.<id> et il est la cible de dlg:modify. Lettres, chiffres et _ , en commençant par une lettre ; unique dans la boîte de dialogue.label(string) — Texte affiché à gauche du widget ; un widget avec un label commence sa propre ligne.visible(boolean; par défaut true) — Affiche le widget.enabled(boolean; par défaut true) — Laisse l'utilisateur le modifier.color(color ("#rgb", "#rrggbb[aa]" or { r, g, b, a }); par défaut "#000000") — La couleur de départ.onchange(function(ev)) — Appelé, dans le script, chaque fois que l'utilisateur change la valeur, avec ev = { id, value }. Une rafale de changements (en faisant glisser un slider) peut n'arriver que sous la forme du dernier. Tout ce qu'il modifie dans le document forme une seule étape d'annulation.
Renvoie (table) : La boîte de dialogue, pour l'enchaînement.
dlg:combobox(opts?) — pure
Ajoute une liste déroulante. Sa valeur est dlg.data.<id> (le texte de l'option choisie).
opts(table, facultatif)id(string) — Nomme le widget : sa valeur se lit avec dlg.data.<id> et il est la cible de dlg:modify. Lettres, chiffres et _ , en commençant par une lettre ; unique dans la boîte de dialogue.label(string) — Texte affiché à gauche du widget ; un widget avec un label commence sa propre ligne.visible(boolean; par défaut true) — Affiche le widget.enabled(boolean; par défaut true) — Laisse l'utilisateur le modifier.options(a list of strings (max 200)) — Les choix.option(string; par défaut the first option) — Le choix de départ.onchange(function(ev)) — Appelé, dans le script, chaque fois que l'utilisateur change la valeur, avec ev = { id, value }. Une rafale de changements (en faisant glisser un slider) peut n'arriver que sous la forme du dernier. Tout ce qu'il modifie dans le document forme une seule étape d'annulation.
Renvoie (table) : La boîte de dialogue, pour l'enchaînement.
dlg:entry(opts?) — pure
Ajoute une zone de texte. Sa valeur est dlg.data.<id> (une chaîne).
opts(table, facultatif)id(string) — Nomme le widget : sa valeur se lit avec dlg.data.<id> et il est la cible de dlg:modify. Lettres, chiffres et _ , en commençant par une lettre ; unique dans la boîte de dialogue.label(string) — Texte affiché à gauche du widget ; un widget avec un label commence sa propre ligne.visible(boolean; par défaut true) — Affiche le widget.enabled(boolean; par défaut true) — Laisse l'utilisateur le modifier.text(string; par défaut "") — Le texte de départ.focus(boolean; par défaut false) — Démarre avec le focus clavier ici.onchange(function(ev)) — Appelé, dans le script, chaque fois que l'utilisateur change la valeur, avec ev = { id, value }. Une rafale de changements (en faisant glisser un slider) peut n'arriver que sous la forme du dernier. Tout ce qu'il modifie dans le document forme une seule étape d'annulation.
Renvoie (table) : La boîte de dialogue, pour l'enchaînement.
dlg:file(opts?) — pure
Ajoute un sélecteur de fichier (ouverture uniquement : le sélecteur de fichiers du navigateur). dlg.data.<id> est le nom du fichier choisi ; son contenu s'obtient via ev.file dans onchange (et dlg.files.<id>) : { name, size, type, text }, où text n'est défini que pour les petits fichiers texte (jusqu'à 256 KiB). Les images et autres fichiers binaires ne sont pas lisibles.
opts(table, facultatif)id(string) — Nomme le widget : sa valeur se lit avec dlg.data.<id> et il est la cible de dlg:modify. Lettres, chiffres et _ , en commençant par une lettre ; unique dans la boîte de dialogue.label(string) — Texte affiché à gauche du widget ; un widget avec un label commence sa propre ligne.visible(boolean; par défaut true) — Affiche le widget.enabled(boolean; par défaut true) — Laisse l'utilisateur le modifier.filename(string) — Un nom à afficher avant qu'un fichier soit choisi.title(string; par défaut "Choose file...") — Le texte du bouton de sélection.filetypes(a list of extensions without the dot, e.g. { "png", "gpl" }) — Les fichiers que propose le sélecteur.onchange(function(ev)) — Appelé, dans le script, chaque fois que l'utilisateur change la valeur, avec ev = { id, value }. Une rafale de changements (en faisant glisser un slider) peut n'arriver que sous la forme du dernier. Tout ce qu'il modifie dans le document forme une seule étape d'annulation.
Renvoie (table) : La boîte de dialogue, pour l'enchaînement.
dlg:label(opts?) — pure
Ajoute une ligne de texte (plusieurs avec \n, jusqu'à 20 lignes).
opts(table, facultatif)id(string) — Nomme le widget : sa valeur se lit avec dlg.data.<id> et il est la cible de dlg:modify. Lettres, chiffres et _ , en commençant par une lettre ; unique dans la boîte de dialogue.label(string) — Texte affiché à gauche du widget ; un widget avec un label commence sa propre ligne.visible(boolean; par défaut true) — Affiche le widget.enabled(boolean; par défaut true) — Laisse l'utilisateur le modifier.text(string) — Le texte.
Renvoie (table) : La boîte de dialogue, pour l'enchaînement.
dlg:modify(opts?) — pure
Modifie un widget (ou le titre de la boîte de dialogue) pendant que la boîte de dialogue est ouverte ou avant son affichage. Les valeurs sont vérifiées et limitées, et dlg.data suit. Affecter dlg.data = { id = value, ... } fait la même chose pour plusieurs valeurs.
opts(table, facultatif)id(string) — Le widget à modifier. Sans lui, la boîte de dialogue elle-même (title uniquement).title(string) — Le titre de la boîte de dialogue (sans id), ou le texte du bouton d'un widget file.text(string) — Un nouveau texte (la valeur d'un entry ou d'un number ; le texte d'un label, d'un check, d'un radio ou d'un button).value(a number, string or boolean to match the widget) — Une nouvelle valeur pour n'importe quel widget à valeur (le nombre d'un slider, ...).selected(boolean) — Un nouvel état pour un check ou un radio.option(string) — Un nouveau choix pour un combobox.options(a list of strings) — De nouveaux choix pour un combobox.color(color ("#rgb", "#rrggbb[aa]" or { r, g, b, a })) — Une nouvelle couleur pour un widget color.colors(a list of colors) — De nouvelles pastilles pour shades.min(number) — Une nouvelle plus petite valeur (number, slider).max(number) — Une nouvelle plus grande valeur (number, slider).label(string) — Un nouveau label.visible(boolean) — Affiche ou masque le widget.enabled(boolean) — Active ou désactive le widget.
Renvoie (table) : La boîte de dialogue, pour l'enchaînement.
dlg:newrow() — pure
Commence une nouvelle ligne : les widgets ajoutés ensuite se placent en dessous au lieu de à côté du précédent.
Renvoie (table) : La boîte de dialogue, pour l'enchaînement.
dlg:number(opts?) — pure
Ajoute un champ numérique. Sa valeur est dlg.data.<id> (un nombre).
opts(table, facultatif)id(string) — Nomme le widget : sa valeur se lit avec dlg.data.<id> et il est la cible de dlg:modify. Lettres, chiffres et _ , en commençant par une lettre ; unique dans la boîte de dialogue.label(string) — Texte affiché à gauche du widget ; un widget avec un label commence sa propre ligne.visible(boolean; par défaut true) — Affiche le widget.enabled(boolean; par défaut true) — Laisse l'utilisateur le modifier.text(number; par défaut 0) — La valeur de départ.min(number) — Plus petite valeur.max(number) — Plus grande valeur.decimals(integer 0–6; par défaut 0) — Nombre de décimales conservées.onchange(function(ev)) — Appelé, dans le script, chaque fois que l'utilisateur change la valeur, avec ev = { id, value }. Une rafale de changements (en faisant glisser un slider) peut n'arriver que sous la forme du dernier. Tout ce qu'il modifie dans le document forme une seule étape d'annulation.
Renvoie (table) : La boîte de dialogue, pour l'enchaînement.
dlg:radio(opts?) — pure
Ajoute un bouton radio. Les boutons radio placés côte à côte sur une ligne forment un groupe dont un seul est sélectionné ; la valeur de chacun est dlg.data.<id> (un booléen).
opts(table, facultatif)id(string) — Nomme le widget : sa valeur se lit avec dlg.data.<id> et il est la cible de dlg:modify. Lettres, chiffres et _ , en commençant par une lettre ; unique dans la boîte de dialogue.label(string) — Texte affiché à gauche du widget ; un widget avec un label commence sa propre ligne.visible(boolean; par défaut true) — Affiche le widget.enabled(boolean; par défaut true) — Laisse l'utilisateur le modifier.text(string) — Le texte à côté du bouton.selected(boolean; par défaut false) — Démarre sélectionné.onchange(function(ev)) — Appelé, dans le script, chaque fois que l'utilisateur change la valeur, avec ev = { id, value }. Une rafale de changements (en faisant glisser un slider) peut n'arriver que sous la forme du dernier. Tout ce qu'il modifie dans le document forme une seule étape d'annulation.
Renvoie (table) : La boîte de dialogue, pour l'enchaînement.
dlg:separator(opts?) — pure
Ajoute une ligne horizontale, avec un texte facultatif, sur sa propre ligne.
opts(table, facultatif)id(string) — Nomme le widget : sa valeur se lit avec dlg.data.<id> et il est la cible de dlg:modify. Lettres, chiffres et _ , en commençant par une lettre ; unique dans la boîte de dialogue.label(string) — Texte affiché à gauche du widget ; un widget avec un label commence sa propre ligne.visible(boolean; par défaut true) — Affiche le widget.enabled(boolean; par défaut true) — Laisse l'utilisateur le modifier.text(string) — Texte affiché à côté de la ligne.
Renvoie (table) : La boîte de dialogue, pour l'enchaînement.
dlg:shades(opts?) — pure
Ajoute une rangée de pastilles de couleur à choisir. Appuyer sur l'une appelle onclick avec ev = { id, color }.
opts(table, facultatif)id(string) — Nomme le widget : sa valeur se lit avec dlg.data.<id> et il est la cible de dlg:modify. Lettres, chiffres et _ , en commençant par une lettre ; unique dans la boîte de dialogue.label(string) — Texte affiché à gauche du widget ; un widget avec un label commence sa propre ligne.visible(boolean; par défaut true) — Affiche le widget.enabled(boolean; par défaut true) — Laisse l'utilisateur le modifier.colors(a list of colors (max 512)) — Les pastilles.onclick(function(ev)) — Appelé, dans le script, quand l'utilisateur appuie dessus, avec ev = { id }. Tout ce qu'il modifie dans le document forme une seule étape d'annulation.
Renvoie (table) : La boîte de dialogue, pour l'enchaînement.
dlg:show(opts?) — pure
Ouvre la boîte de dialogue. On ne peut plus y ajouter de widgets ensuite ; modifie-les avec dlg:modify.
opts(table, facultatif)wait(boolean; par défaut true) — true : la boîte de dialogue est modale (le studio est assombri et verrouillé) et le script s'arrête ici jusqu'à sa fermeture ; les changements faits avant forment leur propre étape d'annulation, le reste du script une nouvelle. false : la boîte de dialogue est une fenêtre flottante ; show revient aussitôt et le script reste actif, au repos, jusqu'à la fermeture de la boîte de dialogue.
Renvoie (table) : La boîte de dialogue, pour l'enchaînement.
dlg:slider(opts?) — pure
Ajoute un slider. Sa valeur est dlg.data.<id> (un nombre).
opts(table, facultatif)id(string) — Nomme le widget : sa valeur se lit avec dlg.data.<id> et il est la cible de dlg:modify. Lettres, chiffres et _ , en commençant par une lettre ; unique dans la boîte de dialogue.label(string) — Texte affiché à gauche du widget ; un widget avec un label commence sa propre ligne.visible(boolean; par défaut true) — Affiche le widget.enabled(boolean; par défaut true) — Laisse l'utilisateur le modifier.min(number; par défaut 0) — Plus petite valeur.max(number; par défaut 100) — Plus grande valeur.value(number; par défaut min) — La valeur de départ.onchange(function(ev)) — Appelé, dans le script, chaque fois que l'utilisateur change la valeur, avec ev = { id, value }. Une rafale de changements (en faisant glisser un slider) peut n'arriver que sous la forme du dernier. Tout ce qu'il modifie dans le document forme une seule étape d'annulation.
Renvoie (table) : La boîte de dialogue, pour l'enchaînement.
plugin:newCommand(opts) — pure
Enregistre une commande, à la manière d'un plugin Aseprite. Définis une fonction globale init(plugin) et appelle ceci à l'intérieur : function init(plugin) plugin:newCommand{ id = "outline", title = "Thick Outline", group = "edit_fx", onclick = function() ... end } end. Installe le script depuis Scripts > Commandes de scripts... : son init s'exécute une fois, sans accès au document, pour voir ce qu'il enregistre, puis les commandes apparaissent dans les menus, la palette de commandes et l'éditeur de raccourcis clavier (où l'on peut leur donner un raccourci). En exécuter une démarre le script (son niveau supérieur s'exécute de nouveau, puis init, puis le onclick de la commande), donc garde le niveau supérieur pour des définitions. Jusqu'à 32 commandes par script.
opts(table)id(string) — L'id de la commande dans le script : une lettre, puis des lettres, chiffres, _ ou - (48 au maximum). Son id d'action, utilisé pour les raccourcis clavier, est script.<scriptId>.<id>.title(string) — Le texte du menu et de la palette de commandes (60 caractères au maximum).group(string) — Où la commande se place dans les menus : file, file_import, edit, edit_transform, edit_fx, edit_adjustments, sprite, layer, frame, select ou view. Sans groupe, elle va sous Scripts > <nom du script>. Une commande dans un menu intégré s'affiche avec le nom du script.onclick(function(ev)) — Appelé, dans le script, quand la commande s'exécute. Tout ce qu'il modifie dans le document forme une seule étape d'annulation.
Ne renvoie rien.
En Markdown : dialogs.md.