2004-05-19 06:54:41 +08:00
|
|
|
/* LIBGIMP - The GIMP Library
|
|
|
|
* Copyright (C) 1995-2003 Peter Mattis and Spencer Kimball
|
|
|
|
*
|
|
|
|
* gimpplugin.h
|
2019-07-31 06:12:36 +08:00
|
|
|
* Copyright (C) 2019 Michael Natterer <mitch@gimp.org>
|
2004-05-19 06:54:41 +08:00
|
|
|
*
|
2009-01-18 06:28:01 +08:00
|
|
|
* This library is free software: you can redistribute it and/or
|
2004-05-19 06:54:41 +08:00
|
|
|
* modify it under the terms of the GNU Lesser General Public
|
|
|
|
* License as published by the Free Software Foundation; either
|
2009-01-18 06:28:01 +08:00
|
|
|
* version 3 of the License, or (at your option) any later version.
|
2004-05-19 06:54:41 +08:00
|
|
|
*
|
|
|
|
* This library 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
|
|
|
|
* Lesser General Public License for more details.
|
|
|
|
*
|
|
|
|
* You should have received a copy of the GNU Lesser General Public
|
2009-01-18 06:28:01 +08:00
|
|
|
* License along with this library. If not, see
|
2018-07-12 05:27:07 +08:00
|
|
|
* <https://www.gnu.org/licenses/>.
|
2004-05-19 06:54:41 +08:00
|
|
|
*/
|
|
|
|
|
2011-04-29 01:59:52 +08:00
|
|
|
#if !defined (__GIMP_H_INSIDE__) && !defined (GIMP_COMPILATION)
|
|
|
|
#error "Only <libgimp/gimp.h> can be included directly."
|
|
|
|
#endif
|
|
|
|
|
2004-05-19 06:54:41 +08:00
|
|
|
#ifndef __GIMP_PLUG_IN_H__
|
|
|
|
#define __GIMP_PLUG_IN_H__
|
|
|
|
|
|
|
|
G_BEGIN_DECLS
|
|
|
|
|
|
|
|
/* For information look into the C source or the html documentation */
|
|
|
|
|
|
|
|
|
2019-07-26 05:07:24 +08:00
|
|
|
#define GIMP_TYPE_PLUG_IN (gimp_plug_in_get_type ())
|
|
|
|
#define GIMP_PLUG_IN(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GIMP_TYPE_PLUG_IN, GimpPlugIn))
|
|
|
|
#define GIMP_PLUG_IN_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), GIMP_TYPE_PLUG_IN, GimpPlugInClass))
|
|
|
|
#define GIMP_IS_PLUG_IN(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GIMP_TYPE_PLUG_IN))
|
|
|
|
#define GIMP_IS_PLUG_IN_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GIMP_TYPE_PLUG_IN))
|
|
|
|
#define GIMP_PLUG_IN_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GIMP_TYPE_PLUG_IN, GimpPlugInClass))
|
|
|
|
|
|
|
|
|
|
|
|
typedef struct _GimpPlugInClass GimpPlugInClass;
|
|
|
|
typedef struct _GimpPlugInPrivate GimpPlugInPrivate;
|
|
|
|
|
|
|
|
struct _GimpPlugIn
|
|
|
|
{
|
|
|
|
GObject parent_instance;
|
|
|
|
|
|
|
|
GimpPlugInPrivate *priv;
|
|
|
|
};
|
|
|
|
|
|
|
|
struct _GimpPlugInClass
|
|
|
|
{
|
|
|
|
GObjectClass parent_class;
|
|
|
|
|
2019-07-31 18:20:20 +08:00
|
|
|
/**
|
2019-08-02 18:05:28 +08:00
|
|
|
* GimpPlugInClass::query_procedures:
|
2019-07-31 18:20:20 +08:00
|
|
|
* @plug_in: a #GimpPlugIn.
|
|
|
|
*
|
2019-08-02 18:05:28 +08:00
|
|
|
* This method can be overridden by all plug-ins to return a newly
|
|
|
|
* allocated array of allocated strings naming the procedures
|
|
|
|
* registered by this plug-in.
|
|
|
|
* This array of strings must be NULL-terminated (i.e. freeable by
|
|
|
|
* g_strfreev()).
|
|
|
|
*
|
|
|
|
* See documentation of init_procedures() for differences.
|
|
|
|
*
|
libgimp, plug-ins: remove n_procedures from (init|query)_procedures().
The way currently implemented plug-ins are, they are already
NULL-terminating the returned arrays. Since a procedure name cannot be
NULL itself by definition, defining the array length by a terminal NULL
is enough. There is no need to also add a n_procedures parameters which
is just one more possible bug source, even more as we were already
expecting the NULL termination by using g_strfreev() to free the memory.
Anyway a length parameter does not bring any advantage since a plug-in
can still "lie" about its array size (just as it can forget to
NULL-terminate it) and when this happens, the plug-in will segfault.
That's it, it's just a plug-in programming error.
Last but not least, some binding seem to have issues with returned array
setting an (out) parameter as the length. In pygobject at least, the
length parameter doesn't disappear and we end up with this ugly
signature:
> In [3]: Gimp.PlugIn.do_query_procedures.__doc__
> Out[3]: 'query_procedures(self) -> list, n_procedures:int'
See bug report pygobject#352.
To avoid this, we should either set both the array and the length as
(out) parameters or just set the returned array as NULL-terminated
(which is the solution I chose).
2019-08-02 19:36:11 +08:00
|
|
|
* Returns: (array zero-terminated=1) (transfer full):
|
2019-08-02 18:05:28 +08:00
|
|
|
* the names of the procedures registered by @plug_in.
|
2019-07-31 18:20:20 +08:00
|
|
|
*/
|
libgimp, plug-ins: remove n_procedures from (init|query)_procedures().
The way currently implemented plug-ins are, they are already
NULL-terminating the returned arrays. Since a procedure name cannot be
NULL itself by definition, defining the array length by a terminal NULL
is enough. There is no need to also add a n_procedures parameters which
is just one more possible bug source, even more as we were already
expecting the NULL termination by using g_strfreev() to free the memory.
Anyway a length parameter does not bring any advantage since a plug-in
can still "lie" about its array size (just as it can forget to
NULL-terminate it) and when this happens, the plug-in will segfault.
That's it, it's just a plug-in programming error.
Last but not least, some binding seem to have issues with returned array
setting an (out) parameter as the length. In pygobject at least, the
length parameter doesn't disappear and we end up with this ugly
signature:
> In [3]: Gimp.PlugIn.do_query_procedures.__doc__
> Out[3]: 'query_procedures(self) -> list, n_procedures:int'
See bug report pygobject#352.
To avoid this, we should either set both the array and the length as
(out) parameters or just set the returned array as NULL-terminated
(which is the solution I chose).
2019-08-02 19:36:11 +08:00
|
|
|
gchar ** (* query_procedures) (GimpPlugIn *plug_in);
|
2019-07-26 08:05:11 +08:00
|
|
|
|
2019-07-31 18:20:20 +08:00
|
|
|
/**
|
2019-07-31 21:19:16 +08:00
|
|
|
* GimpPlugInClass::init_procedures:
|
2019-07-31 18:20:20 +08:00
|
|
|
* @plug_in: a #GimpPlugIn.
|
|
|
|
*
|
|
|
|
* This method can be overridden by all plug-ins to return a newly
|
|
|
|
* allocated array of allocated strings naming procedures registered
|
|
|
|
* by this plug-in.
|
|
|
|
* This array of strings must be NULL-terminated (i.e. freeable by
|
|
|
|
* g_strfreev()).
|
|
|
|
*
|
|
|
|
* It is different from 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 init_procedures()
|
|
|
|
* typically returns procedures dependent to runtime conditions (such
|
|
|
|
* as the presence of a third-party tool), whereas query_procedures()
|
|
|
|
* would usually return unconditional and always available procedures.
|
|
|
|
* Most of the time, you only want to override query_procedures() and
|
|
|
|
* leave init_procedures() untouched.
|
|
|
|
*
|
libgimp, plug-ins: remove n_procedures from (init|query)_procedures().
The way currently implemented plug-ins are, they are already
NULL-terminating the returned arrays. Since a procedure name cannot be
NULL itself by definition, defining the array length by a terminal NULL
is enough. There is no need to also add a n_procedures parameters which
is just one more possible bug source, even more as we were already
expecting the NULL termination by using g_strfreev() to free the memory.
Anyway a length parameter does not bring any advantage since a plug-in
can still "lie" about its array size (just as it can forget to
NULL-terminate it) and when this happens, the plug-in will segfault.
That's it, it's just a plug-in programming error.
Last but not least, some binding seem to have issues with returned array
setting an (out) parameter as the length. In pygobject at least, the
length parameter doesn't disappear and we end up with this ugly
signature:
> In [3]: Gimp.PlugIn.do_query_procedures.__doc__
> Out[3]: 'query_procedures(self) -> list, n_procedures:int'
See bug report pygobject#352.
To avoid this, we should either set both the array and the length as
(out) parameters or just set the returned array as NULL-terminated
(which is the solution I chose).
2019-08-02 19:36:11 +08:00
|
|
|
* Returns: (array zero-terminated=1) (transfer full):
|
2019-07-31 18:20:20 +08:00
|
|
|
* the names of the procedures registered by @plug_in.
|
|
|
|
*/
|
libgimp, plug-ins: remove n_procedures from (init|query)_procedures().
The way currently implemented plug-ins are, they are already
NULL-terminating the returned arrays. Since a procedure name cannot be
NULL itself by definition, defining the array length by a terminal NULL
is enough. There is no need to also add a n_procedures parameters which
is just one more possible bug source, even more as we were already
expecting the NULL termination by using g_strfreev() to free the memory.
Anyway a length parameter does not bring any advantage since a plug-in
can still "lie" about its array size (just as it can forget to
NULL-terminate it) and when this happens, the plug-in will segfault.
That's it, it's just a plug-in programming error.
Last but not least, some binding seem to have issues with returned array
setting an (out) parameter as the length. In pygobject at least, the
length parameter doesn't disappear and we end up with this ugly
signature:
> In [3]: Gimp.PlugIn.do_query_procedures.__doc__
> Out[3]: 'query_procedures(self) -> list, n_procedures:int'
See bug report pygobject#352.
To avoid this, we should either set both the array and the length as
(out) parameters or just set the returned array as NULL-terminated
(which is the solution I chose).
2019-08-02 19:36:11 +08:00
|
|
|
gchar ** (* init_procedures) (GimpPlugIn *plug_in);
|
2019-07-31 18:20:20 +08:00
|
|
|
/**
|
2019-07-31 21:19:16 +08:00
|
|
|
* GimpPlugInClass::create_procedure:
|
2019-07-31 18:20:20 +08:00
|
|
|
* @plug_in: a #GimpPlugIn.
|
|
|
|
* @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()
|
2019-08-02 08:30:07 +08:00
|
|
|
* and init_procedures() so care must be taken to handle them all.
|
2019-07-31 18:20:20 +08:00
|
|
|
*
|
2019-07-31 21:19:16 +08:00
|
|
|
* Returns: (transfer full):
|
|
|
|
* the procedure to be registered by @plug_in.
|
2019-07-31 18:20:20 +08:00
|
|
|
*/
|
2019-07-26 08:05:11 +08:00
|
|
|
GimpProcedure * (* create_procedure) (GimpPlugIn *plug_in,
|
|
|
|
const gchar *name);
|
2019-07-26 05:07:24 +08:00
|
|
|
|
2019-08-02 18:05:28 +08:00
|
|
|
/**
|
|
|
|
* GimpPlugInClass::quit:
|
|
|
|
* @plug_in: a #GimpPlugIn.
|
|
|
|
*
|
|
|
|
* This method can be overridden by a plug-in which needs to perform
|
|
|
|
* some actions upon quitting.
|
|
|
|
*/
|
|
|
|
void (* quit) (GimpPlugIn *plug_in);
|
|
|
|
|
2019-07-26 05:07:24 +08:00
|
|
|
/* Padding for future expansion */
|
|
|
|
void (* _gimp_reserved1) (void);
|
|
|
|
void (* _gimp_reserved2) (void);
|
|
|
|
void (* _gimp_reserved3) (void);
|
|
|
|
void (* _gimp_reserved4) (void);
|
|
|
|
void (* _gimp_reserved5) (void);
|
|
|
|
void (* _gimp_reserved6) (void);
|
|
|
|
void (* _gimp_reserved7) (void);
|
|
|
|
void (* _gimp_reserved8) (void);
|
|
|
|
};
|
|
|
|
|
|
|
|
|
2019-07-31 01:21:57 +08:00
|
|
|
GType gimp_plug_in_get_type (void) G_GNUC_CONST;
|
|
|
|
|
|
|
|
void gimp_plug_in_set_translation_domain (GimpPlugIn *plug_in,
|
|
|
|
const gchar *domain_name,
|
|
|
|
GFile *domain_path);
|
|
|
|
void gimp_plug_in_set_help_domain (GimpPlugIn *plug_in,
|
|
|
|
const gchar *domain_name,
|
|
|
|
GFile *domain_uri);
|
|
|
|
|
|
|
|
void gimp_plug_in_add_menu_branch (GimpPlugIn *plug_in,
|
|
|
|
const gchar *menu_path,
|
|
|
|
const gchar *menu_label);
|
|
|
|
|
|
|
|
GimpProcedure * gimp_plug_in_create_procedure (GimpPlugIn *plug_in,
|
|
|
|
const gchar *name);
|
|
|
|
|
2019-07-31 03:02:58 +08:00
|
|
|
void gimp_plug_in_add_temp_procedure (GimpPlugIn *plug_in,
|
2019-07-31 01:21:57 +08:00
|
|
|
GimpProcedure *procedure);
|
2019-07-31 03:02:58 +08:00
|
|
|
void gimp_plug_in_remove_temp_procedure (GimpPlugIn *plug_in,
|
2019-07-31 01:21:57 +08:00
|
|
|
const gchar *name);
|
|
|
|
|
2019-07-31 03:02:58 +08:00
|
|
|
GList * gimp_plug_in_get_temp_procedures (GimpPlugIn *plug_in);
|
|
|
|
GimpProcedure * gimp_plug_in_get_temp_procedure (GimpPlugIn *plug_in,
|
2019-07-31 01:21:57 +08:00
|
|
|
const gchar *name);
|
2019-07-26 05:07:24 +08:00
|
|
|
|
2019-08-02 17:06:48 +08:00
|
|
|
void gimp_plug_in_extension_enable (GimpPlugIn *plug_in);
|
|
|
|
void gimp_plug_in_extension_process (GimpPlugIn *plug_in,
|
|
|
|
guint timeout);
|
|
|
|
|
2019-07-26 05:07:24 +08:00
|
|
|
|
2004-05-19 06:54:41 +08:00
|
|
|
G_END_DECLS
|
|
|
|
|
|
|
|
#endif /* __GIMP_PLUG_IN_H__ */
|