Per a poder accedir a les funcions del GIMP, comencem amb import gi. Aquest mòdul pot esbrinar quines funcions estan disponibles en cada mòdul definit a través de la «introspecció d'objectes». El que això significa per a nosaltres és que importem tots els mòduls relacionats amb el GIMP que puguem necessitar mitjançant crides a gi.repository.

Per a la funcionalitat bàsica, només els mòduls Gimp i GimpUi poden ser suficients. Si voleu executar el connector des de la línia d'ordres, ni tan sols necessitareu el GimpUi. Comencem amb un exemple.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
#   GIMP - The GNU Image Manipulation Program
#   Copyright (C) 1995 Spencer Kimball and Peter Mattis
#
#   gimp-tutorial-plug-in.py
#   sample plug-in to illustrate the Python plug-in writing tutorial
#   Copyright (C) 2023 Jacob Boerema
#
#   This program is free software: you can redistribute it and/or modify
#   it under the terms of the GNU General Public License as published by
#   the Free Software Foundation; either version 3 of the License, or
#   (at your option) any later version.
#
#   This program is distributed in the hope that it will be useful,
#   but WITHOUT ANY WARRANTY; without even the implied warranty of
#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#   GNU General Public License for more details.
#
#   You should have received a copy of the GNU General Public License
#   along with this program.  If not, see <https://www.gnu.org/licenses/>.

import sys

import gi
gi.require_version('Gimp', '3.0')
from gi.repository import Gimp
gi.require_version('GimpUi', '3.0')
from gi.repository import GimpUi
from gi.repository import GLib
      

Comencem amb la importació de sys, que necessitem al final per accedir a sys.argv, després que import gi li digui a Python que ha de carregar el mòdul gi. Aquest mòdul s'utilitza per habilitar l'accés a funcions específiques del GIMP mitjançant la «introspecció d'objectes».

A la següent línia li diem a gi que necessitem que la versió de l'API del GIMP sigui la versió 3.0. (Aquest connector no funcionarà amb versions anteriors del GIMP.) La línia següent demana importar totes les funcions, classes, etc. des del mòdul del Gimp.

Les dues línies següents fan el mateix pel GimpUi. GimpUi conté tots els elements relacionats amb la interfície per al GIMP. Si teniu pensat crear un connector que només es cridarà des de la línia d'ordres, no ho necessitareu. Acabem amb la importació de GLib que necessitarem més endavant per accedir a GLib.Error.

Hi ha altres mòduls opcionals que també podeu utilitzar, com el Gegl i el Glib entre molts altres, però ací no hi entrarem.

El GIMP ha de saber quines funcions estan disponibles, quina funcionalitat admeten i quina ubicació del menú utilitzar. Per això definim una classe que es deriva de la classe Gimp.PlugIn.

Un connector mínim necessita almenys les funcions següents definides en aquesta classe:

Ara entrarem una mica més en detall. No s'inclou a sota la primera part del codi Python que es mostrava a dalt. Això només mostra el disseny bàsic de la classe.

class MyFirstPlugin (Gimp.PlugIn):
    def do_query_procedures(self):
        return [ "jb-plug-in-first-try" ]

    def do_set_i18n (self, name):
        return False

    def do_create_procedure(self, name):
        procedure = Gimp.ImageProcedure.new(self, name,
                                            Gimp.PDBProcType.PLUGIN,
                                            self.run, None)

        procedure.set_image_types("*")

        procedure.set_menu_label("My first Python plug-in")
        procedure.add_menu_path('<Image>/Filters/Tutorial/')

        procedure.set_documentation("My first Python plug-in tryout",
                                    "My first Python 3 plug-in for GIMP 3",
                                    name)
        procedure.set_attribution("Your name", "Your name", "2023")

        return procedure

    def run(self, procedure, run_mode, image, n_drawables, drawables, config, run_data):
        Gimp.message("Hello world!")
        # do what you want to do, then, in case of success, return:
        return procedure.new_return_values(Gimp.PDBStatusType.SUCCESS, GLib.Error())
      

Fem una ullada més de prop a do_create_procedures. A la línia retorn [ "jb-plug-in-first-try" ] li diem al GIMP el nom del nostre procediment: l'anomenem "jb-plug-in-first-try". Aquest és el nom que es mostrarà al Navegador de procediments del GIMP.

Podeu tenir més d'un procediment definit en un connector. En aquest cas llistareu tots els noms separats per una coma.

És una bona pràctica iniciar tots els vostres tràmits amb les vostres inicials o alguna altra etiqueta reconeixible i única. D'aquesta manera és menys probable que el vostre nom sigui el mateix que el connector d'algú altre, cosa que podria confondre el GIMP. A més d'això, podeu anomenar-lo com vulgueu.

A continuació, li diem al GIMP que no admetem traduccions retornant False en la crida a do_set_i18n. Què fer quan voleu que el vostre connector es tradueixi i està fora de l'abast d'aquest tutorial.

El mètode do_create_procedure és on es fa la major part de la inicialització del GIMP.

Cada connector comença amb una crida a Gimp.main.

        Gimp.main(MyFirstPlugin.__gtype__, sys.argv)
      

L'única cosa que heu de canviar en aquesta línia per al vostre connector és el nom de la vostra classe de connector, ací anomenada «MyFirstPlugin».

A continuació presentem l'script Python sencer que s'hauria d'executar sempre que se li doni el nom correcte en un directori amb el mateix nom, i en una ubicació que conegui el GIMP. Mostrarà el missatge «Hola món!» a la consola d'errors o en un diàleg emergent.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
#   GIMP - The GNU Image Manipulation Program
#   Copyright (C) 1995 Spencer Kimball and Peter Mattis
#
#   gimp-tutorial-plug-in.py
#   sample plug-in to illustrate the Python plug-in writing tutorial
#   Copyright (C) 2023 Jacob Boerema
#
#   This program is free software: you can redistribute it and/or modify
#   it under the terms of the GNU General Public License as published by
#   the Free Software Foundation; either version 3 of the License, or
#   (at your option) any later version.
#
#   This program is distributed in the hope that it will be useful,
#   but WITHOUT ANY WARRANTY; without even the implied warranty of
#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#   GNU General Public License for more details.
#
#   You should have received a copy of the GNU General Public License
#   along with this program.  If not, see <https://www.gnu.org/licenses/>.

import sys

import gi
gi.require_version('Gimp', '3.0')
from gi.repository import Gimp
gi.require_version('GimpUi', '3.0')
from gi.repository import GimpUi

from gi.repository import GLib

class MyFirstPlugin (Gimp.PlugIn):
    def do_query_procedures(self):
        return [ "jb-plug-in-first-try" ]

    def do_set_i18n (self, name):
        return False

    def do_create_procedure(self, name):
        procedure = Gimp.ImageProcedure.new(self, name,
                                            Gimp.PDBProcType.PLUGIN,
                                            self.run, None)

        procedure.set_image_types("*")

        procedure.set_menu_label("My first Python plug-in")
        procedure.add_menu_path('<Image>/Filters/Tutorial/')

        procedure.set_documentation("My first Python plug-in tryout",
                                    "My first Python 3 plug-in for GIMP 3.0",
                                    name)
        procedure.set_attribution("Your name", "Your name", "2023")

        return procedure

    def run(self, procedure, run_mode, image, n_drawables, drawables, config, run_data):
        Gimp.message("Hello world!")
        # do what you want to do, then, in case of success, return:
        return procedure.new_return_values(Gimp.PDBStatusType.SUCCESS, GLib.Error())

Gimp.main(MyFirstPlugin.__gtype__, sys.argv)