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.

In the ~/.config/GIMP/2.10/ directory that GIMP made off of your home directory, you should find a directory called scripts. GIMP will automatically look in your ~/.config/GIMP/2.10/ directory for a scripts directory, and add the scripts in this directory to the Script-Fu database. You should place your personal scripts here.

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"                        ;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 FiltrosScript-FuRecarregar scripts. Este novo script vai aparecer como ArquivoCriarTextText 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, (AjudaNavegador 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] ArquivoCriarTextText 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

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] 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
ElementoDescriçã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
ElementoDescriçã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
ElementoDescriçã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.