3.4. Il primo script Script-Fu
| 3. Una guida sugli Script-Fu |

### 3.4. Il primo script Script-Fu

Serve una pausa? No? Bene, procediamo con la quarta lezione, il primo script Script-Fu.

#### 3.4.1. Creare uno script Text Box

Una delle operazioni più comuni che si intraprendono in GIMP è la creazione di un rettangolo con del testo per una pagina web, un logo o altro. Tuttavia quando si comincia non si sa quanto far grande l'immagine iniziale. Non si sa quanto spazio occuperà il testo con il font e la dimensione del font che si desidera.

Il maestro di Script-Fu (e lo studente) si accorgeranno subito che questo problema può facilmente essere risolto e automatizzato con Script-Fu.

Si creerà quindi uno script, intitolato Text Box, che crea un'immagine delle dimensioni corrette per contenere una linea di testo immessa dall'utente. Si consentirà inoltre all'utente di scegliere il font, la dimensione del font e il colore del testo.

#### 3.4.2. Modificare e memorizzare gli script

Fino ad ora si è lavorato nella finestra della console Script-Fu. Adesso si comincerà a modificare file testuali per gli script.

Dove tenere i propri script è una questione di preferenze personali. Se si ha accesso alla directory predefinita degli script di GIMP si possono tenere lì gli script. Tuttavia è preferibile mantenere i propri script in una propria directory personale per tenerli separati dagli script piazzati dall'installazione.

Nella directory `.gimp-2.6` che GIMP crea nella directory home dell'utente, si dovrebbe trovare una directory denominata `scripts`. GIMP controllerà automaticamente nella directory `.gimp-2.6` se esiste una directory `scripts` e aggiungerà gli scripts contenuti in questa directory al database di Script-Fu. Perciò è conveniente usare questa directory per memorizzare i propri script personali.

#### 3.4.3. Lo stretto necessario

Ogni script Script-Fu definisce almeno una funzione che è la funzione principale dello script. Questa è la funzione dove si fa il lavoro.

Ogni script deve registrarsi nel database delle procedure per poter risultare accessibile a GIMP.

Si definisca dapprima la funzione principale:

            (define (script-fu-text-box inText inFont inFontSize inTextColor))

Qui viene definita una nuova funzione denominata `script-fu-text-box` che riceve quattro parametri che poi corrisponderanno a del testo, ad un font, alla dimensione del font e al colore del testo. La funzione è al momento vuota e non fa nulla.

#### 3.4.4. Convenzioni per i nomi

Le convenzioni sui nomi di Scheme sembrano dare la preferenza a lettere minuscole con trattini, convenzione seguita nel dare il nome alla funzione. Tuttavia ci si è allontanati dalla convenzione con gli argomenti. Si sono preferiti nomi più descrittivi per argomenti e variabili e quindi si è aggiunto il prefisso "in" agli argomenti in modo da distinguerli rapidamente come argomenti passati allo script piuttosto che creati al suo interno. Si è usato il prefisso "the" per variabili definite all'interno dello script.

Fa parte di una convenzione di GIMP di denominare le funzioni degli script `script-fu-abc`, poiché quando vengono elencate nel database delle procedure sono tutte raggruppate sotto il prefisso script-fu. Ciò aiuta anche a distinguerle dai plug-in.

#### 3.4.5. Registrare la funzione

Reistrare ora la funzione in GIMP. Ciò si ottiene richiamando la funzione `script-fu-register`. Quando GIMP legge uno script, esegue questa funzione che registra lo script nel database delle procedure. Si può posizionare questa funzione in ogni parte dello script, ma di solito la si posiziona alla fine, dopo tutto il codice.

Ecco il listato per registrare questa funzione (si chiariranno a breve gli argomenti):

      (script-fu-register
        "script-fu-text-box"                        ;func name
        "Text Box"                                  ;menu label
        "Creates a simple text box, sized to fit\
          around the user's choice of text,\
          font, font size, and color."              ;description
        "Michael Terry"                             ;author
        "copyright 1997, Michael Terry;\
          2009, the GIMP Documentation Team"        ;copyright notice
        "October 27, 1997"                          ;date created
        ""                     ;image type that the script works on
        SF-STRING      "Text"          "Text Box"   ;a string variable
        SF-FONT        "Font"          "Charter"    ;a font variable
        SF-ADJUSTMENT  "Font size"     '(50 1 1000 1 10 0 1)
                                                    ;a spin-button
        SF-COLOR       "Color"         '(0 0 0)     ;color variable
      )
      (script-fu-menu-register "script-fu-text-box" "<Image>/File/Create/Text")

Se si salvano queste funzioni in un file di testo con estensione `.scm` all'interno della directory degli script, quindi si seleziona Filtri → Script-Fu → Rinfresca gli scripts, questo nuovo script comparirà come Filtri → Script-Fu → Text → Text Box.

Se si invoca questo nuovo script naturalmente non succede nulla, ma si possono osservare le richieste di parametri definite quando si registra lo script (ulteriori informazioni più avanti).

Infine, se si richiama il Navigatore di procedure (Aiuto → Navigatore di procedure), si noterà che lo script ora appare nel database.

#### 3.4.6. Passi per la registrazione dello script

Per registrare lo script in GIMP si richiama la funzione `script-fu-register`, passando i sette parametri richiesti e aggiungendo gli argomenti dello script insieme con una descrizione e un valore predefinito per ciascun argomento.

Gli argomenti richiesti

- Il nome della funzione definita. Questa è la funzione che viene chiamata quando si invoca lo script (il punto di entrata). È obbligatoria perché si possono definire altre funzioni all'interno dello stesso file e GIMP deve sapere quale tra queste funzioni richiamare. Nell'esempio si è definita solo una funzione, text-box, che è stata registrata.

- La collocazione nel menu dove lo script sarà inserito. L'esatta posizione è specificata come un percorso di file Unix, con `<Image>` come radice. [5]

  Se lo script non opera su immagini preesistenti (e quindi ne crea di nuove come lo script Text Box), è preferibile inserirlo nel menu della finestra immagine, accessibile tramite la barra del menu immagine, con il clic destro del mouse nella finestra immagine, facendo clic sull'icona del pulsante del menu sull'angolo in alto a sinistra della finestra immagine o premendo F10.

  Se lo script è stato pensato per lavorare su un'immagine in corso di modifica, è preferibile inserirlo nel menu immagine. La parte restante del percorso indica la voce del menu e dei sottomenu. Perciò, registrare lo script Text Box nel sottomenu Text del sottomenu Crea del menu File. [6] (File → Crea → Text → Text Box).

  Si noti che il sottomenu Text del menu File/Crea, non era presente all'inizio: GIMP crea automaticamente i menu inesistenti.

- Una descrizione dello script che viene visualizzata nel Navigatore delle procedure.

