From 34489d1b13add3c9853ba8fa868f94489e73fc14 Mon Sep 17 00:00:00 2001 From: Michael Natterer Date: Tue, 10 Sep 2019 11:17:12 +0200 Subject: [PATCH] libgimp: add section docs for GimpPlugIn with general information and document the members of GimpProcedureClass. Also various doc fixes. --- devel-docs/libgimp/libgimp3-sections.txt | 4 +- libgimp/gimp.c | 16 +++--- libgimp/gimpplugin.c | 68 ++++++++++++++++++++---- libgimp/gimpprocedure.h | 15 ++++++ 4 files changed, 82 insertions(+), 21 deletions(-) diff --git a/devel-docs/libgimp/libgimp3-sections.txt b/devel-docs/libgimp/libgimp3-sections.txt index 9570b7646b..7da09b8690 100644 --- a/devel-docs/libgimp/libgimp3-sections.txt +++ b/devel-docs/libgimp/libgimp3-sections.txt @@ -964,6 +964,8 @@ gimp_pdb_get_type gimpprocedure GimpProcedure GimpRunFunc +GimpProcedure +GimpProcedureClass gimp_procedure_new gimp_procedure_get_plug_in gimp_procedure_get_name @@ -1004,8 +1006,6 @@ GIMP_PROCEDURE GIMP_PROCEDURE_CLASS GIMP_PROCEDURE_GET_CLASS GIMP_TYPE_PROCEDURE -GimpProcedure -GimpProcedureClass GimpProcedurePrivate gimp_procedure_get_type diff --git a/libgimp/gimp.c b/libgimp/gimp.c index fa9920fc79..e193fb1ef0 100644 --- a/libgimp/gimp.c +++ b/libgimp/gimp.c @@ -163,11 +163,11 @@ static GimpStackTraceMode stack_trace_mode = GIMP_STACK_TRACE_NEVER; * @argc: the number of arguments * @argv: (array length=argc): the arguments * - * The main procedure that must be called with the plug-in's - * #GimpPlugIn subclass type and the 'argc' and 'argv' that are passed - * to "main". + * The main plug-in function that must be called with the plug-in's + * #GimpPlugIn subclass #GType and the 'argc' and 'argv' that are passed + * to the platform's main(). * - * See also: GIMP_MAIN(). + * See also: GIMP_MAIN(), #GimpPlugIn. * * Returns: an exit status as defined by the C library, * on success EXIT_SUCCESS. @@ -598,8 +598,8 @@ gimp_main (GType plug_in_type, /** * gimp_get_plug_in: * - * This function returns the plug-in's #GimpPlugIn instance, which can - * exist exactly once per running plug-in program. + * This function returns the plug-in's #GimpPlugIn instance, which is + * a a singleton that can exist exactly once per running plug-in. * * Returns: (transfer none) (nullable): The plug-in's #GimpPlugIn singleton. * @@ -614,8 +614,8 @@ gimp_get_plug_in (void) /** * gimp_get_pdb: * - * This function returns the plug-in's #GimpPDB instance, which can - * exist exactly once per running plug-in program. + * This function returns the plug-in's #GimpPDB instance, which is a + * singleton that can exist exactly once per running plug-in. * * Returns: (transfer none) (nullable): The plug-in's #GimpPDB singleton. * diff --git a/libgimp/gimpplugin.c b/libgimp/gimpplugin.c index ab9f9b8fbd..eb66fdd9f2 100644 --- a/libgimp/gimpplugin.c +++ b/libgimp/gimpplugin.c @@ -42,8 +42,55 @@ * @title: GimpPlugIn * @short_description: The base class for plug-ins to derive from * - * The base class for plug-ins to derive from. Manages the plug-in's - * #GimpProcedure objects. + * The base class for plug-ins to derive from. #GimpPlugIn manages the + * plug-in's #GimpProcedure objects. The procedures a plug-in + * implements are registered with GIMP by returning a #GList of their + * names from either #GimpPlugInClass.query_procedures() or + * #GimpPlugInClass.init_procedures(). + * + * Every GIMP plug-in has to implement a #GimpPlugIn subclass and make + * it known to the libgimp infrastructure and the main GIMP + * application by passing its #GType to GIMP_MAIN(). + * + * GIMP_MAIN() passes the 'argc' and 'argv' of the platform's main() + * function, along with the #GType, to gimp_main(), which creates an + * instance of the plug-in's #GimpPlugIn subclass and calls its + * virtual functions, depending on how the plug-in was called by GIMP. + * + * There are three different ways GIMP calls a plug-in, "query", + * "init" and "run". + * + * The plug-in is called in "query" mode once after it was installed, + * or when the cached plug-in information in the config file + * "pluginrc" needs to be recreated. In "query" mode, + * #GimpPlugInClass.query_procedures() is called and returns a #GList + * of procedure names the plug-in implements. This is the "normal" + * place to register procedures, because the existence of most + * procedures doesn't depend on things that change between GIMP + * sessions. + * + * The plug-in is called in "init" mode at each GIMP startup, and + * #GimpPlugInClass.init_procedures() is called and returns a #GList + * of procedure names this plug-in implements. This only happens if + * the plug-in actually implements + * #GimpPlugInClass.init_procedures(). A plug-in only needs to + * implement #GimpPlugInClass.init_procedures() if the existence of + * its procedures can change between GIMP sessions, for example if + * they depend on the presence of external tools, or hardware like + * scanners, or online services, or whatever variable circumstances. + * + * The plug-in is called in "run" mode whenever one of the procedures + * it implements is called by either the main GIMP appliction or any + * other plug-in. In "run" mode, one of the procedure names returned + * by #GimpPlugInClass.query_procedures() or + * #GimpPlugInClass.init_procedures() is passed to + * #GimpPlugInClass.create_procedure() which must return a + * #GimpProcedure for the passed name. The procedure is then executed + * by calling gimp_procedure_run(). + * + * In any of the three modes, #GimpPlugInClass.quit() is called before + * the plug-in process exits, so the plug-in can perform whatever + * cleanup neccessary. * * Since: 3.0 **/ @@ -325,9 +372,8 @@ gimp_plug_in_get_property (GObject *object, * location, you may specify an absolute path to another * location. * - * This function can only be called in the #GimpPlugInClass.query() - * function of a plug-in and it has to be called before any procedure - * is installed. + * This function can only be called in the + * #GimpPlugInClass.query_procedures() function of a plug-in. * * Since: 3.0 **/ @@ -360,8 +406,8 @@ gimp_plug_in_set_translation_domain (GimpPlugIn *plug_in, * supported language there should be a file called 'gimp-help.xml' * that maps the help IDs to the actual help files. * - * This function can only be called in the #GimpPlugInClass.query() - * function of a plug-in. + * This function can only be called in the + * #GimpPlugInClass.query_procedures() function of a plug-in. * * Since: 3.0 **/ @@ -386,13 +432,13 @@ gimp_plug_in_set_help_domain (GimpPlugIn *plug_in, * @menu_path: The sub-menu's menu path. * @menu_label: The menu label of the sub-menu. * - * Add a new sub-menu to thr GIMP menus. + * Add a new sub-menu to the GIMP menus. * * This function installs a sub-menu which does not belong to any * procedure at the location @menu_path. * - * For translations of tooltips to work properly, @menu_label should - * only be marked for translation but passed to this function + * For translations of @menu_label to work properly, @menu_label + * should only be marked for translation but passed to this function * untranslated, for example using N_("Submenu"). GIMP will look up * the translation in the textdomain registered for the plug-in. * @@ -425,7 +471,7 @@ gimp_plug_in_add_menu_branch (GimpPlugIn *plug_in, * @plug_in: A #GimpPlugIn * @procedure_name: A procedure name. * - * This functiond creates a new procedure and is called when a plug-in + * This function creates a new procedure and is called when a plug-in * instance is started by GIMP when one of the %GIMP_PDB_PROC_TYPE_PLUGIN or * %GIMP_PDB_PROC_TYPE_EXTENSION procedures it implements is invoked. * diff --git a/libgimp/gimpprocedure.h b/libgimp/gimpprocedure.h index 0f4351e345..6b4431c23d 100644 --- a/libgimp/gimpprocedure.h +++ b/libgimp/gimpprocedure.h @@ -67,6 +67,21 @@ struct _GimpProcedure GimpProcedurePrivate *priv; }; +/** + * GimpProcedureClass: + * @install: called to install the procedure with the main GIMP + * application. This is an implementation detail and must never + * be called by any plug-in code. + * @uninstall: called to uninstall the procedure from the main GIMP + * application. This is an implementation detail and must never + * be called by any plug-in code. + * @run: called to when the procedure is executed via gimp_procedure_run(). + * the default implementation simply calls the procedure's #GimpRunFunc, + * #GimpProcedure subclasses are free to modify the passed @args and + * call their own, subclass-specific run functions. + * + * Since: 3.0 + **/ struct _GimpProcedureClass { GObjectClass parent_class;