3.5. Adding Additional Functionality

Si continui con il nostro addestramento e si aggiungano delle funzionalità allo script.

3.5.1. Creare una nuova immagine

In the previous lesson, we created an empty function and registered it with GIMP. In this lesson, we want to provide functionality to our script — we want to create a new image, add the user's text to it and resize the image to fit the text exactly.

Once you know how to set variables, define functions and access list members, the rest is all downhill — all you need to do is familiarize yourself with the functions available in GIMP's procedural database and call those functions directly. Open the Sezione 12.9, «Il navigatore delle procedure».

Cominciare creando una nuova immagine. Creare una nuova variabile, theImage, a cui assegnare il valore restituito dalla funzione interna gimp-image-new.

As you can see from the DB Browser, the function gimp-image-new takes three parameters — the image's width, height and the type of image. Because we'll later resize the image to fit the text, we'll make a 10×10 pixels RGB image. We'll store the image's width and sizes in some variables, too, as we'll refer to and manipulate them later in the script.

        (define (script-fu-text-box inText inFont inFontSize inTextColor)
        (let*
              (
                 ;definizione delle variabili locali
                 ;creazione di una nuova immagine:
                 (theImageWidth  10)
                 (theImageHeight 10)
                 (theImage (car
                                (gimp-image-new
                                 theImageWidth
                                 theImageHeight
                                 RGB
                                )
                           )
                 )
                 (theText)     ;una dichiarazione per il testo
                               ;che creeremo più avanti
      

Nota: si è utilizzato il valore RGB per specificare che l'immagine è di tipo RGB. Si sarebbe potuto anche utilizzare il valore 0 ma RGB è più descrittivo, quando si guarda il codice.

You should also notice that we took the head of the result of the function call. This may seem strange, because the database explicitly tells us that it returns only one value — the ID of the newly created image. However, all GIMP functions return a list, even if there is only one element in the list, so we need to get the head of the list.

3.5.2. Aggiungere un nuovo livello all'immagine

Ora che un'immagine è disponibile, occorre aggiungervi un livello. Chiamare la funzione gimp-layer-new per creare il livello passando l'ID dell'immagine precedentemente creata (da adesso in poi, invece di elencare l'intera funzione, verranno mostrate solo le linee da aggiungere. Si può osservare lo script completo qui). Poiché si sono dichiarate tutte le variabili locali utilizzate, si chiuderanno tutte le parentesi segnando la fine del blocco di dichiarazione delle variabili:

        ;create a new layer for the image:
           (theLayer
                     (car
                          (gimp-layer-new
                           theImage
                           "layer 1"
                           theImageWidth
                           theImageHeight
                           RGB-IMAGE
                           100
                           LAYER-MODE-NORMAL
                          )
                      )
            )
         ) ;end of our local variables
      

Una volta disponibile il nuovo livello occorre aggiungerlo all'immagine:

        (gimp-image-insert-layer theImage theLayer 0 0)
      

Si provi ora a testare il risultato del lavoro svolto fino a questo punto aggiungendo la linea seguente per mostrare la nuova immagine:

(gimp-display-new theImage)

Save your work, restart GIMP, run the script and a new image should pop up. It will probably contain garbage (random colors), because we haven't erased it. We'll get to that in a second.

3.5.3. Aggiungere il testo

Procedere rimuovendo la riga per visualizzare l'immagine (o la si commenti facendola precedere da un ; ad inizio linea).

Prima di aggiungere il testo all'immagine occorre impostare i colori di primo piano e di sfondo in modo che il testo abbia il colore selezionato dall'utente. Utilizzare le funzioni gimp-context-set-back/foreground:

        (gimp-context-set-background '(255 255 255) )
        (gimp-context-set-foreground inTextColor)
      

Con i colori opportunamente impostati cancellare la spazzatura presente nell'immagine riempiendo l'area con il colore di sfondo:

        (gimp-drawable-fill theLayer FILL-BACKGROUND)
      

Dopo aver pulito l'immagine si è pronti per l'aggiunta del testo:

        (set! theText
                      (car
                           (gimp-text-font
                            theImage theLayer
                            0 0
                            inText
                            0
                            TRUE
                            inFontSize
                            inFont)
                       )
        )
      

Anche se la chiamata della funzione è molto lunga è facile comprenderne il funzionamento esaminando i parametri mentre si fa riferimento alla voce della funzione nel Navigatore delle procedure. Essenzialmente si sta creando un nuovo livello di testo e lo si sta assegnando alla variabile theText.

Ora che il testo è disponibile si possono richiedere le sue dimensioni e ritagliare l'immagine e il suo livello:

        (set! theImageWidth   (car (gimp-drawable-get-width  theText) ) )
        (set! theImageHeight  (car (gimp-drawable-get-height theText) ) )

        (gimp-image-resize theImage theImageWidth theImageHeight 0 0)

        (gimp-layer-resize theLayer theImageWidth theImageHeight 0 0)
      

Ci si potrebbe chiedere che differenza c'è tra un piano disegnabile e un livello. Un piano disegnabile è qualcosa in cui si può disegnare e comprende i livelli ma anche i canali, le maschere, la selezione ecc. Un livello è una specializzazione di un piano disegnabile. Nella maggioranza dei casi, tuttavia, la differenza non è rilevante.

Una volta che l'immagine è pronta si può reinserire la riga per la visualizzazione:

        (gimp-display-new theImage)
      

Save your work, restart GIMP and give your first script a run!

3.5.4. Reimpostare il dirty flag

If you try to close the image created without first saving the file, GIMP will ask you if you want to save your work before you close the image. It asks this because the image is marked as dirty, or unsaved. In the case of our script, this is a nuisance for the times when we simply give it a test run and don't add or change anything in the resulting image — that is, our work is easily reproducible in such a simple script, so it makes sense to get rid of this dirty flag.

Si può azzerare la marcatura di modifica dopo aver mostrato l'immagine:

        (gimp-image-clean-all theImage)
      

Ciò azzererà il contatore delle modifiche, rendendo l'immagine «non modificata».

L'aggiunta di questa linea è una questione di gusti personali. È consigliabile utilizzarla in script che producono nuove immagini in cui i risultati sono banali. Se lo script è molto complicato o se lavora su immagini preesistenti è consigliabile non utilizzare questa funzione.