Commit fba010a6 authored by Michael Natterer's avatar Michael Natterer 😴

libgimp: more GimpPlugIn docs

Mention and guarantee the order of procedure registration (see
previous thumbnail loader commit). Remove duplicate docs from the
GimpPlugIn class comments that are needed for introspection, it's too
cumbersome to keep two identical texts in sync, and the removed text
is used nowhere.
parent cc514956
Pipeline #113763 passed with stages
in 16 minutes and 22 seconds
......@@ -79,6 +79,14 @@
* they depend on the presence of external tools, or hardware like
* scanners, or online services, or whatever variable circumstances.
*
* In order to register the plug-in's procedures with the main GIMP
* application in the plug-in's "query" and "init" modes, #GimpPlugIn
* calls #GimpPlugInClass.create_procedure() on all procedure names in
* the exact order of the #GList returned by
* #GimpPlugInClass.query_procedures() or
* #GimpPlugInClass.init_procedures() and then registers the returned
* #GimpProcedure using #GimpProcedureClass.register().
*
* 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
......
......@@ -73,8 +73,12 @@ struct _GimpPlugIn
* and return a newly allocated #GimpProcedure named @name. It will
* be called for every @name as returned by
* #GimpPlugInClass.query_procedures() and
* #GimpPlugInClass.init_procedures() so care must be taken to handle
* them all.
* #GimpPlugInClass.init_procedures() so care must be taken to
* handle them all.
* Upon procedure registration, #GimpPlugInClass.create_procedure()
* will be called in the order of the lists returned by
* #GimpPlugInClass.query_procedures() and
* #GimpPlugInClass.init_procedures()
* @quit: This method can be overridden by a plug-in which needs to
* perform some actions upon quitting.
*
......@@ -93,44 +97,18 @@ struct _GimpPlugInClass
* GimpPlugInClass::query_procedures:
* @plug_in: a #GimpPlugIn.
*
* This method can be overridden by all plug-ins to return a newly
* allocated GList of allocated strings naming the procedures
* registered by this plug-in.
*
* See documentation of GimpPlugInClass::init_procedures() for
* differences.
*
* Returns: (element-type gchar*) (transfer full):
* the names of the procedures registered by @plug_in.
*
* Since: 3.0
*/
**/
GList * (* query_procedures) (GimpPlugIn *plug_in);
/**
* GimpPlugInClass::init_procedures:
* @plug_in: a #GimpPlugIn.
*
* This method can be overridden by all plug-ins to return a newly
* allocated #GList of allocated strings naming procedures registered
* by this plug-in.
*
* It is different from GimpPlugInClass::query_procedures() in that
* init happens at every startup, whereas query happens only once in
* the life of a plug-in (right after installation or update). Hence
* GimpPlugInClass::init_procedures() typically returns procedures
* dependent to runtime conditions (such as the presence of a
* third-party tool), whereas GimpPlugInClass::query_procedures()
* would usually return unconditional and always available
* procedures. Most of the time, you only want to override
* GimpPlugInClass::query_procedures() and leave
* GimpPlugInClass::init_procedures() untouched.
*
* Returns: (element-type gchar*) (transfer full):
* the names of the procedures registered by @plug_in.
*
* Since: 3.0
*/
**/
GList * (* init_procedures) (GimpPlugIn *plug_in);
/**
......@@ -138,28 +116,16 @@ struct _GimpPlugInClass
* @plug_in: a #GimpPlugIn.
* @procedure_name: procedure name.
*
* This method should be overridden by all plug-ins and return a newly
* allocated #GimpProcedure named @name.
* It will be called for every @name as returned by query_procedures()
* and init_procedures() so care must be taken to handle them all.
*
* Returns: (transfer full):
* the procedure to be registered by @plug_in.
*
* Since: 3.0
*/
* the procedure to be registered or executed by @plug_in.
**/
GimpProcedure * (* create_procedure) (GimpPlugIn *plug_in,
const gchar *procedure_name);
/**
* GimpPlugInClass::quit:
* @plug_in: a #GimpPlugIn.
*
* This method can be overridden by a plug-in which needs to perform
* some actions upon quitting.
*
* Since: 3.0
*/
**/
void (* quit) (GimpPlugIn *plug_in);
/* Padding for future expansion */
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment