### 3.4. Seu primeiro 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. Criando um Script para uma caixa de texto

Uma das coisas mais comuns a se fazer no GIMP é criar uma caixa com algum texto para uma página web, um logotipo, ou para qualquer outra coisa. Entretanto, você nunca sabe de que tamanho criar a imagem inicial quando você começa o trabalho. Você não sabe quanto espaço o texto vai usar com a fonte e tamanho de fonte que você quer usar.

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

Nós iremos, portanto, criar um script chamado Caixa de Texto, que cria uma imagem do tamanho correto para conter uma linha de texto digitada pelo usuário. Também deixaremos o usuário escolher a fonte, tamanho da fonte e cor do texto.

#### 3.4.2. Editando e guardando seus 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. O básico essencial

Todo Script-fu define pelo menos uma função, que é a função principal do Script. É ai que você faz o trabalho.

Todo script também precisa se registrar com a base de dados procedural, de forma que ele possa ser acessado de dentro do GIMP.

Primeiro vamos definir nossa função principal:

            (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. Convenções para os nomes

A convenção de nomes do Scheme prefere nomes em caixa baixa separados por hífen, o que eu segui no nome da função. No entanto, eu não uso a convenção para criar os nomes dos parâmetros. Eu gosto de nomes mais descritivos para os meus parâmetros e variáveis, e portanto eu coloquei o prefixo "in" nos nomes dos parâmetros, de forma que eu possa perceber rapidamente que eles são valores passados ao script, em vez de criados lá dentro. Eu uso o prefixo "the" para variáveis definidas dentro do script.

It's GIMP convention to name your script functions `script-fu-abc`, because then when they're listed in the procedural database, they'll all show up under Script-Fu when you're listing the functions. This also helps distinguish them from plug-ins.

#### 3.4.5. Registrando a função

Agora, vamos registrar a função no GIMP. Isso é feito chamando-se a função `script-fu-register`. Quando o GIMP lê um script, ele executa esta função, que registra o script com a base de dados procedural. Você pode colocar essa chamada de função onde desejar no seu script, mas eu normalmente a coloco no final, depois de todo o meu código.

Aqui está a listagem para registrar esta função (eu vou explicar todos esses parâmetros em um minuto):

      (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.

Se você invocar esse novo script, ele não vai fazer nada, claro, mas você já pode ver as entradas que ele cria ao registrar o script. (Em seguida mais informações sobre o que foi que fizemos)

Finalmente, se você invocar o navegador de procedimentos, (Ajuda → Navegador de procedimentos), você notará que nosso script aparece no banco de dados.

#### 3.4.6. Passos para registrar o script

Para registrar nosso script com o GIMP, nós chamamos a função `script-fu-register`, preenchemos os sete parâmetros necessários e adicionamos os parâmetros de nosso próprio script, junto com uma descrição e um valor padrão para cada parâmetro.

Os parâmetros necessários

- O nome (func name) da função que nós definimos. Essa é a função que será chamada quando nosso script for invocado (o ponto de entrada de nosso script). Isso é necessário por que nós podemos definir funções adicionais no mesmo arquivo, e o GIMP precisa saber qual chamar. No nosso exemplo, nós definimos apenas uma função, script-fu-text-box, que nós registramos.

- The menu label is the name that will be shown in the menu. To specify the location, see Seção 3.4.9, “Registering the Menu Location”.

- Voltando aos parâmetros da chamada de “script-fu-register”: você passa uma descrição (description) do seu script, que será mostrada no navegador de procedimentos.

- Seu nome - o quarto parâmetro recebe o nome do autor do script. (Michael Terry no exemplo)

- O quinto parâmetro contém informações de Copyright (direto de autor).

- O sexto parâmetro é a data em que o script foi feito, ou a data da última revisão.

- 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. Registrando os parâmetros do script

Uma vez que nós tenhamos listado os parâmetros necessários, então precisamos listar os parâmetros que correspondem ao que o nosso script precisa. Quando listamos esses parâmetros, nós damos dicas de qual tipo cada um deve ser. Com isso, o GIMP constrói um diálogo automaticamente quando o usuário executar nosso script. Nós também damos um valor padrão para cada parâmetro.

A seção de registro de parâmetros tem o seguinte formato:

Tipo de parâmetro | Descrição | Exemplo
--- | --- | ---
`SF-IMAGE` | Se o seu script vai trabalhar numa imagem que já está aberta, esse deve ser o primeiro parâmetro, depois dos parâmetros requeridos. O GIMP irá passar uma referência para a imagem neste parâmetro. | 3
`SF-DRAWABLE` | Se o seu script vai trabalhar numa imagem que já está aberta, esse deve ser o segundo parâmetro, logo depois do parâmetro `SF-IMAGE`. Ele se refere à camada ou outro objeto desenhável ativo (canal, máscara de camada, etc...). O GIMP passa uma referência à camada ativa neste parâmetro. | 17
`SF-STRING` | Aceita strings (texto) | "Algum texto"
`SF-COLOR` | Indica que uma cor é requerida neste parâmetro | '(0 102 255)
`SF-TOGGLE` | É exibido um controle que devolve um valor Booleano | TRUE ou FALSE

#### 3.4.8. A API de parâmetros do Script-fu

| Nota
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.

Tipo de parâmetro | Descrição
--- | ---

`SF-ADJUSTMENT`

Cria um controle de ajuste no diálogo

SF-ADJUSTMENT "rótulo" '(value lower upper step_inc page_inc digits type)

Lista de argumentos do controle

Elemento | Descrição
--- | ---
"rótulo" | O texto impresso antes do controle
value (valor) | O valor a ser colocado por padrão
lower / upper (limite_inferior / limite_superior) | Os valores para os limites inferior e superior (faixa de escolha)
step_inc (passo_de_incremento) | Valor de incremento/decremento
page_inc (incremento_de_pagina) | valor de incremento/decremento ao usar PageUp e PageDown
digits (dígitos) | Número de dígitos após a vírgula (parte decimal)
type (tipo) | Um dentre: SF-SLIDER or 0, SF-SPINNER or 1 (muda o tipo de widget apresentado)

`SF-COLOR`

Cria um botão de seleção de cor no diálogo.

SF-COLOR "rótulo" '(red green blue)

ou

SF-COLOR "rótulo" "color"

Lista de argumentos do controle

Elemento | Descrição
--- | ---
"rótulo" | O texto impresso antes do controle
'(red green blue) | Lista de três valores para os componentes vermelho, verde e azul
"color" (cor) | Color name in CSS notation.

`SF-FONT`

Cria um widget de seleção de fontes no diálogo. Ele retorna um nome de fonte como uma string. Existem dois novos procedimentos de gimp-text para usar com esse parâmetro retornado:

(gimp-text-fontname image drawable x-pos y-pos text border antialias size unit font)

(gimp-text-get-extents-fontname text size unit font)

onde “font” é o nome da fonte que você recebe. O tamanho especificado no nome da fonte é ignorado silenciosamente - ele só é usado no seletor de fontes. Então é pedido a você que escolher um bom valor - para o parâmetro “size” (tamanho) (24 pixels é uma boa escolha)

SF-FONT "rótulo" "fontname"

Lista de argumentos do controle

Elemento | Descrição
--- | ---
"rótulo" | O texto impresso antes do controle
"fontname" (nome da fonte) | Nome da fonte que será mostrada como padrão.

`SF-BRUSH`

Irá criar um widget no diálogo de controle do script - este widget consiste numa área de pré-visualização (que quando clicada fará aparecer uma pré-visualização flutuante) e um botão com o rótulo "...". O botão fará aparecer um diálogo onde o usuário pode escolher pincéis e cada uma das características do pincel pode ser modificada.

SF-BRUSH "Brush" '("Circle (03)" 100 44 0)

Nesse caso, o diálogo de pincéis será aberto com um pincel padrão de "Circle (03)" (esse é o nome do pincel), opacidade 100, espaçamento 44, e modo de pintura Normal (valor 0)

Se esta seleção não for modificada, o valor passado para a função como parâmetro será '("Circle (03)" 100 44 0).

`SF-PATTERN`

Irá criar um widget no diálogo de controle do script - este widget consiste numa área de pré-visualização (que quando clicada fará aparecer uma pré-visualização flutuante) e um botão com o rótulo "...". O botão fará aparecer um diálogo onde o usuário pode escolher umatexturas entre as disponíveis para o GIMP

SF-PATTERN "Textura" "Maple Leaves"

O valor de retorno quando o script for chamado é uma string contendo o nome da textura. Se a seleção acima não for alterada, essa string iria conter "Maple Leaves". (o nome da textura como existe por padrão no GIMP)

`SF-GRADIENT`

Irá criar um widget no diálogo do script. Este widget consiste em um botão contendo uma pré-visualização do degradê selecionado

Se o botão for pressionado, uma seleção de degradês aparecerá num diálogo separado.

SF-GRADIENT "Degradê" "Deep Sea"

O valor de retorno quando o script for chamado é uma string contendo o nome do Degradê. Se a seleção acima não for alterada, essa string iria conter "Deep Sea". (o nome do degradê como existe por padrão no GIMP)

`SF-PALETTE` | Irá criar um widget no diálogo do script. Este widget consiste em um botão contendo o nome da paleta selecionada. Se o botão for pressionado, surgirá um diálogo de seleção de paletas. SF-PALETTE "Palette" "Named Colors" O valor retornado quando o script é chamado é uma string com o nome da paleta. Se a seleção acima não for alterada, isso será uma string contendo "Named Colors".
`SF-FILENAME` | Irá criar um widget no diálogo do script. Este widget consiste em um botão contendo um nome de arquivo. Se o botão for pressionado, surgirá um diálogo de seleção de arquivos. SF-FILENAME "label" (string-append "" gimp-data-directory "/scripts/beavis.jpg") O valor retornado quando o script é chamado é uma string com o nome do arquivo.
`SF-DIRNAME` | Só é útil no modo interativo.Muito parecido com SF-FILENAME, mas o widget criado só permite a escolha de uma pasta, em vez de um arquivo. SF-DIRNAME "label" "/var/tmp/images" O valor retornado quando o script é chamado é uma string com o caminho para a pasta.
`SF-OPTION` | Irá criar um widget no diálogo do script. Este widget consiste em uma caixa de escolhas mostrando as opções passadas como uma lista. A primeira opção é a escolha selecionada por padrão. SF-OPTION "rótulo" '("option1" "option2") O valor retornado quando o script é chamado é o número da opção escolhida, onde a primeira opção tem é considerada como estando na posição "0".

`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 "Interpolação" '("InterpolationType" "linear")

O valor retornado quando o script é invocado corresponde ao valor numérico do item de enumeração escolhido·

#### 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. Listas, Listas e mais Listas! |  | 3.5. Adding Additional Functionality

Report a bug in GIMP Report a documentation error