# API de scripting Lua de pxstud.io — Diálogos y comandos > Parte de la referencia de scripting Lua de pxstud.io, cuya introducción (https://pxstud.io/es/docs/scripting.md) explica sus convenciones. Los grupos de opciones y los tipos a los que remite están en https://pxstud.io/es/docs/scripting/option-groups.md y https://pxstud.io/es/docs/scripting/types.md. Todo en un solo archivo (en inglés): https://pxstud.io/llms-full.txt. El índice de todo el sitio (en inglés): https://pxstud.io/llms.txt. ### Diálogos y comandos Interfaz de scripts, modelada sobre la de Aseprite: Dialog{ title = ... } construye una ventana a partir de widgets (label, entry, number, slider, check, radio, combobox, color, shades, button, separator, file) y plugin:newCommand añade comandos a los menús, a la paleta de comandos y al editor de Atajos de teclado. El editor dibuja la ventana, solo con texto, con una barra de título que nombra el script y lo marca como "script". Los callbacks (onclick, onchange, onclose) se ejecutan en el script, de uno en uno, cada uno como un solo paso de deshacer; un script con un diálogo abierto sigue vivo, inactivo, mientras el usuario sigue dibujando, y detenerlo cierra sus diálogos. No se admiten: widgets de lienzo ni dlg:repaint. #### `Dialog(opts)` — pura Crea un diálogo: una ventana que el script dibuja en el editor, construida con los métodos dlg: y abierta con dlg:show. La ventana siempre nombra el script y está marcada como "script" para que no se pueda confundir con una parte del editor, y todo lo que un script pone en ella es texto simple. Añade widgets con los métodos dlg: (se encadenan), y luego dlg:show{ wait = false } para una ventana que sigue abierta mientras el usuario sigue dibujando, o dlg:show{ wait = true } (el valor predeterminado) para detener el script hasta que se cierre. Un script con un diálogo abierto sigue vivo, inactivo; detener el script lo cierra. Los callbacks (onclick, onchange, onclose) se ejecutan en el script; cada uno es un solo paso de deshacer. Se pueden tener abiertos como máximo 4 diálogos y abrir 10 cada 10 segundos; como máximo 100 widgets cada uno. - `opts` (table) — Una cadena de título, o una tabla. Dialog("Title") es Dialog{ title = "Title" }. - `title` (string) — Se muestra en la parte superior del diálogo (máx. 80 caracteres). Solo texto. - `onclose` (function(ev)) — Se llama, en el script, cuando el usuario cierra el diálogo. Devuelve (table): El diálogo. dlg.data es una tabla con los valores actuales de los widgets que tienen un id. #### `dlg:button(opts?)` — pura Añade un botón. Sin onclick, al pulsarlo cierra el diálogo y establece dlg.data. en true (así, tras dlg:show{ wait = true } puedes saber qué botón lo cerró). - `opts` (table, opcional) - `id` (string) — Da nombre al widget: su valor se lee como dlg.data. y es el destino de dlg:modify. Letras, dígitos y _ , empezando por una letra; único en el diálogo. - `label` (string) — Texto que se muestra a la izquierda del widget; un widget con etiqueta empieza su propia fila. - `visible` (boolean; predeterminado true) — Muestra el widget. - `enabled` (boolean; predeterminado true) — Permite que el usuario lo cambie. - `text` (string) — El texto del botón. - `focus` (boolean; predeterminado false) — Empieza con el foco del teclado aquí. - `onclick` (function(ev)) — Se llama, en el script, cuando el usuario lo pulsa, con ev = { id }. Todo lo que cambia en el documento es un solo paso de deshacer. Devuelve (table): El diálogo, para encadenar. #### `dlg:check(opts?)` — pura Añade una casilla de verificación. Su valor es dlg.data. (un booleano). - `opts` (table, opcional) - `id` (string) — Da nombre al widget: su valor se lee como dlg.data. y es el destino de dlg:modify. Letras, dígitos y _ , empezando por una letra; único en el diálogo. - `label` (string) — Texto que se muestra a la izquierda del widget; un widget con etiqueta empieza su propia fila. - `visible` (boolean; predeterminado true) — Muestra el widget. - `enabled` (boolean; predeterminado true) — Permite que el usuario lo cambie. - `text` (string) — El texto junto a la casilla. - `selected` (boolean; predeterminado false) — Empieza marcada. - `onchange` (function(ev)) — Se llama, en el script, cada vez que el usuario cambia el valor, con ev = { id, value }. Una ráfaga de cambios (al arrastrar un control deslizante) puede llegar solo como el último. Todo lo que cambia en el documento es un solo paso de deshacer. Devuelve (table): El diálogo, para encadenar. #### `dlg:close()` — pura Cierra el diálogo (desde el script, p. ej. en el onclick de un botón). Un script termina cuando su fragmento principal acaba y no queda ningún diálogo abierto. Devuelve (table): El diálogo, para encadenar. #### `dlg:color(opts?)` — pura Añade un campo de color que abre el selector de color completo, con la paleta del sprite y los colores recientes. Su valor es dlg.data. (una cadena "#rrggbb" o "#rrggbbaa"). - `opts` (table, opcional) - `id` (string) — Da nombre al widget: su valor se lee como dlg.data. y es el destino de dlg:modify. Letras, dígitos y _ , empezando por una letra; único en el diálogo. - `label` (string) — Texto que se muestra a la izquierda del widget; un widget con etiqueta empieza su propia fila. - `visible` (boolean; predeterminado true) — Muestra el widget. - `enabled` (boolean; predeterminado true) — Permite que el usuario lo cambie. - `color` (color ("#rgb", "#rrggbb[aa]" or { r, g, b, a }); predeterminado "#000000") — El color inicial. - `onchange` (function(ev)) — Se llama, en el script, cada vez que el usuario cambia el valor, con ev = { id, value }. Una ráfaga de cambios (al arrastrar un control deslizante) puede llegar solo como el último. Todo lo que cambia en el documento es un solo paso de deshacer. Devuelve (table): El diálogo, para encadenar. #### `dlg:combobox(opts?)` — pura Añade una lista desplegable. Su valor es dlg.data. (el texto de la opción elegida). - `opts` (table, opcional) - `id` (string) — Da nombre al widget: su valor se lee como dlg.data. y es el destino de dlg:modify. Letras, dígitos y _ , empezando por una letra; único en el diálogo. - `label` (string) — Texto que se muestra a la izquierda del widget; un widget con etiqueta empieza su propia fila. - `visible` (boolean; predeterminado true) — Muestra el widget. - `enabled` (boolean; predeterminado true) — Permite que el usuario lo cambie. - `options` (a list of strings (max 200)) — Las opciones. - `option` (string; predeterminado the first option) — La opción inicial. - `onchange` (function(ev)) — Se llama, en el script, cada vez que el usuario cambia el valor, con ev = { id, value }. Una ráfaga de cambios (al arrastrar un control deslizante) puede llegar solo como el último. Todo lo que cambia en el documento es un solo paso de deshacer. Devuelve (table): El diálogo, para encadenar. #### `dlg:entry(opts?)` — pura Añade un cuadro de texto. Su valor es dlg.data. (una cadena). - `opts` (table, opcional) - `id` (string) — Da nombre al widget: su valor se lee como dlg.data. y es el destino de dlg:modify. Letras, dígitos y _ , empezando por una letra; único en el diálogo. - `label` (string) — Texto que se muestra a la izquierda del widget; un widget con etiqueta empieza su propia fila. - `visible` (boolean; predeterminado true) — Muestra el widget. - `enabled` (boolean; predeterminado true) — Permite que el usuario lo cambie. - `text` (string; predeterminado "") — El texto inicial. - `focus` (boolean; predeterminado false) — Empieza con el foco del teclado aquí. - `onchange` (function(ev)) — Se llama, en el script, cada vez que el usuario cambia el valor, con ev = { id, value }. Una ráfaga de cambios (al arrastrar un control deslizante) puede llegar solo como el último. Todo lo que cambia en el documento es un solo paso de deshacer. Devuelve (table): El diálogo, para encadenar. #### `dlg:file(opts?)` — pura Añade un selector de archivo (solo para abrir: el selector de archivos del navegador). dlg.data. es el nombre del archivo elegido; se accede al contenido del archivo mediante ev.file en onchange (y dlg.files.): { name, size, type, text }, donde text solo se establece para archivos de texto pequeños (hasta 256 KiB). Las imágenes y otros archivos binarios no se pueden leer. - `opts` (table, opcional) - `id` (string) — Da nombre al widget: su valor se lee como dlg.data. y es el destino de dlg:modify. Letras, dígitos y _ , empezando por una letra; único en el diálogo. - `label` (string) — Texto que se muestra a la izquierda del widget; un widget con etiqueta empieza su propia fila. - `visible` (boolean; predeterminado true) — Muestra el widget. - `enabled` (boolean; predeterminado true) — Permite que el usuario lo cambie. - `filename` (string) — Un nombre que se muestra antes de elegir un archivo. - `title` (string; predeterminado "Choose file...") — El texto del botón del selector. - `filetypes` (a list of extensions without the dot, e.g. { "png", "gpl" }) — Los archivos que ofrece el selector. - `onchange` (function(ev)) — Se llama, en el script, cada vez que el usuario cambia el valor, con ev = { id, value }. Una ráfaga de cambios (al arrastrar un control deslizante) puede llegar solo como el último. Todo lo que cambia en el documento es un solo paso de deshacer. Devuelve (table): El diálogo, para encadenar. #### `dlg:label(opts?)` — pura Añade una línea de texto (varias con \n, hasta 20 líneas). - `opts` (table, opcional) - `id` (string) — Da nombre al widget: su valor se lee como dlg.data. y es el destino de dlg:modify. Letras, dígitos y _ , empezando por una letra; único en el diálogo. - `label` (string) — Texto que se muestra a la izquierda del widget; un widget con etiqueta empieza su propia fila. - `visible` (boolean; predeterminado true) — Muestra el widget. - `enabled` (boolean; predeterminado true) — Permite que el usuario lo cambie. - `text` (string) — El texto. Devuelve (table): El diálogo, para encadenar. #### `dlg:modify(opts?)` — pura Cambia un widget (o el título del diálogo) mientras el diálogo está abierto o antes de mostrarlo. Los valores se comprueban y se limitan, y dlg.data los sigue. Asignar dlg.data = { id = value, ... } hace lo mismo para varios valores. - `opts` (table, opcional) - `id` (string) — El widget que se cambia. Sin él, el propio diálogo (solo title). - `title` (string) — El título del diálogo (sin id), o el texto del botón de un widget file. - `text` (string) — Un texto nuevo (el valor de un entry o number; el texto de un label, check, radio o button). - `value` (a number, string or boolean to match the widget) — Un valor nuevo de cualquier widget de valor (el número de un slider, ...). - `selected` (boolean) — Un estado nuevo para un check o radio. - `option` (string) — Una opción nueva para un combobox. - `options` (a list of strings) — Opciones nuevas para un combobox. - `color` (color ("#rgb", "#rrggbb[aa]" or { r, g, b, a })) — Un color nuevo para un widget color. - `colors` (a list of colors) — Muestras nuevas para shades. - `min` (number) — Un nuevo valor mínimo (number, slider). - `max` (number) — Un nuevo valor máximo (number, slider). - `label` (string) — Una etiqueta nueva. - `visible` (boolean) — Muestra u oculta el widget. - `enabled` (boolean) — Activa o desactiva el widget. Devuelve (table): El diálogo, para encadenar. #### `dlg:newrow()` — pura Empieza una fila nueva: los widgets que se añadan después van debajo en lugar de junto al anterior. Devuelve (table): El diálogo, para encadenar. #### `dlg:number(opts?)` — pura Añade un cuadro numérico. Su valor es dlg.data. (un número). - `opts` (table, opcional) - `id` (string) — Da nombre al widget: su valor se lee como dlg.data. y es el destino de dlg:modify. Letras, dígitos y _ , empezando por una letra; único en el diálogo. - `label` (string) — Texto que se muestra a la izquierda del widget; un widget con etiqueta empieza su propia fila. - `visible` (boolean; predeterminado true) — Muestra el widget. - `enabled` (boolean; predeterminado true) — Permite que el usuario lo cambie. - `text` (number; predeterminado 0) — El valor inicial. - `min` (number) — Valor mínimo. - `max` (number) — Valor máximo. - `decimals` (integer 0–6; predeterminado 0) — Posiciones decimales que se conservan. - `onchange` (function(ev)) — Se llama, en el script, cada vez que el usuario cambia el valor, con ev = { id, value }. Una ráfaga de cambios (al arrastrar un control deslizante) puede llegar solo como el último. Todo lo que cambia en el documento es un solo paso de deshacer. Devuelve (table): El diálogo, para encadenar. #### `dlg:radio(opts?)` — pura Añade un botón de opción. Los botones de opción contiguos en una fila forman un grupo en el que uno está seleccionado; el valor de cada uno es dlg.data. (un booleano). - `opts` (table, opcional) - `id` (string) — Da nombre al widget: su valor se lee como dlg.data. y es el destino de dlg:modify. Letras, dígitos y _ , empezando por una letra; único en el diálogo. - `label` (string) — Texto que se muestra a la izquierda del widget; un widget con etiqueta empieza su propia fila. - `visible` (boolean; predeterminado true) — Muestra el widget. - `enabled` (boolean; predeterminado true) — Permite que el usuario lo cambie. - `text` (string) — El texto junto al botón. - `selected` (boolean; predeterminado false) — Empieza seleccionado. - `onchange` (function(ev)) — Se llama, en el script, cada vez que el usuario cambia el valor, con ev = { id, value }. Una ráfaga de cambios (al arrastrar un control deslizante) puede llegar solo como el último. Todo lo que cambia en el documento es un solo paso de deshacer. Devuelve (table): El diálogo, para encadenar. #### `dlg:separator(opts?)` — pura Añade una línea horizontal, con texto opcional, en su propia fila. - `opts` (table, opcional) - `id` (string) — Da nombre al widget: su valor se lee como dlg.data. y es el destino de dlg:modify. Letras, dígitos y _ , empezando por una letra; único en el diálogo. - `label` (string) — Texto que se muestra a la izquierda del widget; un widget con etiqueta empieza su propia fila. - `visible` (boolean; predeterminado true) — Muestra el widget. - `enabled` (boolean; predeterminado true) — Permite que el usuario lo cambie. - `text` (string) — Texto que se muestra junto a la línea. Devuelve (table): El diálogo, para encadenar. #### `dlg:shades(opts?)` — pura Añade una fila de muestras de color para elegir. Al pulsar una se llama a onclick con ev = { id, color }. - `opts` (table, opcional) - `id` (string) — Da nombre al widget: su valor se lee como dlg.data. y es el destino de dlg:modify. Letras, dígitos y _ , empezando por una letra; único en el diálogo. - `label` (string) — Texto que se muestra a la izquierda del widget; un widget con etiqueta empieza su propia fila. - `visible` (boolean; predeterminado true) — Muestra el widget. - `enabled` (boolean; predeterminado true) — Permite que el usuario lo cambie. - `colors` (a list of colors (max 512)) — Las muestras. - `onclick` (function(ev)) — Se llama, en el script, cuando el usuario lo pulsa, con ev = { id }. Todo lo que cambia en el documento es un solo paso de deshacer. Devuelve (table): El diálogo, para encadenar. #### `dlg:show(opts?)` — pura Abre el diálogo. Después ya no se pueden añadir widgets; cámbialos con dlg:modify. - `opts` (table, opcional) - `wait` (boolean; predeterminado true) — true: el diálogo es modal (el estudio se atenúa y se bloquea) y el script se detiene aquí hasta que se cierre; los cambios hechos antes son un paso de deshacer propio, y el resto del script, uno nuevo. false: el diálogo es una ventana flotante; show vuelve de inmediato y el script sigue vivo, inactivo, hasta que se cierra el diálogo. Devuelve (table): El diálogo, para encadenar. #### `dlg:slider(opts?)` — pura Añade un control deslizante. Su valor es dlg.data. (un número). - `opts` (table, opcional) - `id` (string) — Da nombre al widget: su valor se lee como dlg.data. y es el destino de dlg:modify. Letras, dígitos y _ , empezando por una letra; único en el diálogo. - `label` (string) — Texto que se muestra a la izquierda del widget; un widget con etiqueta empieza su propia fila. - `visible` (boolean; predeterminado true) — Muestra el widget. - `enabled` (boolean; predeterminado true) — Permite que el usuario lo cambie. - `min` (number; predeterminado 0) — Valor mínimo. - `max` (number; predeterminado 100) — Valor máximo. - `value` (number; predeterminado min) — El valor inicial. - `onchange` (function(ev)) — Se llama, en el script, cada vez que el usuario cambia el valor, con ev = { id, value }. Una ráfaga de cambios (al arrastrar un control deslizante) puede llegar solo como el último. Todo lo que cambia en el documento es un solo paso de deshacer. Devuelve (table): El diálogo, para encadenar. #### `plugin:newCommand(opts)` — pura Registra un comando, a la manera de un plugin de Aseprite. Define una función global init(plugin) y llama a esto dentro de ella: function init(plugin) plugin:newCommand{ id = "outline", title = "Thick Outline", group = "edit_fx", onclick = function() ... end } end. Instala el script desde Scripts > Comandos de scripts...: su init se ejecuta una vez, sin acceso al documento, para ver qué registra, y los comandos aparecen entonces en los menús, en la paleta de comandos y en el editor de Atajos de teclado (donde se les puede asignar un atajo). Ejecutar uno inicia el script (su nivel superior se ejecuta de nuevo, luego init y luego el onclick del comando), así que deja en el nivel superior solo definiciones. Hasta 32 comandos por script. - `opts` (table) - `id` (string) — El id del comando dentro del script: una letra, y luego letras, dígitos, _ o - (máx. 48). Su id de acción, usado para los atajos de teclado, es script... - `title` (string) — El texto del menú y de la paleta de comandos (máx. 60 caracteres). - `group` (string) — Dónde va el comando en los menús: file, file_import, edit, edit_transform, edit_fx, edit_adjustments, sprite, layer, frame, select o view. Sin grupo, va en Scripts > . Un comando en un menú integrado se muestra con el nombre del script. - `onclick` (function(ev)) — Se llama, en el script, cuando el comando se ejecuta. Todo lo que cambia en el documento es un solo paso de deshacer. No devuelve nada.