# API di scripting Lua di pxstud.io — Pennelli

> Parte del riferimento di scripting Lua di pxstud.io, la cui panoramica (https://pxstud.io/it/docs/scripting.md) ne spiega le convenzioni. I gruppi di opzioni e i tipi a cui rimanda sono in https://pxstud.io/it/docs/scripting/option-groups.md e https://pxstud.io/it/docs/scripting/types.md. Tutto in un unico file (in inglese): https://pxstud.io/llms-full.txt. L'indice dell'intero sito (in inglese): https://pxstud.io/llms.txt.

### Pennelli
Definisci i tuoi pennelli con un nome, poi dipingi con loro. Esistono solo nel motore per la durata della sessione: non fanno parte del documento, non si possono annullare, non vengono salvati e sono separati dalla libreria dei pennelli dell'editor.

#### `app.brushFromSelection(name)` — modifica
Definisce un pennello personalizzato a partire dalla forma della selezione corrente (i pixel selezionati dipingono). Genera un errore se non c'è nessuna selezione o se la selezione è più grande di 64 x 64.

- `name` (string) — Il nome da dare al pennello.

Restituisce (table): { width, height } del pennello.

#### `app.defineBrush(name, brush)` — modifica
Definisce un pennello personalizzato con un nome, da usare come `brush = "name"` nei comandi di disegno o con app.useBrush. I pennelli esistono solo nel motore per la durata della sessione: non fanno parte del documento, non si possono annullare e non vengono salvati né aggiunti alla libreria dei pennelli dell'editor.

- `name` (string) — Da 1 a 64 caratteri. Definire un nome già esistente lo sostituisce.
- `brush` (table) — Passa `rows` (leggibile) oppure `width`, `height` e `mask`. Esempio: { rows = { ".#.", "###", ".#." } } è un segno più.
  - `name` (string) — Ignorato: c'è solo perché un pennello preso da un campo di un modulo di configurazione (app.config.<id>) possa essere passato così com'è.
  - `rows` (list of strings, one per row; ".", " " and "0" are empty, anything else paints) — Il pennello come testo, fino a 64 x 64. Le righe corte vengono completate con pixel vuoti.
  - `width` (integer 1–64) — Larghezza in pixel (con `mask`).
  - `height` (integer 1–64) — Altezza in pixel (con `mask`).
  - `mask` (flat row-major list of width*height 0/1 values) — Il pennello come numeri (con `width` e `height`).

Restituisce (table): { width, height } del pennello.

#### `app.getBrush(name)` — legge
Un pennello personalizzato per nome, come { name, width, height, mask (elenco piatto di 0/1), rows (lo stesso come stringhe di # e .) }, oppure nil se quel pennello non esiste.

- `name` (string)

Restituisce (table): Tabella del pennello o nil.

#### `app.getBrushes()` — legge
I pennelli personalizzati definiti con app.defineBrush, nell'ordine di definizione, come { name, width, height }. I pennelli integrati (circle, square, horizontal) non sono elencati.

Restituisce (table): Array di { name, width, height }.

#### `app.removeBrush(name)` — modifica
Elimina un pennello personalizzato definito con app.defineBrush. I comandi di disegno già eseguiti mantengono il pennello che hanno usato.

- `name` (string)

Restituisce (boolean): true se il pennello esisteva.

#### `app.useBrush(name)` — modifica
Imposta un pennello personalizzato come pennello corrente (il brushShape = "custom" e il customBrush del contesto di modifica), così i comandi di disegno senza l'opzione `brush` lo usano: lo mostra anche la barra degli strumenti dell'editor. Genera un errore se il nome è sconosciuto.

- `name` (string) — Un pennello definito con app.defineBrush.

Non restituisce nulla.