3.4. Seu primeiro Script de Script-Fu
| 3. Um tutorial de Script-Fu |

### 3.4. Seu primeiro Script de Script-Fu

Você precisa parar e recuperar o fôlego? Não? Bem, então vamos proceder a quarta lição — seu primeiro Script em Script-Fu.

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

O Mestre de Script-Fu (e o aprendiz) podem reconhecer rapidamente que esse problema pode ser resolvido facilmente e automatizado por meio do 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))

Aqui, nós colocamos o cabeçalho que define uma função chamada `script-fu-text-box` que recebe 4 parâmetros, que mais tarde irão corresponder a um texto, uma fonte, um tamanho de fonte e uma cor de texto. Exceto a palavra chave “define” os outros nomes foram criados nesse momento, pelo programa. O corpo da função por enquanto não foi criado. Por enquanto tudo bem, nada demais.

#### 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>/File/Create/Text")

Se você salvar essas funções numa arquivo de texto com uma extensão `.scm` na sua pasta de scripts, então clique em Filtros → Script-Fu → Recarregar scripts. Este novo script vai aparecer como Arquivo → Criar → Text → 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. In previous versions of GIMP you could specify the menu location here, but that has changed. How to specify the location will be shown below.

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

- O sétimo parâmetro. de tipos sé é necessário para scripts que vão trabalhar em imagens já existentes. Ele deve ser um desses: RGB, RGBA, GRAY, GRAYA, INDEXED, INDEXEDA. Ou pode ficar em branco no nosso caso, já que estaremos criando uma imagem nova. Se o seu script aceitar qualquer tipo de imagem, você pode por um `"*"` aqui.

#### 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-VALUE` | Aceita números e strings. Note que as strings para o texto padrão tem que ser escapadas (escaped) — então é melhor usar `SF-STRING` para texto. | 42
`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
Além dos tipos de parâmetros acima, há mais tipos para o modo interativo — cada um deles criará um widget no diálogo de controle. Você encontrará uma lista desses parâmetros com descrições e exemplos no script de teste `plug-ins/script-fu/scripts/test-sphere.scm` que vai junto com o código fonte do GIMP.

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 File → Create. This is what the line with the `script-fu-menu-register` function does. Thus, we registered our Text Box script here: File → Create → Text → Text Box.

Se você notar, o submenu “Text” de Arquivo/Criar não estava lá antes de registrar o script. O GIMP cria automaticamente os caminhos de menus que já não existem. E para permitir que Scrips possam rodar no mesmo lugar na estrutura de menus mesmo com o GIMP rodando em línguas diferentes (lembre-se, o GIMP é traduzido para mais de 50 línguas), o nome em Inglês dos menus é usado para o registro. Então, mesmo usando o caminho "<Image>/File/Create" em nossa chamada da função “script-fu-menu-register ”, os nomes em português serão usados até onde os nomes em inglês coincidirem com os que são usados no GIMP naquela língua. Isso acontece por que o GIMP é escrito em inglês, e todo o texto que aparece no programa, inclusive nos nomes de menus, é traduzido para outras línguas separadamente. Se você colocar os nomes de menus que você vê no GIMP em português na chamada de “script-fu-menu-register ”, um segundo menu “Arquivo”, antes do menu “Janelas” será criado para conter o seu script.

Figura 13.2. O nosso script nos menus

3.3. Listas, Listas e mais Listas! |  | 3.5. Colocando algum conteúdo em nosso script

Report a bug in GIMP Report a documentation error