Dialogs and commands

Dialog(opts) — pure

Creates a dialog: a window the script draws in the editor, built with the dlg: methods and opened with dlg:show. The window always names the script and is marked "script" so it cannot pass for part of the editor, and everything a script puts in it is plain text. Add widgets with the dlg: methods (they chain), then dlg:show{ wait = false } for a window that stays open while the user keeps drawing, or dlg:show{ wait = true } (the default) to stop the script until it is closed. A script with a dialog open stays alive, idle; stopping the script closes it. Callbacks (onclick, onchange, onclose) run in the script; each one is a single undo step. At most 4 dialogs can be open and 10 opened per 10 seconds; at most 100 widgets each.

• opts (table) — A title string, or a table. Dialog("Title") is Dialog{ title = "Title" }.
  • title (string) — Shown at the top of the dialog (max 80 characters). Text only.
  • onclose (function(ev)) — Called, in the script, when the user closes the dialog.

Returns (table): The dialog. dlg.data is a table of the current values of the widgets that have an id.

dlg:button(opts?) — pure

Adds a button. Without an onclick, pressing it closes the dialog and sets dlg.data.<id> to true (so after dlg:show{ wait = true } you can tell which button closed it).

• opts (table, optional)
  • id (string) — Names the widget: its value is read as dlg.data.<id> and it is the target of dlg:modify. Letters, digits and _ , starting with a letter; unique in the dialog.
  • label (string) — Text shown to the left of the widget; a widget with a label starts its own row.
  • visible (boolean; default true) — Show the widget.
  • enabled (boolean; default true) — Let the user change it.
  • text (string) — The button's text.
  • focus (boolean; default false) — Start with the keyboard focus here.
  • onclick (function(ev)) — Called, in the script, when the user presses it, with ev = { id }. Everything it changes in the document is one undo step.

Returns (table): The dialog, for chaining.

dlg:check(opts?) — pure

Adds a checkbox. Its value is dlg.data.<id> (a boolean).

• opts (table, optional)
  • id (string) — Names the widget: its value is read as dlg.data.<id> and it is the target of dlg:modify. Letters, digits and _ , starting with a letter; unique in the dialog.
  • label (string) — Text shown to the left of the widget; a widget with a label starts its own row.
  • visible (boolean; default true) — Show the widget.
  • enabled (boolean; default true) — Let the user change it.
  • text (string) — The text next to the box.
  • selected (boolean; default false) — Start checked.
  • onchange (function(ev)) — Called, in the script, each time the user changes the value, with ev = { id, value }. A burst of changes (dragging a slider) may arrive as just the last one. Everything it changes in the document is one undo step.

Returns (table): The dialog, for chaining.

dlg:close() — pure

