### 3.4. Votre premier script de Script-Fu

Do you not need to stop and catch your breath? No? Well then, let's proceed with your fourth lesson your first Script-Fu Script.

#### 3.4.1. Création d’un Script Boîte de Texte

L’une des opérations les plus fréquentes que je réalise avec GIMP, est la création d’une boîte contenant un texte pour une page Web ou un logo. Mais vous ne savez jamais bien quelle taille donner à l’image au départ. Vous ne savez pas combien d’espace le texte occupera avec la taille de police que vous voulez.

This problem can be solved and automated with Script-Fu.

Nous allons donc créer un script, appelé Text Box, qui crée une image dont la taille est parfaitement adaptée au texte que saisit l’utilisateur. Nous permettrons aussi à l’utilisateur de choisir la police de caractères, sa taille, et la couleur du texte.

#### 3.4.2. Modifier et enregistrer vos Scripts

Up until now, we've been working in the Script-Fu Console. Now, however, we're going to switch to editing script files. Script files should be plain text files that you can edit in a text or code editor. The name you give is not that important, except for being able to recognize the script. You should give your script file the extension « .scm ».

Where you place your scripts is a matter of preference. In GIMP's folder preferences you can see in which folders GIMP looks for scripts. It is also possible to add a new folder there. The folder where GIMP stores its own scripts is usually not the best choice for your scripts, but for the rest feel free to choose what suits you best.

#### 3.4.3. Le strict nécessaire

Tout script de Script-Fu définit au moins une fonction, qui est la fonction principale du script. C’est là que vous travaillerez.

Tout script doit également être connu de la base de données de procédures (PDB), de façon à ce que GIMP puisse y accéder.

Nous allons définir la fonction principale en premier :

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

Here, we've defined a new function called `script-fu-text-box` that takes four parameters, which will later correspond to some text, a font, the font size, and the text's color. The function is currently empty and thus does nothing. So far, so good nothing new, nothing fancy.

#### 3.4.4. Conventions de dénomination

Les conventions de dénomination de Scheme préfèrent les lettres minuscules avec traits d’union, ce que j’ai respecté dans la dénomination de la fonction. Toutefois, je me suis écarté de la convention en ce qui concerne les paramètres. Je préfère en effet les noms descriptifs pour mes paramètres et variables, c’est pourquoi j’ai ajouté le préfixe « in » aux paramètres, de façon à voir d’emblée qu’il s’agit de paramètres reçus par la fonction et non pas de paramètres émis par elle. Et j’utilise le prefixe « the » pour les variables définies au sein du script.

C’est une convention GIMP de nommer vos fonctions de script script-fu-xxx, parce qu’ainsi elle apparaîtront avec les script-fu quand elles seront listées dans la base de procédures. Cela permet aussi de les distinguer des greffons.

#### 3.4.5. Enregistrement de la fonction

Maintenant, faisons connaître la fonction à GIMP. On réalise cela en appelant la fonction `script-fu-register`. Quand GIMP lira le script, il exécutera cette fonction qui enregistrera le script dans la base de procédures. Vous pouvez placer cette fonction où vous voulez dans votre script, mais personnellement je la mets à la fin, après tout le reste de mon code.

