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

Até agora nós estávamos trabalhando no terminal do Script-Fu. Agora, entretanto, nós vamos mudar isso, e editar arquivos de texto contendo os scripts.

Onde você coloca o script é uma questão de preferência — Você pode deixa-los na pasta `scripts` do seu diretório pessoal de dados do GIMP, ou pode deixa-los numa pasta separada.

Na pasta `.gimp-2.8` (na versão 2.10 em diante, veja a pasta “.config/GIMP/<versão>”) que o GIMP criou na sua pasta de arquivos pessoais, você vai encontrar uma pasta com o nome de `scripts`. O GIMP vai olhar automaticamente nessa pasta, e adicionar quaisquer scripts encontrados aí na sua base de dados de Script-fu. Você pode deixar seus scripts pessoais aí, ou criar outra pasta indo até a guia de Pastas no diálogo de Preferências do GIMP.

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

E é uma convenção do GIMP que sua função de script tenha um nome do tipo `script-fu-abc`, por que quando elas são listadas na base de dados procedural, elas também aparecem sob “script-fu” quando você está listando as funções. Isso ajuda a distinguir as mesmas de 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"                        ;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 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.

- O nome que nosso script vai ter nos menus é colocado no segundo parâmetro - o rótulo (menu label). Em scripts antigos, esse parâmetro também continha a posição nos menus onde o script iria aparecer no GIMP. No GIMP atual, é feita uma outra chamada para registrar o script, à função `script-fu-menu-register` — é aí que é definido o ponto em que o script aparecerá nos menus. O ponto é exato é especificado usando um caminho de menus separados por "/", com a primeira parte sendo `<Image>`. [5]

  Uma vez que seu script não trabalha em uma imagem pré-existente (e portanto, cria uma nova imagem, como nosso Text Box “Caixa de Texto” fará), você não precisa colocar os primeiros parâmetros da função como sendo do tipo SF-IMAGE e SF-DRAWABLE. (veja a nota de rodapé)

  Assim, nós registramos nosso script em: File menu.[6] Arquivo → Criar → Text → Text Box [7]

  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.

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

Figura 13.4. O nosso script nos menus

#### 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) | Nome da cor na notação usada em CSS
`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` | Irá criar um widget no diálogo do script. este widget é uma caixa de opções mostrando todos os valores de enumeração para o tipo de enumeração dado. O parâmetro tem que ser o nome de uma enumeração registrada, sem o prefixo "GIMP". O segundo parâmetro especifica o valor padrão, usando o apelido dado na enumeração. SF-ENUM "Interpolação" '("InterpolationType" "linear") O valor retornado quando o script é invocado corresponde ao valor numérico do item de enumeração escolhido·

[5] Antes da versão 2.6, `<Toolbox>` também podia ser usado, mas agora o menu de Toolbox (caixa de ferramentas) foi removido, então não o use. Há outros nomes que podem ser usados no entanto, para adicionar o script aos menus contextuais de vários diálogos, como o de Camadas, Vetores, Texturas, etc...

[6] O tutorial original, escrito pelo Mike, colocava esse menu na caixa de ferramentas do GIMP, num tempo em que havia um menu separado lá, como nome de Extras (Xtns) — todos os plug-ins e scripts que criavam novas imagens eram colocados aí. Desde a versão 2.6, no entanto, esses menus foram unificados, e a forma de dizer ao GIMP que seu script vai funcionar com uma imagem já existente passou a ser a definição de parâmetros. Se os dois primeiros parâmetros forem do tipo SF-IMAGE e SF-DRAWABLE, o GIMP manda automaticamente a referência da imagem e objeto desenhável ativos quando seu plug-in é chamado.

[7] O tutorial original, escrito pelo Mike, colocava esse menu na caixa de ferramentas do GIMP, num tempo em que havia um menu separado lá, como nome de Extras (Xtns) — todos os plug-ins e scripts que criavam novas imagens eram colocados aí. Desde a versão 2.6, no entanto, esses menus foram unificados, e a forma de dizer ao GIMP que seu script vai funcionar com uma imagem já existente passou a ser a definição de parâmetros. Se os dois primeiros parâmetros forem do tipo SF-IMAGE e SF-DRAWABLE, o GIMP manda automaticamente a referência da imagem e objeto desenhável ativos quando seu plug-in é chamado.

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

Crie um relato de erro no Bugzilla