dnrops
/
gimp
mirror of https://github.com/GNOME/gimp.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

libgimp: more GimpPlugIn and GimpProcedure docs and annotations 

They are now GI-warning-free.
This commit is contained in:
Michael Natterer 2019-08-02 01:32:16 +02:00
parent 0bec2bcdec
commit f86279fd1f
2 changed files with 155 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

130
libgimp/gimpplugin.c
View File

@ -97,6 +97,27 @@ gimp_plug_in_finalize (GObject *object)
/* public functions */
/**
* gimp_plug_in_set_translation_domain:
* @plug_in: A #GimpPlugIn.
* @domain_name: The name of the textdomain (must be unique).
* @domain_path: The absolute path to the compiled message catalog
* (may be %NULL).
*
* Sets a textdomain for localisation for the @plug_in.
*
* This function adds a textdomain to the list of domains Gimp
* searches for strings when translating its menu entries. There is no
* need to call this function for plug-ins that have their strings
* included in the 'gimp-std-plugins' domain as that is used by
* default. If the compiled message catalog is not in the standard
* location, you may specify an absolute path to another
* location. This function can only be called in the
* GimpPlugIn::query() function of a plug-in and it has to be called
* before any procedure is installed.
*
* Since: 3.0
**/
void
gimp_plug_in_set_translation_domain (GimpPlugIn *plug_in,
const gchar *domain_name,
@ -112,6 +133,22 @@ gimp_plug_in_set_translation_domain (GimpPlugIn *plug_in,
g_set_object (&plug_in->priv->translation_domain_path, domain_path);
}
/**
* gimp_plug_in_set_help_domain:
* @plug_in: A #GimpPlugIn.
* @domain_name: The XML namespace of the plug-in's help pages.
* @domain_uri: The root URI of the plug-in's help pages.
*
* Set a help domain and path for the @plug_in.
*
* This function registers user documentation for the calling plug-in
* with the GIMP help system. The domain_uri parameter points to the
* root directory where the plug-in help is installed. For each
* supported language there should be a file called 'gimp-help.xml'
* that maps the help IDs to the actual help files.
*
* Since: 3.0
**/
void
gimp_plug_in_set_help_domain (GimpPlugIn *plug_in,
const gchar *domain_name,
@ -127,6 +164,26 @@ gimp_plug_in_set_help_domain (GimpPlugIn *plug_in,
g_set_object (&plug_in->priv->help_domain_uri, domain_uri);
}
/**
* gimp_plug_in_add_menu_branch:
* @plug_in: A #GimpPlugIn
* @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.
*
* 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
* untranslated, for example using N_("Submenu"). GIMP will look up
* the translation in the textdomain registered for the plug-in.
*
* See also: gimp_procedure_add_menu_path().
*
* Since: 3.0
**/
void
gimp_plug_in_add_menu_branch (GimpPlugIn *plug_in,
const gchar *menu_path,
@ -147,6 +204,21 @@ gimp_plug_in_add_menu_branch (GimpPlugIn *plug_in,
branch);
}
/**
* gimp_plug_in_create_procedure:
* @plug_in: A #GimpPlugIn
* @name: A procedure name.
*
* This functiond creates a new procedure and is called when a plug-in
* instance is started by GIMP when one of the %GIMP_PLUGIN or
* %GIMP_EXTENSION procedures it implements is invoked.
*
* This function will only ever be called with names returned by
* implementations of GimpPlugIn::init_procedures() or
* GimpPlugIn::query_procedures().
*
* Returns: (transfer full): The newly created #GimpProcedure.
**/
GimpProcedure *
gimp_plug_in_create_procedure (GimpPlugIn *plug_in,
const gchar *name)
@ -161,6 +233,29 @@ gimp_plug_in_create_procedure (GimpPlugIn *plug_in,
return NULL;
}
/**
* gimp_plug_in_add_temp_procedure:
* @plug_in: A #GimpPlugIn
* @procedure: A #GimpProcedure of type %GIMP_TEMPORARY.
*
* This function adds a temporary procedure to @plug_in. It is usually
* called from a %GIMP_EXTENSION procedure's GimpProcedure::run().
*
* A temporary procedure is a procedure which is only available while
* one of your plug-in's "real" procedures is running.
*
* The procedure's type <emphasis>must</emphasis> be %GIMP_TEMPORARY
* or the function will fail.
*
* NOTE: Normally, plug-in communication is triggered by the plug-in
* and the GIMP core only responds to the plug-in's requests. You must
* explicitly enable receiving of temporary procedure run requests
* using either gimp_extension_enable() or
* gimp_extension_process(). See this functions' documentation for
* details.
*
* Since: 3.0
**/
void
gimp_plug_in_add_temp_procedure (GimpPlugIn *plug_in,
GimpProcedure *procedure)
@ -176,6 +271,16 @@ gimp_plug_in_add_temp_procedure (GimpPlugIn *plug_in,
_gimp_procedure_register (procedure);
}
/**
* gimp_plug_in_add_temp_procedure:
* @plug_in: A #GimpPlugIn
* @name: The name of a #GimpProcedure added to @plug_in.
*
* This function removes a temporary procedure from @plug_in by the
* procedure's @name.
*
* Since: 3.0
**/
void
gimp_plug_in_remove_temp_procedure (GimpPlugIn *plug_in,
const gchar *name)
@ -197,6 +302,19 @@ gimp_plug_in_remove_temp_procedure (GimpPlugIn *plug_in,
}
}
/**
* gimp_plug_in_get_temp_procedures:
* @plug_in: A #GimpPlugIn
* @name: The name of a #GimpProcedure added to @plug_in.
*
* This function retrieves the list of temporary procedure of @plug_in as
* added with gimp_plug_in_add_temp_procedure().
*
* Returns: (transfer none) (element-type GimpProcedure): The list of
* procedures.
*
* Since: 3.0
**/
GList *
gimp_plug_in_get_temp_procedures (GimpPlugIn *plug_in)
{
@ -205,6 +323,18 @@ gimp_plug_in_get_temp_procedures (GimpPlugIn *plug_in)
return plug_in->priv->temp_procedures;
}
/**
* gimp_plug_in_get_temp_procedure:
* @plug_in: A #GimpPlugIn
* @name: The name of a #GimpProcedure added to @plug_in.
*
* This function retrieves a temporary procedure from @plug_in by the
* procedure's @name.
*
* Returns: (transfer none): The procedure if registered, or %NULL.
*
* Since: 3.0
**/
GimpProcedure *
gimp_plug_in_get_temp_procedure (GimpPlugIn *plug_in,
const gchar *name)

37
libgimp/gimpprocedure.c
View File

@ -184,9 +184,18 @@ gimp_procedure_finalize (GObject *object)
*
* Using %GIMP_EXTENSION means that the plug-in will add temporary
* procedures. Therefore, the GIMP core will wait until the
* %GIMP_EXTENSION procedure has called gimp_extension_ack(), which
* means that the procedure has done its initialization, installed its
* temporary procedures and is ready to run.
* %GIMP_EXTENSION procedure has called
* gimp_procedure_extension_ready(), which means that the procedure
* has done its initialization, installed its temporary procedures and
* is ready to run.
*
* <emphasis>Not calling gimp_procedure_extension_reads() from a
* %GIMP_EXTENSION procedure will cause the GIMP core to lock
* up.</emphasis>
*
* Additionally, a %GIMP_EXTENSION procedure with no arguments added
* is an "automatic" extension that will be automatically started on
* each GIMP startup.
*
* %GIMP_TEMPORARY must be used for temporary procedures that are
* created during a plug-ins lifetime. They must be added to the
@ -283,9 +292,10 @@ gimp_procedure_get_proc_type (GimpProcedure *procedure)
* location(s) where to register in the menu hierarchy is chosen using
* gimp_procedure_add_menu_path().
*
* For translations of menu labels to work properly, this string
* For translations of menu labels to work properly, @menu_label
* should only be marked for translation but passed to this function
* untranslated, for example using N_("Label").
* untranslated, for example using N_("Label"). GIMP will look up the
* translation in the textdomain registered for the plug-in.
*
* Since: 3.0
**/
@ -295,7 +305,7 @@ gimp_procedure_set_menu_label (GimpProcedure *procedure,
{
g_return_if_fail (GIMP_IS_PROCEDURE (procedure));
g_clear_pointer (&procedure->priv->menu_label, g_free);
g_clear_pointer (&procedure->priv->menu_label, g_free);
procedure->priv->menu_label = g_strdup (menu_label);
}
@ -326,9 +336,10 @@ gimp_procedure_get_menu_label (GimpProcedure *procedure)
* @blurb is used as the @procedure's tooltip when represented in the UI,
* for example as a menu entry.
*
* For translations of tooltips to work properly, this string should
* only be marked for translation but passed to this function
* untranslated, for example using N_("Blurb").
* For translations of tooltips to work properly, @blurb should only
* be marked for translation but passed to this function untranslated,
* for example using N_("Blurb"). GIMP will look up the translation in
* the textdomain registered for the plug-in.
*
* @help: is a free-form text that's meant as documentation for
* developers of scripts and plug-ins.
@ -345,9 +356,9 @@ gimp_procedure_set_documentation (GimpProcedure *procedure,
{
g_return_if_fail (GIMP_IS_PROCEDURE (procedure));
g_clear_pointer (&procedure->priv->blurb, g_free);
g_clear_pointer (&procedure->priv->help, g_free);
g_clear_pointer (&procedure->priv->help_id, g_free);
g_clear_pointer (&procedure->priv->blurb, g_free);
g_clear_pointer (&procedure->priv->help, g_free);
g_clear_pointer (&procedure->priv->help_id, g_free);
procedure->priv->blurb = g_strdup (blurb);
procedure->priv->help = g_strdup (help);
@ -597,6 +608,8 @@ gimp_procedure_get_icon (GimpProcedure *procedure,
*
* &lt;Image&gt;/Layer/Transform
*
* See also: gimp_plug_in_add_menu_branch().
*
* Since: 3.0
**/
void