- Un nome autore (l'autore dello script).

- Informazioni sul Copyright.

- La data di creazione dello script o quella della sua ultima revisione.

- I tipi di immagine su cui lo script opera. Questo argomento può essere uno tra: RGB, RGBA, GRAY, GRAYA, INDEXED, INDEXEDA. Oppure può anche non essere presente del tutto, nel caso si crei una nuova immagine e quindi non risulti applicabile.

Figura 12.4. Il menu del nostro script.

#### 3.4.7. Registrare i parametri dello script

Dopo aver elencato gli argomenti necessari occorre elencare gli argomenti che corrispondono a quelli necessari al nostro script. Quando si elencano questi argomenti si danno indicazioni sui loro tipi, questo serve per la finestra di dialogo che compare quando l'utente seleziona lo script. Si deve anche fornire un valore predefinito.

Questa sezione del processo di registrazione ha il seguente formato:

Tipo argomento | Descrizione | Esempio
--- | --- | ---
`SF-IMAGE` | Se lo script opera su un'immagine già aperta, questo dovrebbe essere il primo argomento dopo quelli richiesti. GIMP passa un riferimento all'immagine in questo parametro. | 3
`SF-DRAWABLE` | Se lo script opera su un'immagine aperta questo dovrebbe essere il secondo argomento dopo `SF-IMAGE`. Si riferisce al livello attivo. GIMP passa un riferimento al livello attivo in questo parametro. | 17
`SF-VALUE` | Accetta numeri e stringhe. Si noti che le virgolette devono essere sottoposte ad escape perciò, in caso di stringhe di testo, è preferibile utilizzare `SF-STRING`. | 42
`SF-STRING` | Accetta stringhe. | "Del testo"
`SF-COLOR` | Indica che questo argomento richiede un colore. | '(0 102 255)
`SF-TOGGLE` | Viene mostrata una casella di scelta per richiedere un valore booleano. | TRUE o FALSE (vero o falso)

#### 3.4.8. Le API dei parametri Script-Fu [7]

| Nota
Malgrado il fatto che i precedenti tipi di parametri sono per lo più per la modalità interattiva, ogniuno di essi crea un widget nel pannello di controllo. Si può trovare un elenco di questi parametri con descrizioni e esempi nello script di prova `plug-ins/script-fu/scripts/test-sphere.scm` distribuito con i sorgenti di GIMP.

Tipo argomento | Descrizione
--- | ---
`SF-ADJUSTMENT` | Crea un widget di regolazione nella finestra di dialogo. SF-ADJUSTMENT "etichetta" '(valore inferiore superiore passo_inc pgina_inc cifre tipo) Elenco argomenti del widget
Elemento | Descrizione
--- | ---
"etichetta" | Testo stampato prima del widget.
valore | Valore stampato alla partenza.
inferiore / superiore | I valori inferiore / superiore (campo libero).
passo_inc | Incrementa/decrementa il valore.
pagina_inc | Incrementa/decrementa il valore usando i tasti pagina.
cifre | Cifre dopo la il punto (la parte decimale).
tipo | Uno di: SF-SLIDER o 0, SF-SPINNER o 1
`SF-COLOR` | Crea un pulsante di colore nella finestra di dialogo. SF-COLOR "etichetta" '(rosso verde blu) o SF-COLOR "etichetta" "colore" Elenco argomenti del widget
Elemento | Descrizione
--- | ---
"etichetta" | Testo stampato prima del widget.
'(rosso verde blu) | Elenco i tre valori per le componenti rosso, verde e blu.
"colore" | Nome colore in notazione CSS.
`SF-FONT` | Crea un widget di selezione caratteri nel pannello. Restituisce un nome di carattere come stringa. Ci sono due nuove procedure per la gestione del testo di GIMP per facilitare l'uso di questo parametro di ritorno: (gimp-text-fontname image drawable x-pos y-pos text border antialias size unit font) (gimp-text-get-extents-fontname text size unit font) dove font è il nome del carattere ottenuto. La dimensione specificata nel nome del carattere viene silenziosamente ignorata. Viene usata solo nel selettore del font. Per questa ragione viene richiesto di impostarla ad un valore sensato (24 pixel è una buona scelta). SF-FONT "etichetta" "nomecarattere" Elenco argomenti del widget
Elemento | Descrizione
--- | ---
"etichetta" | Testo stampato prima del widget.
"nomecarattere" | Nome del carattere predefinito.
`SF-BRUSH` | Crea un widget nel pannello di controllo. Il widget consiste in un'area di anteprima (che se premuta porta in primo piano una finestra di anteprima) ed un pulsante con etichetta "...". Il pulsante provocherà a sua volta la creazione di una finestra di dialogo in primo piano dove si potrà selezionare i pennelli e qualsiasi caratteristica di questi potrà essere modificata. SF-BRUSH "Brush" '("Circle (03)" 100 44 0) Qui il pannello pennelli verrà portato in primo piano con un pennello predefinito circolare (03) con opacità 100, spaziatura 44 e modalità di disegno Normale (valore 0). Se questa selezione non è stata modificata, il valore passato alla funzione come parametro sarà '("Circle (03)" 100 44 0).
`SF-PATTERN` | Crea un widget nel pannello di controllo. Il widget consiste di un'area di anteprima (che se premuta porta in primo piano una finestra di anteprima) ed un pulsante con etichetta "...". Il pulsante porta a sua volta in primo piano una finestra di dialogo con la quale è possibile selezionare i motivi. SF-PATTERN "Motivo" "Maple Leaves" Il valore restituito all'invocazione dello script è una stringa contenente il nome del motivo. Se la selezione precedente non è stata modificata la stringa contiene "Maple Leaves".
`SF-GRADIENT` | Crea un widget nel pannello di controllo. Il widget consiste in un pulsante contenente un'anteprima del gradiente selezionato. Se il pulsante viene premuto viene portata in primo piano una finestra di dialogo di scelta del gradiente. SF-GRADIENT "Gradiente" "Deep Sea" Il valore restituito quando lo script viene invocato è una stringa contenente il nome del gradiente. Se la selezione precedente non è stata modificata, la stringa contiene "Deep Sea".
`SF-PALETTE` | Crea un widget nella finestra di controllo. Il widget consiste in un pulsante contenente il nome della tavolozza selezionata. Se il pulsante viene premuto viene portata in primo piano una finestra di dialogo di scelta della tavolozza. SF-PALETTE "Tavolozza" "Colori con nome" Il valore restituito quando lo script viene invocato è una stringa contenente il nome della tavolozza. Se la selezione precedente non è stata alterata, la stringa dovrebbe contenere "Colori con nome".
`SF-FILENAME` | Esso conterrà un widget nel pannello di controllo. Il widget consiste in un pulsante contenente il nome di un file. Se viene premuto il pulsante, viene portata in primo piano una finestra di selezione file. SF-FILENAME "etichetta" (string-append "" gimp-data-directory "/scripts/beavis.jpg") Il valore restituito quando lo script viene invocato è una stringa contenente il nome del file.
`SF-DIRNAME` | Utile sono in modalità interattiva. Molto simile a SF-FILENAME, il widget creato permette di scegliere una directory invece di un file. SF-DIRNAME "etichetta" "/var/tmp/images" Il valore restituito quando lo script viene invocato è una stringa contenente il nome della directory.
`SF-OPTION` | Crea un widget nella finestra di controllo. Il widget è un combo-box (NdT: una combinazione di casella di testo e lista a discesa) che mostra le opzioni passate come lista. La prima opzione è la predefinita. SF-OPTION "etichetta" '("opzione1" "opzione2") Il valore restituito quando lo script viene invocato è il numero delle opzioni scelte, dove la prima opzione viene contata come 0.
`SF-ENUM` | Crea un widget nel pannello di controllo. Il widget è un combo-box che mostra tutti i valori enumerativi per il dato tipo enumerativo. Quest'ultimo deve essere il nome di un enumerato registrato, senza il prefisso "Gimp". Il secondo parametro specifica il valore predefinito, usando il nick del valore enumerativo. SF-ENUM "Interpolazione" '("TipoInterpolazione" "lineare") Il valore restituito, quando lo script viene invocato, corrisponde al valore scelto.

[5] Prima della versione 2.6, si poteva usare anche `<Toolbox>`, ma ora il menu degli strumenti (N.d.T. toolbox) è stato rimosso, perciò non usatelo.

[6] L'originale, scritto da Mike, diceva di mettere la voce di menu nel sottomenu Script-Fu del menu Xtns che era presente nel pannello degli strumenti ma, dalla versione 2.6, il menu del pannello strumenti è stato rimosso e fuso assieme con la barra del menu immagine.

[7] Questa sezione non è una parte originale di questa guida.

3.3. Liste, liste e ancora liste |  | 3.5. Dare un corpo allo script