Voici le listing pour enregistrer cette fonction (j’expliquerai ses paramètres dans un instant) :

      (script-fu-register
        "script-fu-text-box"                        ;function 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>/Filters/Tutorial")

Save these functions in a text file with a `.scm` suffix in a subdirectory of your script directory, with the same name as your script file, then restart GIMP. The new script will appear as Filters → Tutorial → Text Box.

Si vous lancez ce nouveau script, il ne fera rien bien sûr, mais vous pourrez voir les invites que vous avez créées quand vous avez enregistré le script (ça sera plus clair plus loin).

Finalement, si vous invoquez le Navigateur de Procédures ( Aide → Navigateur de Procédures), vous verrez que votre script figure maintenant dans la base de procédures.

#### 3.4.6. Étapes pour enregistrer le script

Pour enregistrer notre script dans GIMP, nous appelons la fonction `script-fu-register`, remplissons les sept paramètres requis et nous ajoutons nos propres paramètres de script, ainsi qu’une description et une valeur par défaut pour chaque paramètre.

Les paramètres requis

- Le nom de la fonction que nous avons définie. C’est la fonction appelée quand notre script est invoqué, le point d’entrée dans notre script. C’est important parce qu’il est possible de définir plusieurs autres fonctions dans le même fichier, et GIMP doit savoir quelle fonction appeler. Dans notre exemple, nous n’avons défini qu’une seule fonction, text-box, que nous avons enregistrée.

- The menu label is the name that will be shown in the menu. To specify the location, see Section 3.4.9, « Registering the Menu Location ».

- Une description de votre script, qui sera affichée dans le Navigateur de Procédures.

- Votre nom (l’auteur du script)

- Information de Copyright.

- La date à laquelle le script a été créé, ou la date de dernière révision.

- The types of images the script works on. This may be any of the following: RGB, RGBA, GRAY, GRAYA, INDEXED, INDEXEDA. Or it may be none at all in our case, we're creating an image, and thus don't need to define the type of image on which we work.

#### 3.4.7. Enregistrement des paramètres du script

Maintenant que nous avons vu la liste des paramètres requis, nous devons préciser ceux qui correspondent aux besoins de notre script. Nous devons fournir des précisions concernant leur type, pour la fenêtre de dialogue qui apparaît quand l’utilisateur choisit notre script. Nous devons aussi fournir une valeur par défaut.

Cette section du processus d’enregistrement a le format suivant :

Type de paramètre | Description | Exemple
--- | --- | ---
`SF-IMAGE` | Si votre script opère sur une image ouverte, ceci doit être le premier paramètre après les paramètres requis. GIMP transmettra une référence à l’image dans ce paramètre. | 3
`SF-DRAWABLE` | Si votre script opère sur une image ouverte, ceci doit être le second paramètre, après le paramètre `SF-IMAGE`. Il se réfère au calque actif. GIMP transmettra une référence au calque actif dans ce paramètre. | 17
`SF-STRING` | Accepte les chaînes de caractères. | "Un texte"
`SF-COLOR` | Indique qu’une couleur est nécessaire pour ce paramètre. | '(0 102 255)
`SF-TOGGLE` | Une boîte de saisie est affichée, pour entrer une valeur Booléenne. | TRUE ou FALSE (Vrai ou Faux)

#### 3.4.8. Les paramètres de l’API Script-Fu

| Note
Beside the above parameter types there are more types for the interactive mode, each of them will create a widget in the control dialog. You will find a list of these parameters with descriptions and examples in the test script `plug-ins/script-fu/scripts/test-sphere-v3.scm` shipped with the GIMP source code.

Type de paramètre | Description
--- | ---
`SF-ADJUSTMENT` | En mode interactif il crée une zone de dialogue dans la fenêtre de dialogue du script-fu. SF-ADJUSTMENT "label" '(value lower upper step_inc page_inc digits type) Liste d’arguments de boutons
Élément | Description
--- | ---
"label" | Texte affiché devant la zone de dialogue.
valeur | value : Valeur affichée par défaut au départ.
lower / upper | Valeurs mini / maxi (détermine la plage de choix).
step_inc | Valeur pour incrémenter/décrémenter.
page_inc | Valeur pour incrémenter/décrémenter utilisant les touches Page
chiffres | Chiffres après le point (partie décimale)
type | Un parmi: SF-SLIDER or 0 (glissière), SF-SPINNER or 1 (bouton à flèche)
`SF-COLOR` | Crée un bouton de choix de couleur. SF-COLOR "label" '(red green blue) ou SF-COLOR "label" "color" Liste d’arguments de boutons
Élément | Description
--- | ---
"label" | Texte affiché devant la zone de dialogue.
'(red green blue) | Liste de trois valeurs pour les composantes rouge, vert et bleu de la couleur par défaut.
"color" | Color name in CSS notation.
`SF-FONT` | Crée une zone de sélection de fonte. Retourne le nom de la fonte sous la forme d’une chaîne de caractères. Il existe deux nouvelles procédures de type gimp-text pour utiliser facilement ce paramètre que retourne la fonction: (gimp-text-fontname image drawable x-pos y-pos text border antialias size unit font) (gimp-text-get-extents-fontname text size unit font) dans lesquelles le paramètre "font" est le nom de la fonte que vous obtenez. La taille spécifiée dans fontname est ignorée. Elle est utilisée seulement dans le sélecteur de fonte. On vous demandera de donner une valeur utilisable (24 pixels est un choix correct). SF-FONT "label" "fontname" Liste d’arguments de boutons
Élément | Description
--- | ---
"label" | Texte affiché devant la zone de dialogue.
"fontname" | Nom de la fonte par défaut.
`SF-BRUSH` | Crée une zone de choix de brosse : prévisualisation de la brosse et à sa droite, bouton "Parcourir". Cliquer sur ce dernier fait apparaître la boite de dialogue des brosses avec possibilité de choisir une brosse ainsi que son espacement, son opacité et son mode. SF-BRUSH "Brush" '("Circle (03)" 100 44 0) Dans ce cas la brosse par défaut sera un Cercle (03) avec une opacité de 100, un espacement de 44 et en mode normal (0). Si cette sélection reste inchangée la valeur passée à la fonction comme paramètre sera '("Circle (03)" 100 44 0).
`SF-PATTERN` | Crée une zone de choix de motif : prévisualisation du motif et à sa droite, bouton "Parcourir". Cliquer sur ce dernier fait apparaître la boite de dialogue des motifs. SF-PATTERN "Pattern" "Maple Leaves" La valeur retournée quand le script est appelé est une chaîne de caractères contenant le nom du motif. Si la sélection par défaut ci-dessus n’est pas modifiée, la chaîne contiendra "Maple Leaves".
`SF-GRADIENT` | Crée un bouton contenant une prévisualisation du dégradé. Si on appuie sur le bouton, une fenêtre de sélection de palette apparaît. SF-GRADIENT "Gradient" "Deep Sea" La valeur retournée quand le script est appelé est une chaîne de caractères contenant le nom du dégradé. Si la sélection par défaut ci-dessus n’est pas modifiée, la chaîne contiendra "Deep Sea".
`SF-PALETTE` | Crée un bouton contenant le nom de la palette sélectionnée. Si on appuie sur le bouton, une fenêtre de sélection de palette apparaît. SF-PALETTE "Palette" "Named Colors" La valeur retournée quand le script est appelé est une chaîne de caractères contenant le nom de la palette. Si la sélection par défaut ci-dessus n’est pas modifiée, la chaîne contiendra "Named Colors".
`SF-FILENAME` | Crée un bouton contenant le nom d’un fichier. Cliquer sur celui-ci fait apparaître la boite de dialogue de sélection de fichiers. SF-FILENAME "label" (string-append "" gimp-data-directory "/scripts/beavis.jpg") La valeur retournée quand le script est appelé est une chaîne de caractères contenant le nom du fichier.
`SF-DIRNAME` | Similaire à SF-FILENAME, mais permet de choisir un dossier. SF-DIRNAME "label" "/var/tmp/images" La valeur retournée quand le script est appelé est une chaîne de caractères contenant le nom du dossier.
`SF-OPTION` | Crée une boîte de choix (combo-box) pour des options possibles. La première option est l’option par défaut. SF-OPTION "label" '("option1" "option2") La valeur retournée quand le script est appelé est le numéro de l’option choisie (0 correspondant à la 1ère option…).
`SF-ENUM` | It will create a widget in the control dialog. The widget is a combo-box showing all enum values for the given enum type. This has to be the name of a registered enum, without the "Gimp" prefix. The second parameter specifies the default value, using the enum value's nick. SF-ENUM "Interpolation" '("InterpolationType" "linear") La valeur retournée quand le script est appelé est la valeur choisie de l’énumération.

#### 3.4.9. Registering the Menu Location

Once we have registered our script, we need to tell GIMP where it should be found in the menu.

The best menu location of your script depends on its function. Most scripts are found in the Filters and Colors menus.

For the current script, which creates a new image, we choose a submenu of Filters → Tutorial. This is what the line with the `script-fu-menu-register` function does. Thus, we registered our Text Box script here: Filters → Tutorial → Text Box.

Any submenu that you specify in your script that doesn't exist yet will be automatically created by GIMP.

3.3. Listes, des listes et encore des listes |  | 3.5. Adding Additional Functionality

Report a bug in GIMP Report a documentation error