Formulaires de configuration

Un script peut déclarer un petit formulaire affiché avant son exécution. Ce que l'utilisateur remplit arrive sous la forme de la table app.config, indexée par l'id de chaque champ. Les champs sont de simples données (un script ne décrit jamais l'interface) : l'éditeur les affiche et les valide. Les couleurs, les pinceaux et les palettes sont la façon dont un script demande quelque chose issu des affaires de l'utilisateur : le moteur ne lit jamais ses bibliothèques, donc un script reçoit exactement ce qui est choisi.

• number — Un champ numérique. En Lua : number. Options : default (La valeur de départ.); min (La plus petite valeur autorisée.); max (La plus grande valeur autorisée.); optional (Autorise à le laisser vide.); randomMin / randomMax (La plage dans laquelle Aléatoire tire, à l'intérieur de min..max (min..max par défaut ; sans les deux bornes, Aléatoire n'y touche pas). Des nombres entiers quand les bornes et la valeur par défaut le sont.); randomize (false conserve la valeur quand l'utilisateur rend le formulaire aléatoire.).
• text — Une ligne de texte. En Lua : string. Options : default (Le texte de départ.); optional (Autorise à le laisser vide.).
• checkbox — Un interrupteur activé/désactivé. En Lua : boolean. Options : default (Indique s'il démarre coché.); randomize (false conserve la valeur quand l'utilisateur rend le formulaire aléatoire.).
• select — Un choix dans une liste fixe. En Lua : string (la valeur de l'option choisie). Options : options (Les choix, chacun sous la forme { value, label }.); default (La valeur sélectionnée au départ.); randomize (false conserve le choix quand l'utilisateur rend le formulaire aléatoire.).
• color — Une couleur, choisie avec le sélecteur de couleur de l'éditeur, avec la palette du sprite et les couleurs récentes à portée d'un clic. Donne à chaque rôle son propre champ (feuille claire, feuille sombre, écorce...) et l'utilisateur les choisit tous. En Lua : string, "#rrggbb" (ou "#rrggbbaa" avec alpha) : acceptée directement partout où une couleur est attendue. Options : default (La couleur de départ, "#rrggbb" ou "#rrggbbaa" (noir si omise).); randomize (true permet à Aléatoire de tirer aussi une couleur (l'alpha est conservé). Désactivé par défaut : les couleurs de la plupart des scripts sont soigneusement choisies.).
• brush — Un des pinceaux enregistrés de l'utilisateur, choisi dans sa bibliothèque de pinceaux. En Lua : table { name, width, height, mask } : passe-la à app.defineBrush ; absente quand le champ est facultatif et laissé vide. Options : optional (Autorise à le laisser vide (app.config.<id> vaut alors nil).).
• palette — Une des palettes enregistrées de l'utilisateur, choisie dans sa bibliothèque de palettes. En Lua : liste de chaînes "#rrggbb" (ou "#rrggbbaa") : passe-la à app.setPalette, ou pioche dedans avec du calcul de couleurs ; absente quand le champ est facultatif et laissé vide. Options : optional (Autorise à le laisser vide (app.config.<id> vaut alors nil).).

Exemple de formulaire (JSON) et du script qui l'utilise :

{
  "fields": [
    {
      "id": "leafLight",
      "type": "color",
      "label": "Leaf (light)",
      "default": "#6cc24a"
    },
    {
      "id": "leafMid",
      "type": "color",
      "label": "Leaf (mid)",
      "default": "#3a8f4a"
    },
    {
      "id": "leafDark",
      "type": "color",
      "label": "Leaf (dark)",
      "default": "#23603a"
    },
    {
      "id": "barkLight",
      "type": "color",
      "label": "Bark (light)",
      "default": "#8a5a35"
    },
    {
      "id": "barkDark",
      "type": "color",
      "label": "Bark (dark)",
      "default": "#5a3a22"
    },
    {
      "id": "stamp",
      "type": "brush",
      "label": "Leaf brush",
      "optional": true
    }
  ]
}

local layer, frame = app.getActiveLayerId(), app.getActiveFrameId()
local c = app.config

-- trunk: two bark colors the user chose
app.drawRectangle(layer, frame, 14, 20, 17, 31, { color = c.barkDark, fill = "filled" })
app.drawRectangle(layer, frame, 14, 20, 15, 31, { color = c.barkLight, fill = "filled" })

-- canopy: three leaf colors, with the user's own brush if they picked one
if c.stamp then app.defineBrush("leaf", c.stamp) end
for i, color in ipairs({ c.leafDark, c.leafMid, c.leafLight }) do
  app.drawStroke(layer, frame, { { 8, 18 - i * 4 }, { 24, 18 - i * 4 } },
    { color = color, brush = c.stamp and "leaf" or nil, brushSize = 4 })
end

Ramification

Tout champ peut porter un when, { "<earlier field id>": [values] }, et ne s'affiche alors que tant que chaque select nommé contient l'une de ces valeurs d'option (ou que la checkbox vaut true/false) et qu'il est lui-même affiché. Les conditions ne regardent que les select et checkbox précédents, donc elles s'enchaînent à n'importe quelle profondeur : change la racine et toute sa branche se masque. Un champ masqué est absent de app.config, donc le script retombe sur sa propre valeur par défaut : lis chaque champ comme facultatif.

{
  "fields": [
    {
      "id": "kind",
      "type": "select",
      "label": "Kind",
      "options": [
        {
          "value": "broadleaf",
          "label": "Broadleaf"
        },
        {
          "value": "conifer",
          "label": "Conifer"
        }
      ],
      "default": "broadleaf"
    },
    {
      "id": "crown",
      "type": "select",
      "label": "Crown",
      "options": [
        {
          "value": "round",
          "label": "Round"
        },
        {
          "value": "weeping",
          "label": "Weeping"
        }
      ],
      "when": {
        "kind": [
          "broadleaf"
        ]
      }
    },
    {
      "id": "droop",
      "type": "number",
      "label": "Droop",
      "min": 0,
      "max": 100,
      "randomMin": 20,
      "randomMax": 80,
      "when": {
        "crown": [
          "weeping"
        ]
      }
    },
    {
      "id": "tiers",
      "type": "number",
      "label": "Tiers",
      "min": 2,
      "max": 12,
      "when": {
        "kind": [
          "conifer"
        ]
      }
    },
    {
      "id": "newLayer",
      "type": "checkbox",
      "label": "Draw on a new layer",
      "randomize": false
    }
  ]
}

Aléatoire

Chaque formulaire a un bouton Aléatoire. Il tire chaque nombre dans randomMin..randomMax (min..max par défaut ; un nombre sans les deux bornes est conservé), choisit une option de n'importe quel select et inverse les checkbox ; les couleurs ne sont tirées qu'avec randomize: true, et les textes, pinceaux et palettes ne sont jamais touchés. Règle randomMin/randomMax sur la plage qui reste belle, et randomize: false sur les réglages qui ne concernent pas l'illustration (nouveau calque, respect de la sélection...).

En Markdown : config-forms.md.