# Lua-Skript-API von pxstud.io — Dialoge und Befehle > Teil der Lua-Skript-Referenz von pxstud.io, deren Übersicht (https://pxstud.io/de/docs/scripting.md) die Konventionen erklärt. Die Optionsgruppen und Typen, auf die sie verweist, stehen in https://pxstud.io/de/docs/scripting/option-groups.md und https://pxstud.io/de/docs/scripting/types.md. Alles in einer Datei (auf Englisch): https://pxstud.io/llms-full.txt. Das Verzeichnis der ganzen Website (auf Englisch): https://pxstud.io/llms.txt. ### Dialoge und Befehle Skript-Oberfläche nach dem Vorbild von Aseprite: Dialog{ title = ... } baut ein Fenster aus Widgets (label, entry, number, slider, check, radio, combobox, color, shades, button, separator, file), und plugin:newCommand fügt den Menüs, der Befehlspalette und dem Editor für Tastenkürzel Befehle hinzu. Das Fenster wird vom Editor gezeichnet, nur als Text, mit einer Titelleiste, die das Skript nennt und als "script" markiert. Callbacks (onclick, onchange, onclose) laufen im Skript, einer nach dem anderen, jeder als ein einzelner Rückgängig-Schritt; ein Skript mit offenem Dialog bleibt am Leben, im Leerlauf, während du weiterzeichnest, und wird es angehalten, schließt das seine Dialoge. Nicht unterstützt: Canvas-Widgets und dlg:repaint. #### `Dialog(opts)` — rein Erstellt einen Dialog: ein Fenster, das das Skript im Editor zeichnet, gebaut mit den dlg:-Methoden und geöffnet mit dlg:show. Das Fenster nennt immer das Skript und ist als "script" markiert, damit es nicht als Teil des Editors durchgeht, und alles, was ein Skript hineinlegt, ist reiner Text. Füge Widgets mit den dlg:-Methoden hinzu (sie lassen sich verketten), dann dlg:show{ wait = false } für ein Fenster, das offen bleibt, während du weiterzeichnest, oder dlg:show{ wait = true } (der Standard), um das Skript anzuhalten, bis es geschlossen wird. Ein Skript mit offenem Dialog bleibt am Leben, im Leerlauf; das Anhalten des Skripts schließt ihn. Callbacks (onclick, onchange, onclose) laufen im Skript; jeder ist ein einzelner Rückgängig-Schritt. Höchstens 4 Dialoge können offen sein und 10 pro 10 Sekunden geöffnet werden; höchstens je 100 Widgets. - `opts` (table) — Ein Titel-String oder eine Tabelle. Dialog("Title") ist Dialog{ title = "Title" }. - `title` (string) — Wird oben im Dialog angezeigt (max. 80 Zeichen). Nur Text. - `onclose` (function(ev)) — Wird im Skript aufgerufen, wenn der Dialog geschlossen wird. Gibt zurück (table): Der Dialog. dlg.data ist eine Tabelle mit den aktuellen Werten der Widgets, die eine id haben. #### `dlg:button(opts?)` — rein Fügt eine Schaltfläche hinzu. Ohne onclick schließt ihr Drücken den Dialog und setzt dlg.data. auf true (so erkennst du nach dlg:show{ wait = true }, welche Schaltfläche ihn geschlossen hat). - `opts` (table, optional) - `id` (string) — Benennt das Widget: Sein Wert wird als dlg.data. gelesen, und es ist das Ziel von dlg:modify. Buchstaben, Ziffern und _ , beginnend mit einem Buchstaben; eindeutig im Dialog. - `label` (string) — Text links vom Widget; ein Widget mit label beginnt eine eigene Zeile. - `visible` (boolean; Standard true) — Zeigt das Widget an. - `enabled` (boolean; Standard true) — Erlaubt es, das Widget zu ändern. - `text` (string) — Der Text der Schaltfläche. - `focus` (boolean; Standard false) — Startet mit dem Tastaturfokus hier. - `onclick` (function(ev)) — Wird im Skript aufgerufen, wenn das Widget gedrückt wird, mit ev = { id }. Alles, was dadurch im Dokument geändert wird, ist ein Rückgängig-Schritt. Gibt zurück (table): Der Dialog, zum Verketten. #### `dlg:check(opts?)` — rein Fügt ein Kontrollkästchen hinzu. Sein Wert ist dlg.data. (ein Boolean). - `opts` (table, optional) - `id` (string) — Benennt das Widget: Sein Wert wird als dlg.data. gelesen, und es ist das Ziel von dlg:modify. Buchstaben, Ziffern und _ , beginnend mit einem Buchstaben; eindeutig im Dialog. - `label` (string) — Text links vom Widget; ein Widget mit label beginnt eine eigene Zeile. - `visible` (boolean; Standard true) — Zeigt das Widget an. - `enabled` (boolean; Standard true) — Erlaubt es, das Widget zu ändern. - `text` (string) — Der Text neben dem Kästchen. - `selected` (boolean; Standard false) — Startet angehakt. - `onchange` (function(ev)) — Wird im Skript jedes Mal aufgerufen, wenn der Wert geändert wird, mit ev = { id, value }. Eine Folge von Änderungen (Ziehen eines Schiebereglers) kommt unter Umständen nur als die letzte an. Alles, was dadurch im Dokument geändert wird, ist ein Rückgängig-Schritt. Gibt zurück (table): Der Dialog, zum Verketten. #### `dlg:close()` — rein Schließt den Dialog (aus dem Skript, z. B. im onclick einer Schaltfläche). Ein Skript endet, wenn sein Hauptblock fertig ist und kein Dialog offen ist. Gibt zurück (table): Der Dialog, zum Verketten. #### `dlg:color(opts?)` — rein Fügt ein Farbfeld hinzu, das die volle Farbauswahl öffnet, mit der Palette des Sprites und den zuletzt verwendeten Farben. Sein Wert ist dlg.data. (ein String "#rrggbb" oder "#rrggbbaa"). - `opts` (table, optional) - `id` (string) — Benennt das Widget: Sein Wert wird als dlg.data. gelesen, und es ist das Ziel von dlg:modify. Buchstaben, Ziffern und _ , beginnend mit einem Buchstaben; eindeutig im Dialog. - `label` (string) — Text links vom Widget; ein Widget mit label beginnt eine eigene Zeile. - `visible` (boolean; Standard true) — Zeigt das Widget an. - `enabled` (boolean; Standard true) — Erlaubt es, das Widget zu ändern. - `color` (color ("#rgb", "#rrggbb[aa]" or { r, g, b, a }); Standard "#000000") — Die Startfarbe. - `onchange` (function(ev)) — Wird im Skript jedes Mal aufgerufen, wenn der Wert geändert wird, mit ev = { id, value }. Eine Folge von Änderungen (Ziehen eines Schiebereglers) kommt unter Umständen nur als die letzte an. Alles, was dadurch im Dokument geändert wird, ist ein Rückgängig-Schritt. Gibt zurück (table): Der Dialog, zum Verketten. #### `dlg:combobox(opts?)` — rein Fügt eine Dropdown-Liste hinzu. Ihr Wert ist dlg.data. (der Text der gewählten Option). - `opts` (table, optional) - `id` (string) — Benennt das Widget: Sein Wert wird als dlg.data. gelesen, und es ist das Ziel von dlg:modify. Buchstaben, Ziffern und _ , beginnend mit einem Buchstaben; eindeutig im Dialog. - `label` (string) — Text links vom Widget; ein Widget mit label beginnt eine eigene Zeile. - `visible` (boolean; Standard true) — Zeigt das Widget an. - `enabled` (boolean; Standard true) — Erlaubt es, das Widget zu ändern. - `options` (a list of strings (max 200)) — Die Auswahlmöglichkeiten. - `option` (string; Standard the first option) — Die anfängliche Auswahl. - `onchange` (function(ev)) — Wird im Skript jedes Mal aufgerufen, wenn der Wert geändert wird, mit ev = { id, value }. Eine Folge von Änderungen (Ziehen eines Schiebereglers) kommt unter Umständen nur als die letzte an. Alles, was dadurch im Dokument geändert wird, ist ein Rückgängig-Schritt. Gibt zurück (table): Der Dialog, zum Verketten. #### `dlg:entry(opts?)` — rein Fügt ein Textfeld hinzu. Sein Wert ist dlg.data. (ein String). - `opts` (table, optional) - `id` (string) — Benennt das Widget: Sein Wert wird als dlg.data. gelesen, und es ist das Ziel von dlg:modify. Buchstaben, Ziffern und _ , beginnend mit einem Buchstaben; eindeutig im Dialog. - `label` (string) — Text links vom Widget; ein Widget mit label beginnt eine eigene Zeile. - `visible` (boolean; Standard true) — Zeigt das Widget an. - `enabled` (boolean; Standard true) — Erlaubt es, das Widget zu ändern. - `text` (string; Standard "") — Der Starttext. - `focus` (boolean; Standard false) — Startet mit dem Tastaturfokus hier. - `onchange` (function(ev)) — Wird im Skript jedes Mal aufgerufen, wenn der Wert geändert wird, mit ev = { id, value }. Eine Folge von Änderungen (Ziehen eines Schiebereglers) kommt unter Umständen nur als die letzte an. Alles, was dadurch im Dokument geändert wird, ist ein Rückgängig-Schritt. Gibt zurück (table): Der Dialog, zum Verketten. #### `dlg:file(opts?)` — rein Fügt eine Dateiauswahl hinzu (nur Öffnen: der Dateiauswahldialog des Browsers). dlg.data. ist der Name der gewählten Datei; auf ihren Inhalt greifst du über ev.file in onchange (und dlg.files.) zu: { name, size, type, text }, wobei text nur bei kleinen Textdateien gesetzt ist (bis 256 KiB). Bilder und andere Binärdateien sind nicht lesbar. - `opts` (table, optional) - `id` (string) — Benennt das Widget: Sein Wert wird als dlg.data. gelesen, und es ist das Ziel von dlg:modify. Buchstaben, Ziffern und _ , beginnend mit einem Buchstaben; eindeutig im Dialog. - `label` (string) — Text links vom Widget; ein Widget mit label beginnt eine eigene Zeile. - `visible` (boolean; Standard true) — Zeigt das Widget an. - `enabled` (boolean; Standard true) — Erlaubt es, das Widget zu ändern. - `filename` (string) — Ein Name, der angezeigt wird, bevor eine Datei gewählt ist. - `title` (string; Standard "Choose file...") — Der Text der Auswahl-Schaltfläche. - `filetypes` (a list of extensions without the dot, e.g. { "png", "gpl" }) — Dateien, die der Dateiauswahldialog anbietet. - `onchange` (function(ev)) — Wird im Skript jedes Mal aufgerufen, wenn der Wert geändert wird, mit ev = { id, value }. Eine Folge von Änderungen (Ziehen eines Schiebereglers) kommt unter Umständen nur als die letzte an. Alles, was dadurch im Dokument geändert wird, ist ein Rückgängig-Schritt. Gibt zurück (table): Der Dialog, zum Verketten. #### `dlg:label(opts?)` — rein Fügt eine Textzeile hinzu (mehrere mit \n, bis zu 20 Zeilen). - `opts` (table, optional) - `id` (string) — Benennt das Widget: Sein Wert wird als dlg.data. gelesen, und es ist das Ziel von dlg:modify. Buchstaben, Ziffern und _ , beginnend mit einem Buchstaben; eindeutig im Dialog. - `label` (string) — Text links vom Widget; ein Widget mit label beginnt eine eigene Zeile. - `visible` (boolean; Standard true) — Zeigt das Widget an. - `enabled` (boolean; Standard true) — Erlaubt es, das Widget zu ändern. - `text` (string) — Der Text. Gibt zurück (table): Der Dialog, zum Verketten. #### `dlg:modify(opts?)` — rein Ändert ein Widget (oder den Titel des Dialogs), während der Dialog offen ist oder bevor er angezeigt wird. Werte werden geprüft und begrenzt, und dlg.data folgt. Die Zuweisung dlg.data = { id = value, ... } tut dasselbe für mehrere Werte. - `opts` (table, optional) - `id` (string) — Das Widget, das geändert wird. Ohne sie der Dialog selbst (nur title). - `title` (string) — Der Titel des Dialogs (ohne id) oder der Schaltflächentext eines file-Widgets. - `text` (string) — Ein neuer Text (der Wert eines entry oder number; der Text eines label, check, radio oder button). - `value` (a number, string or boolean to match the widget) — Ein neuer Wert eines beliebigen Wert-Widgets (die Zahl eines slider, ...). - `selected` (boolean) — Ein neuer Zustand für ein check oder radio. - `option` (string) — Eine neue Auswahl für eine combobox. - `options` (a list of strings) — Neue Auswahlmöglichkeiten für eine combobox. - `color` (color ("#rgb", "#rrggbb[aa]" or { r, g, b, a })) — Eine neue Farbe für ein color-Widget. - `colors` (a list of colors) — Neue Farbfelder für shades. - `min` (number) — Ein neuer kleinster Wert (number, slider). - `max` (number) — Ein neuer größter Wert (number, slider). - `label` (string) — Ein neues label. - `visible` (boolean) — Blendet das Widget ein oder aus. - `enabled` (boolean) — Aktiviert oder deaktiviert das Widget. Gibt zurück (table): Der Dialog, zum Verketten. #### `dlg:newrow()` — rein Beginnt eine neue Zeile: Als Nächstes hinzugefügte Widgets kommen darunter statt neben das vorherige. Gibt zurück (table): Der Dialog, zum Verketten. #### `dlg:number(opts?)` — rein Fügt ein Zahlenfeld hinzu. Sein Wert ist dlg.data. (eine Zahl). - `opts` (table, optional) - `id` (string) — Benennt das Widget: Sein Wert wird als dlg.data. gelesen, und es ist das Ziel von dlg:modify. Buchstaben, Ziffern und _ , beginnend mit einem Buchstaben; eindeutig im Dialog. - `label` (string) — Text links vom Widget; ein Widget mit label beginnt eine eigene Zeile. - `visible` (boolean; Standard true) — Zeigt das Widget an. - `enabled` (boolean; Standard true) — Erlaubt es, das Widget zu ändern. - `text` (number; Standard 0) — Der Startwert. - `min` (number) — Kleinster Wert. - `max` (number) — Größter Wert. - `decimals` (integer 0–6; Standard 0) — Beibehaltene Dezimalstellen. - `onchange` (function(ev)) — Wird im Skript jedes Mal aufgerufen, wenn der Wert geändert wird, mit ev = { id, value }. Eine Folge von Änderungen (Ziehen eines Schiebereglers) kommt unter Umständen nur als die letzte an. Alles, was dadurch im Dokument geändert wird, ist ein Rückgängig-Schritt. Gibt zurück (table): Der Dialog, zum Verketten. #### `dlg:radio(opts?)` — rein Fügt eine Optionsschaltfläche hinzu. Nebeneinander in einer Zeile stehende Optionsschaltflächen bilden eine Gruppe, in der eine ausgewählt ist; der Wert jeder ist dlg.data. (ein Boolean). - `opts` (table, optional) - `id` (string) — Benennt das Widget: Sein Wert wird als dlg.data. gelesen, und es ist das Ziel von dlg:modify. Buchstaben, Ziffern und _ , beginnend mit einem Buchstaben; eindeutig im Dialog. - `label` (string) — Text links vom Widget; ein Widget mit label beginnt eine eigene Zeile. - `visible` (boolean; Standard true) — Zeigt das Widget an. - `enabled` (boolean; Standard true) — Erlaubt es, das Widget zu ändern. - `text` (string) — Der Text neben der Schaltfläche. - `selected` (boolean; Standard false) — Startet ausgewählt. - `onchange` (function(ev)) — Wird im Skript jedes Mal aufgerufen, wenn der Wert geändert wird, mit ev = { id, value }. Eine Folge von Änderungen (Ziehen eines Schiebereglers) kommt unter Umständen nur als die letzte an. Alles, was dadurch im Dokument geändert wird, ist ein Rückgängig-Schritt. Gibt zurück (table): Der Dialog, zum Verketten. #### `dlg:separator(opts?)` — rein Fügt in einer eigenen Zeile eine horizontale Linie hinzu, optional mit Text. - `opts` (table, optional) - `id` (string) — Benennt das Widget: Sein Wert wird als dlg.data. gelesen, und es ist das Ziel von dlg:modify. Buchstaben, Ziffern und _ , beginnend mit einem Buchstaben; eindeutig im Dialog. - `label` (string) — Text links vom Widget; ein Widget mit label beginnt eine eigene Zeile. - `visible` (boolean; Standard true) — Zeigt das Widget an. - `enabled` (boolean; Standard true) — Erlaubt es, das Widget zu ändern. - `text` (string) — Text, der neben der Linie angezeigt wird. Gibt zurück (table): Der Dialog, zum Verketten. #### `dlg:shades(opts?)` — rein Fügt eine Reihe von Farbfeldern zur Auswahl hinzu. Das Drücken eines ruft onclick mit ev = { id, color } auf. - `opts` (table, optional) - `id` (string) — Benennt das Widget: Sein Wert wird als dlg.data. gelesen, und es ist das Ziel von dlg:modify. Buchstaben, Ziffern und _ , beginnend mit einem Buchstaben; eindeutig im Dialog. - `label` (string) — Text links vom Widget; ein Widget mit label beginnt eine eigene Zeile. - `visible` (boolean; Standard true) — Zeigt das Widget an. - `enabled` (boolean; Standard true) — Erlaubt es, das Widget zu ändern. - `colors` (a list of colors (max 512)) — Die Farbfelder. - `onclick` (function(ev)) — Wird im Skript aufgerufen, wenn das Widget gedrückt wird, mit ev = { id }. Alles, was dadurch im Dokument geändert wird, ist ein Rückgängig-Schritt. Gibt zurück (table): Der Dialog, zum Verketten. #### `dlg:show(opts?)` — rein Öffnet den Dialog. Danach können keine Widgets mehr hinzugefügt werden; ändere sie mit dlg:modify. - `opts` (table, optional) - `wait` (boolean; Standard true) — true: Der Dialog ist modal (das Studio ist abgedunkelt und gesperrt), und das Skript hält hier an, bis er geschlossen wird; die zuvor gemachten Änderungen sind ein eigener Rückgängig-Schritt, der Rest des Skripts ein neuer. false: Der Dialog ist ein schwebendes Fenster; show kehrt sofort zurück, und das Skript bleibt am Leben, im Leerlauf, bis der Dialog geschlossen wird. Gibt zurück (table): Der Dialog, zum Verketten. #### `dlg:slider(opts?)` — rein Fügt einen Schieberegler hinzu. Sein Wert ist dlg.data. (eine Zahl). - `opts` (table, optional) - `id` (string) — Benennt das Widget: Sein Wert wird als dlg.data. gelesen, und es ist das Ziel von dlg:modify. Buchstaben, Ziffern und _ , beginnend mit einem Buchstaben; eindeutig im Dialog. - `label` (string) — Text links vom Widget; ein Widget mit label beginnt eine eigene Zeile. - `visible` (boolean; Standard true) — Zeigt das Widget an. - `enabled` (boolean; Standard true) — Erlaubt es, das Widget zu ändern. - `min` (number; Standard 0) — Kleinster Wert. - `max` (number; Standard 100) — Größter Wert. - `value` (number; Standard min) — Der Startwert. - `onchange` (function(ev)) — Wird im Skript jedes Mal aufgerufen, wenn der Wert geändert wird, mit ev = { id, value }. Eine Folge von Änderungen (Ziehen eines Schiebereglers) kommt unter Umständen nur als die letzte an. Alles, was dadurch im Dokument geändert wird, ist ein Rückgängig-Schritt. Gibt zurück (table): Der Dialog, zum Verketten. #### `plugin:newCommand(opts)` — rein Registriert einen Befehl, so wie es ein Aseprite-Plugin tut. Definiere eine globale Funktion init(plugin) und rufe dies darin auf: function init(plugin) plugin:newCommand{ id = "outline", title = "Thick Outline", group = "edit_fx", onclick = function() ... end } end. Installiere das Skript über Skripte > Skriptbefehle...: Sein init läuft einmal, ohne Zugriff auf das Dokument, um zu sehen, was es registriert, und die Befehle erscheinen dann in den Menüs, der Befehlspalette und dem Editor für Tastenkürzel (wo man ihnen ein Kürzel geben kann). Einen davon auszuführen startet das Skript (sein oberster Block läuft erneut, dann init, dann das onclick des Befehls), halte den obersten Block also bei Definitionen. Bis zu 32 Befehle pro Skript. - `opts` (table) - `id` (string) — Die ID des Befehls innerhalb des Skripts: ein Buchstabe, dann Buchstaben, Ziffern, _ oder - (max. 48). Seine Aktions-ID, die für Tastenkürzel verwendet wird, ist script... - `title` (string) — Der Text im Menü und in der Befehlspalette (max. 60 Zeichen). - `group` (string) — Wo der Befehl in den Menüs landet: file, file_import, edit, edit_transform, edit_fx, edit_adjustments, sprite, layer, frame, select oder view. Ohne Angabe landet er unter Skripte > . Ein Befehl in einem eingebauten Menü wird mit dem Namen des Skripts angezeigt. - `onclick` (function(ev)) — Wird im Skript aufgerufen, wenn der Befehl läuft. Alles, was dadurch im Dokument geändert wird, ist ein Rückgängig-Schritt. Gibt nichts zurück.