Top | ![]() |
![]() |
![]() |
![]() |
GIOChannel * | read-channel | Read / Write / Construct Only |
GIOChannel * | write-channel | Read / Write / Construct Only |
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.
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 application 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 necessary.
void gimp_plug_in_set_translation_domain (GimpPlugIn *plug_in
,const gchar *domain_name
,GFile *domain_path
);
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
GimpPlugInClass.query_procedures()
function of a plug-in.
plug_in |
A GimpPlugIn. |
|
domain_name |
The name of the textdomain (must be unique). |
|
domain_path |
A GFile pointing to the compiled message catalog
(may be |
[nullable] |
Since: 3.0
void gimp_plug_in_set_help_domain (GimpPlugIn *plug_in
,const gchar *domain_name
,GFile *domain_uri
);
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.
This function can only be called in the
GimpPlugInClass.query_procedures()
function of a plug-in.
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. |
Since: 3.0
void gimp_plug_in_add_menu_branch (GimpPlugIn *plug_in
,const gchar *menu_path
,const gchar *menu_label
);
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 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.
See also: gimp_procedure_add_menu_path()
.
Since: 3.0
void gimp_plug_in_add_temp_procedure (GimpPlugIn *plug_in
,GimpProcedure *procedure
);
This function adds a temporary procedure to plug_in
. It is usually
called from a GIMP_PDB_PROC_TYPE_EXTENSION
procedure's
GimpProcedureClass.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 must be
GIMP_PDB_PROC_TYPE_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_plug_in_extension_enable()
or
gimp_plug_in_extension_process()
. See this functions' documentation
for details.
Since: 3.0
void gimp_plug_in_remove_temp_procedure (GimpPlugIn *plug_in
,const gchar *procedure_name
);
This function removes a temporary procedure from plug_in
by the
procedure's procedure_name
.
Since: 3.0
GList *
gimp_plug_in_get_temp_procedures (GimpPlugIn *plug_in
);
This function retrieves the list of temporary procedure of plug_in
as
added with gimp_plug_in_add_temp_procedure()
.
Since: 3.0
GimpProcedure * gimp_plug_in_get_temp_procedure (GimpPlugIn *plug_in
,const gchar *procedure_name
);
This function retrieves a temporary procedure from plug_in
by the
procedure's procedure_name
.
Since: 3.0
void
gimp_plug_in_extension_enable (GimpPlugIn *plug_in
);
Enables asynchronous processing of messages from the main GIMP application.
Normally, a plug-in is not called by GIMP except for the call to the procedure it implements. All subsequent communication is triggered by the plug-in and all messages sent from GIMP to the plug-in are just answers to requests the plug-in made.
If the plug-in however registered temporary procedures using
gimp_plug_in_add_temp_procedure()
, it needs to be able to receive
requests to execute them. Usually this will be done by running
gimp_plug_in_extension_process()
in an endless loop.
If the plug-in cannot use gimp_plug_in_extension_process()
, i.e. if
it has a GUI and is hanging around in a GMainLoop, it must call
gimp_plug_in_extension_enable()
.
Note that the plug-in does not need to be a GIMP_PDB_PROC_TYPE_EXTENSION to register temporary procedures.
See also: gimp_plug_in_add_temp_procedure()
.
Since: 3.0
void gimp_plug_in_extension_process (GimpPlugIn *plug_in
,guint timeout
);
Processes one message sent by GIMP and returns.
Call this function in an endless loop after calling
gimp_procedure_extension_ready()
to process requests for running
temporary procedures.
See gimp_plug_in_extension_enable()
for an asynchronous way of
doing the same if running an endless loop is not an option.
See also: gimp_plug_in_add_temp_procedure()
.
Since: 3.0
void gimp_plug_in_set_pdb_error_handler (GimpPlugIn *plug_in
,GimpPDBErrorHandler handler
);
Sets an error handler for procedure calls.
This procedure changes the way that errors in procedure calls are
handled. By default GIMP will raise an error dialog if a procedure
call made by a plug-in fails. Using this procedure the plug-in can
change this behavior. If the error handler is set to
GIMP_PDB_ERROR_HANDLER_PLUGIN
, then the plug-in is responsible for
calling gimp_pdb_get_last_error()
and handling the error whenever
one if its procedure calls fails. It can do this by displaying the
error message or by forwarding it in its own return values.
Since: 3.0
GimpPDBErrorHandler
gimp_plug_in_get_pdb_error_handler (GimpPlugIn *plug_in
);
Retrieves the active error handler for procedure calls.
This procedure retrieves the currently active error handler for
procedure calls made by the calling plug-in. See
gimp_plugin_set_pdb_error_handler()
for details.
Since: 3.0
struct GimpPlugInClass { GObjectClass parent_class; /** * GimpPlugInClass::query_procedures: * @plug_in: a #GimpPlugIn. * * Returns: (element-type gchar*) (transfer full): * the names of the procedures registered by @plug_in. **/ GList * (* query_procedures) (GimpPlugIn *plug_in); /** * GimpPlugInClass::init_procedures: * @plug_in: a #GimpPlugIn. * * Returns: (element-type gchar*) (transfer full): * the names of the procedures registered by @plug_in. **/ GList * (* init_procedures) (GimpPlugIn *plug_in); /** * GimpPlugInClass::create_procedure: * @plug_in: a #GimpPlugIn. * @procedure_name: procedure name. * * Returns: (transfer full): * 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. **/ void (* quit) (GimpPlugIn *plug_in); /* Padding for future expansion */ };
A class which every plug-in should subclass, while overriding
GimpPlugInClass.query_procedures()
and/or
GimpPlugInClass.init_procedures()
, as well as
GimpPlugInClass.create_procedure()
.
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
|
||
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 |
||
This method must be overridden by all plug-ins
and return a newly allocated GimpProcedure named |
||
This method can be overridden by a plug-in which needs to perform some actions upon quitting. |
Since: 3.0
“read-channel”
property“read-channel” GIOChannel *
The GIOChanel to read from GIMP.
Owner: GimpPlugIn
Flags: Read / Write / Construct Only
“write-channel”
property“write-channel” GIOChannel *
The GIOChanel to write to GIMP.
Owner: GimpPlugIn
Flags: Read / Write / Construct Only