Closes the dialog (from the script, e.g. in a button's onclick). A script ends when its main chunk is done and no dialog is open.

Returns (table): The dialog, for chaining.

dlg:color(opts?) — pure

Adds a color field that opens the full color picker, with the sprite's palette and recent colors. Its value is dlg.data.<id> (a "#rrggbb" or "#rrggbbaa" string).

• opts (table, optional)
  • id (string) — Names the widget: its value is read as dlg.data.<id> and it is the target of dlg:modify. Letters, digits and _ , starting with a letter; unique in the dialog.
  • label (string) — Text shown to the left of the widget; a widget with a label starts its own row.
  • visible (boolean; default true) — Show the widget.
  • enabled (boolean; default true) — Let the user change it.
  • color (color ("#rgb", "#rrggbb[aa]" or { r, g, b, a }); default "#000000") — The starting color.
  • onchange (function(ev)) — Called, in the script, each time the user changes the value, with ev = { id, value }. A burst of changes (dragging a slider) may arrive as just the last one. Everything it changes in the document is one undo step.

Returns (table): The dialog, for chaining.

dlg:combobox(opts?) — pure

Adds a drop-down list. Its value is dlg.data.<id> (the chosen option's text).

• opts (table, optional)
  • id (string) — Names the widget: its value is read as dlg.data.<id> and it is the target of dlg:modify. Letters, digits and _ , starting with a letter; unique in the dialog.
  • label (string) — Text shown to the left of the widget; a widget with a label starts its own row.
  • visible (boolean; default true) — Show the widget.
  • enabled (boolean; default true) — Let the user change it.
  • options (a list of strings (max 200)) — The choices.
  • option (string; default the first option) — The starting choice.
  • onchange (function(ev)) — Called, in the script, each time the user changes the value, with ev = { id, value }. A burst of changes (dragging a slider) may arrive as just the last one. Everything it changes in the document is one undo step.

Returns (table): The dialog, for chaining.

dlg:entry(opts?) — pure

Adds a text box. Its value is dlg.data.<id> (a string).

• opts (table, optional)
  • id (string) — Names the widget: its value is read as dlg.data.<id> and it is the target of dlg:modify. Letters, digits and _ , starting with a letter; unique in the dialog.
  • label (string) — Text shown to the left of the widget; a widget with a label starts its own row.
  • visible (boolean; default true) — Show the widget.
  • enabled (boolean; default true) — Let the user change it.
  • text (string; default "") — The starting text.
  • focus (boolean; default false) — Start with the keyboard focus here.
  • onchange (function(ev)) — Called, in the script, each time the user changes the value, with ev = { id, value }. A burst of changes (dragging a slider) may arrive as just the last one. Everything it changes in the document is one undo step.

Returns (table): The dialog, for chaining.

dlg:file(opts?) — pure

Adds a file picker (open only: the browser's file chooser). dlg.data.<id> is the chosen file's name; the file's content is reached through ev.file in onchange (and dlg.files.<id>): { name, size, type, text }, where text is only set for small text files (up to 256 KiB). Images and other binary files are not readable.

• opts (table, optional)
  • id (string) — Names the widget: its value is read as dlg.data.<id> and it is the target of dlg:modify. Letters, digits and _ , starting with a letter; unique in the dialog.
  • label (string) — Text shown to the left of the widget; a widget with a label starts its own row.
  • visible (boolean; default true) — Show the widget.
  • enabled (boolean; default true) — Let the user change it.
  • filename (string) — A name to show before a file is chosen.
  • title (string; default "Choose file...") — The picker button's text.
  • filetypes (a list of extensions without the dot, e.g. { "png", "gpl" }) — Files the chooser offers.
  • onchange (function(ev)) — Called, in the script, each time the user changes the value, with ev = { id, value }. A burst of changes (dragging a slider) may arrive as just the last one. Everything it changes in the document is one undo step.

Returns (table): The dialog, for chaining.

dlg:label(opts?) — pure

Adds a line of text (several with \n, up to 20 lines).

• opts (table, optional)
  • id (string) — Names the widget: its value is read as dlg.data.<id> and it is the target of dlg:modify. Letters, digits and _ , starting with a letter; unique in the dialog.
  • label (string) — Text shown to the left of the widget; a widget with a label starts its own row.
  • visible (boolean; default true) — Show the widget.
  • enabled (boolean; default true) — Let the user change it.
  • text (string) — The text.

Returns (table): The dialog, for chaining.

dlg:modify(opts?) — pure

Changes a widget (or the dialog's title) while the dialog is open or before it is shown. Values are checked and clamped, and dlg.data follows. Assigning dlg.data = { id = value, ... } does the same for several values.

• opts (table, optional)
  • id (string) — The widget to change. Without it, the dialog itself (only title).
  • title (string) — The dialog's title (with no id), or a file widget's button text.
  • text (string) — A new text (an entry's or number's value; a label's, check's, radio's or button's text).
  • value (a number, string or boolean to match the widget) — A new value of any value widget (a slider's number, ...).
  • selected (boolean) — A new state for a check or radio.
  • option (string) — A new choice for a combobox.
  • options (a list of strings) — New choices for a combobox.
  • color (color ("#rgb", "#rrggbb[aa]" or { r, g, b, a })) — A new color for a color widget.
  • colors (a list of colors) — New swatches for shades.
  • min (number) — A new smallest value (number, slider).
  • max (number) — A new largest value (number, slider).
  • label (string) — A new label.
  • visible (boolean) — Show or hide the widget.
  • enabled (boolean) — Enable or disable the widget.

Returns (table): The dialog, for chaining.

dlg:newrow() — pure

Starts a new row: widgets added next go below instead of beside the previous one.

Returns (table): The dialog, for chaining.

dlg:number(opts?) — pure

Adds a number box. Its value is dlg.data.<id> (a number).

• opts (table, optional)
  • id (string) — Names the widget: its value is read as dlg.data.<id> and it is the target of dlg:modify. Letters, digits and _ , starting with a letter; unique in the dialog.
  • label (string) — Text shown to the left of the widget; a widget with a label starts its own row.
  • visible (boolean; default true) — Show the widget.
  • enabled (boolean; default true) — Let the user change it.
  • text (number; default 0) — The starting value.
  • min (number) — Smallest value.
  • max (number) — Largest value.
  • decimals (integer 0–6; default 0) — Decimal places kept.
  • onchange (function(ev)) — Called, in the script, each time the user changes the value, with ev = { id, value }. A burst of changes (dragging a slider) may arrive as just the last one. Everything it changes in the document is one undo step.

Returns (table): The dialog, for chaining.

dlg:radio(opts?) — pure

Adds a radio button. Radio buttons next to each other in a row form a group where one is selected; each one's value is dlg.data.<id> (a boolean).

• opts (table, optional)
  • id (string) — Names the widget: its value is read as dlg.data.<id> and it is the target of dlg:modify. Letters, digits and _ , starting with a letter; unique in the dialog.
  • label (string) — Text shown to the left of the widget; a widget with a label starts its own row.
  • visible (boolean; default true) — Show the widget.
  • enabled (boolean; default true) — Let the user change it.
  • text (string) — The text next to the button.
  • selected (boolean; default false) — Start selected.
  • onchange (function(ev)) — Called, in the script, each time the user changes the value, with ev = { id, value }. A burst of changes (dragging a slider) may arrive as just the last one. Everything it changes in the document is one undo step.

Returns (table): The dialog, for chaining.

dlg:separator(opts?) — pure

Adds a horizontal line, with optional text, on its own row.

• opts (table, optional)
  • id (string) — Names the widget: its value is read as dlg.data.<id> and it is the target of dlg:modify. Letters, digits and _ , starting with a letter; unique in the dialog.
  • label (string) — Text shown to the left of the widget; a widget with a label starts its own row.
  • visible (boolean; default true) — Show the widget.
  • enabled (boolean; default true) — Let the user change it.
  • text (string) — Text shown beside the line.

Returns (table): The dialog, for chaining.

dlg:shades(opts?) — pure

Adds a row of color swatches to pick from. Pressing one calls onclick with ev = { id, color }.

• opts (table, optional)
  • id (string) — Names the widget: its value is read as dlg.data.<id> and it is the target of dlg:modify. Letters, digits and _ , starting with a letter; unique in the dialog.
  • label (string) — Text shown to the left of the widget; a widget with a label starts its own row.
  • visible (boolean; default true) — Show the widget.
  • enabled (boolean; default true) — Let the user change it.
  • colors (a list of colors (max 512)) — The swatches.
  • onclick (function(ev)) — Called, in the script, when the user presses it, with ev = { id }. Everything it changes in the document is one undo step.

Returns (table): The dialog, for chaining.

dlg:show(opts?) — pure

Opens the dialog. Widgets cannot be added afterwards; change them with dlg:modify.

• opts (table, optional)
  • wait (boolean; default true) — true: the dialog is modal (the studio is dimmed and locked) and the script stops here until it is closed; the changes made before are their own undo step, the rest of the script a new one. false: the dialog is a floating window; show returns at once and the script stays alive, idle, until the dialog is closed.

Returns (table): The dialog, for chaining.

dlg:slider(opts?) — pure

Adds a slider. Its value is dlg.data.<id> (a number).

• opts (table, optional)
  • id (string) — Names the widget: its value is read as dlg.data.<id> and it is the target of dlg:modify. Letters, digits and _ , starting with a letter; unique in the dialog.
  • label (string) — Text shown to the left of the widget; a widget with a label starts its own row.
  • visible (boolean; default true) — Show the widget.
  • enabled (boolean; default true) — Let the user change it.
  • min (number; default 0) — Smallest value.
  • max (number; default 100) — Largest value.
  • value (number; default min) — The starting value.
  • onchange (function(ev)) — Called, in the script, each time the user changes the value, with ev = { id, value }. A burst of changes (dragging a slider) may arrive as just the last one. Everything it changes in the document is one undo step.

Returns (table): The dialog, for chaining.

plugin:newCommand(opts) — pure

Registers a command, the way an Aseprite plugin does. Define a global function init(plugin) and call this inside it: function init(plugin) plugin:newCommand{ id = "outline", title = "Thick Outline", group = "edit_fx", onclick = function() ... end } end. Install the script from Scripts > Script Commands...: its init runs once, with no access to the document, to see what it registers, and the commands then appear in the menus, the command palette and the Keyboard Shortcuts editor (where they can be given a shortcut). Running one starts the script (its top level runs again, then init, then the command's onclick), so keep the top level to definitions. Up to 32 commands per script.

• opts (table)
  • id (string) — The command's id within the script: a letter, then letters, digits, _ or - (max 48). Its action id, used for keyboard shortcuts, is script.<scriptId>.<id>.
  • title (string) — The menu and command palette text (max 60 characters).
  • group (string) — Where the command goes in the menus: file, file_import, edit, edit_transform, edit_fx, edit_adjustments, sprite, layer, frame, select or view. Without one, it goes under Scripts > <script name>. A command in a built-in menu is shown with the script's name.
  • onclick (function(ev)) — Called, in the script, when the command runs. Everything it changes in the document is one undo step.

Returns nothing.

As Markdown: dialogs.md.