![]() | ![]() | ![]() | GIMP Library Reference Manual | ![]() |
---|
gimp — Main functions needed for building a GIMP plug-in. This header includes all other GIMP Library headers.
#define GIMPVARgchar * gimp_version (void); extern const guint gimp_major_version; extern const guint gimp_minor_version; extern const guint gimp_micro_version; #define gimp_get_data #define gimp_get_data_size #define gimp_set_data void (*GimpInitProc) (void); void (*GimpQuitProc) (void); void (*GimpQueryProc) (void); void (*GimpRunProc) (gchar *name,gint nparams, GimpParam *param,gint *nreturn_vals, GimpParam **return_vals); struct GimpPlugInInfo; struct GimpParamDef; struct GimpParamColor; struct GimpParamRegion; union GimpParamData; struct GimpParam; #define MAIN ()gint gimp_main (const GimpPlugInInfo *info,gint argc,gchar *argv[]); void gimp_install_procedure (constgchar *name, constgchar *blurb, constgchar *help, constgchar *author, constgchar *copyright, constgchar *date, constgchar *menu_path, constgchar *image_types,GimpPDBProcType type,gint n_params,gint n_return_vals, GimpParamDef *params, GimpParamDef *return_vals); void gimp_install_temp_proc (constgchar *name, constgchar *blurb, constgchar *help, constgchar *author, constgchar *copyright, constgchar *date, constgchar *menu_path, constgchar *image_types,GimpPDBProcType type,gint n_params,gint n_return_vals, GimpParamDef *params, GimpParamDef *return_vals, GimpRunProc run_proc); void gimp_uninstall_temp_proc (constgchar *name); GimpParam* gimp_run_procedure (constgchar *name,gint *n_return_vals, ...); GimpParam* gimp_run_procedure2 (constgchar *name,gint *n_return_vals,gint n_params, GimpParam *params); void gimp_destroy_params (GimpParam *params,gint n_params); void gimp_destroy_paramdefs (GimpParamDef *paramdefs,gint n_params);guint gimp_tile_width (void);guint gimp_tile_height (void);gint gimp_shm_ID (void);guchar * gimp_shm_addr (void);gdouble gimp_gamma (void);gboolean gimp_install_cmap (void);gint gimp_min_colors (void);gboolean gimp_show_tool_tips (void);gint32 gimp_default_display (void); constgchar * gimp_get_progname (void); void gimp_extension_enable (void); void gimp_extension_ack (void); void gimp_extension_process (guint timeout);GimpParasite * gimp_parasite_find (gchar *name);gboolean gimp_parasite_list (gint *num_parasites,gchar ***parasites);gboolean gimp_parasite_attach (GimpParasite *parasite);gboolean gimp_parasite_detach (gchar *name); void gimp_attach_new_parasite (constgchar *name,gint flags,gint size, constgpointer data);
Main functions needed for building a GIMP plug-in. This header includes all other GIMP Library headers.
gchar * gimp_version (void);
Returns the host gimp version.
This procedure returns the version number of the currently running gimp.
Returns : | The gimp version. |
void (*GimpRunProc) (gchar *name,gint nparams, GimpParam *param,gint *nreturn_vals, GimpParam **return_vals);
name : | |
nparams : | |
param : | |
nreturn_vals : | |
return_vals : |
struct GimpPlugInInfo { /* called when the gimp application initially starts up */ GimpInitProc init_proc; /* called when the gimp application exits */ GimpQuitProc quit_proc; /* called by the gimp so that the plug-in can inform the * gimp of what it does. (ie. installing a procedure database * procedure). */ GimpQueryProc query_proc; /* called to run a procedure the plug-in installed in the * procedure database. */ GimpRunProc run_proc; };
union GimpParamData { gint32 d_int32; gint16 d_int16; gint8 d_int8; gdouble d_float; gchar *d_string; gint32 *d_int32array; gint16 *d_int16array; gint8 *d_int8array; gdouble *d_floatarray; gchar **d_stringarray; GimpRGB d_color; GimpParamRegion d_region; gint32 d_display; gint32 d_image; gint32 d_layer; gint32 d_layer_mask; gint32 d_channel; gint32 d_drawable; gint32 d_selection; gint32 d_boundary; gint32 d_path; gint32 d_unit; GimpParasite d_parasite; gint32 d_tattoo; GimpPDBStatusType d_status; };
#define MAIN()
A macro that expands to the appropriate
To use this macro, simply place a line that contains just the code MAIN() at the toplevel of your file. No semicolon should be used.
gint gimp_main (const GimpPlugInInfo *info,gint argc,gchar *argv[]);
The main procedure that must be called with the PLUG_IN_INFO structure and the 'argc' and 'argv' that are passed to "main".
info : | the PLUG_IN_INFO structure |
argc : | the number of arguments |
argv : | the arguments |
Returns : |
void gimp_install_procedure (constgchar *name, constgchar *blurb, constgchar *help, constgchar *author, constgchar *copyright, constgchar *date, constgchar *menu_path, constgchar *image_types,GimpPDBProcType type,gint n_params,gint n_return_vals, GimpParamDef *params, GimpParamDef *return_vals);
Installs a new procedure with the PDB (procedural database).
Call this function from within your Plug-In's
The name parameter is mandatory and should be unique, or it will overwrite an already existing procedure (overwrite procedures only if you know what you're doing).
The blurb, help, author, copyright and date parameters are optional but then you shouldn't write procedures without proper documentation, should you.
menu_path can be
type must be one of
NOTE: Unlike the GIMP 1.2 API,
Not calling gimp_extension_ack() from a
Additionally, a
name : | the procedure's name. |
blurb : | a short text describing what the procedure does. |
help : | the help text for the procedure (usually considerably longer than blurb). |
author : | the procedure's author(s). |
copyright : | the procedure's copyright. |
date : | the date the procedure was added. |
menu_path : | the procedure's menu path, or |
image_types : | the drawable types the procedure can handle. |
type : | the type of the procedure. |
n_params : | the number of parameters the procedure takes. |
n_return_vals : | the number of return values the procedure returns. |
params : | the procedure's parameters. |
return_vals : | the procedure's return values. |
void gimp_install_temp_proc (constgchar *name, constgchar *blurb, constgchar *help, constgchar *author, constgchar *copyright, constgchar *date, constgchar *menu_path, constgchar *image_types,GimpPDBProcType type,gint n_params,gint n_return_vals, GimpParamDef *params, GimpParamDef *return_vals, GimpRunProc run_proc);
Installs a new temporary procedure with the PDB (procedural database).
A temporary procedure is a procedure which is only available while one of your Plug-In's "real" procedures is running.
See gimp_install_procedure() for most details.
type must be
run_proc is the function which will be called to execute the procedure.
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 explicitely enable receiving of temporary procedure run requests using either gimp_extension_enable() or gimp_extension_process(). See this functions' documentation for details.
name : | the procedure's name. |
blurb : | a short text describing what the procedure does. |
help : | the help text for the procedure (usually considerably longer than blurb). |
author : | the procedure's author(s). |
copyright : | the procedure's copyright. |
date : | the date the procedure was added. |
menu_path : | the procedure's menu path, or |
image_types : | the drawable types the procedure can handle. |
type : | the type of the procedure. |
n_params : | the number of parameters the procedure takes. |
n_return_vals : | the number of return values the procedure returns. |
params : | the procedure's parameters. |
return_vals : | the procedure's return values. |
run_proc : | the function to call for executing the procedure. |
void gimp_uninstall_temp_proc (constgchar *name);
Uninstalls a temporary procedure which has previously been installed using gimp_install_temp_proc().
name : | the procedure's name |
GimpParam* gimp_run_procedure (constgchar *name,gint *n_return_vals, ...);
This function calls a GIMP procedure and returns its return values.
The procedure's parameters are given by a va_list in the format
(type, value, type, value) and must be terminated by
This function converts the va_list of parameters into an array and passes them to gimp_run_procedure2().
name : | the name of the procedure to run |
n_return_vals : | return location for the number of return values |
... : | list of procedure parameters |
Returns : | the procedure's return values. |
GimpParam* gimp_run_procedure2 (constgchar *name,gint *n_return_vals,gint n_params, GimpParam *params);
This function calls a GIMP procedure and returns its return values.
name : | the name of the procedure to run |
n_return_vals : | return location for the number of return values |
n_params : | the number of parameters the procedure takes. |
params : | the procedure's parameters array. |
Returns : | the procedure's return values. |
void gimp_destroy_params (GimpParam *params,gint n_params);
Destroys a GimpParam array as returned by gimp_run_procedure()
params : | the GimpParam array to destroy |
n_params : | the number of elements in the array |
void gimp_destroy_paramdefs (GimpParamDef *paramdefs,gint n_params);
Destroys a GimpParamDef array as returned by
paramdefs : | the GimpParamDef array to destroy |
n_params : | the number of elements in the array |
guint gimp_tile_width (void);
Returns the tile_width the GIMP is using. This is a constant value given at Plug-In config time.
Returns : | the tile_width |
guint gimp_tile_height (void);
Returns the tile_height the GIMP is using. This is a constant value given at Plug-In config time.
Returns : | the tile_height |
gint gimp_shm_ID (void);
Returns the shared memory ID used for passing tile data between the GIMP core and the Plug-In. This is a constant value given at Plug-In config time.
Returns : | the shared memory ID |
guchar * gimp_shm_addr (void);
Returns the address of the shared memory segment used for passing tile data between the GIMP core and the Plug-In. This is a constant value given at Plug-In config time.
Returns : | the shared memory address |
gdouble gimp_gamma (void);
Returns the global gamma value the GIMP and all its Plug-Ins should use. This is a constant value given at Plug-In config time.
NOTE: this feature is unimplemented.
Returns : | the gamma value |
gboolean gimp_install_cmap (void);
Returns whether or not the Plug-In should allocate an own colormap when running on an 8 bit display. This is a constant value given at Plug-In config time.
See also: gimp_min_colors()
Returns : | the install_cmap boolean |
gint gimp_min_colors (void);
Returns the minimum number of colors to use when allocating an own colormap on 8 bit displays. This is a constant value given at Plug-In config time.
See also: gimp_install_cmap()
Returns : | the minimum number of colors to allocate |
gboolean gimp_show_tool_tips (void);
Returns whether or not the Plug-In should show tooltips. This is a constant value given at Plug-In config time.
Returns : | the show_tool_tips boolean |
gint32 gimp_default_display (void);
Returns the default display ID. This corresponds to the display the running procedure's menu entry was invoked from. This is a constant value given at Plug-In config time.
Returns : | the default display ID |
constgchar * gimp_get_progname (void);
Returns the Plug-In's executable name.
Returns : | the executable name |
void gimp_extension_enable (void);
Enables asnychronous processing of messages from the main GIMP application.
Normally, a plug-in is not called by the GIMP except for the call to the procedure it implements. All subsequent communication is triggered by the plug-in and all messages sent from the GIMP to the plug-in are just answers to requests the plug-in made.
If the plug-in however registered temporary procedures using gimp_install_temp_proc(), it needs to be able to receive requests to execute them. Usually this will be done by running gimp_extension_process() in an endless loop.
If the plug-in cannot use gimp_extension_process(), i.e. if it has
a GUI and is hanging around in a
Note that the plug-in does not need to be a
See also: gimp_install_procedure(), gimp_install_temp_proc()
void gimp_extension_ack (void);
Notify the main GIMP application that the extension has been properly initialized and is ready to run.
This function must be called from every
procedure that was registered as
Subsequently, extensions can process temporary procedure run requests using either gimp_extension_enable() or gimp_extension_process().
See also: gimp_install_procedure(), gimp_install_temp_proc()
void gimp_extension_process (guint timeout);
Processes one message sent by the GIMP and returns.
Call this function in an endless loop after calling gimp_extension_ack() to process requests for running temporary procedures.
See gimp_extension_enable() for an asynchronous way of doing the same if running an endless loop is not an option.
See also: gimp_install_procedure(), gimp_install_temp_proc()
timeout : | The timeout (in ms) to use for the |
GimpParasite * gimp_parasite_find (gchar *name);
Finds the named parasite.
Finds and returns the named parasite that was previously attached to the gimp.
name : | The name of the parasite to find. |
Returns : | The found parasite. |
gboolean gimp_parasite_list (gint *num_parasites,gchar ***parasites);
List all parasites.
Returns a list of all currently attached parasites.
num_parasites : | The number of attached parasites. |
parasites : | The names of currently attached parasites. |
Returns : | TRUE on success. |
gboolean gimp_parasite_attach (GimpParasite *parasite);
Add a parasite to the gimp.
This procedure attaches a parasite to the gimp. It has no return values.
parasite : | The parasite to attach to the gimp. |
Returns : | TRUE on success. |
gboolean gimp_parasite_detach (gchar *name);
Removes a parasite from the gimp.
This procedure detaches a parasite from the gimp. It has no return values.
name : | The name of the parasite to detach from the gimp. |
Returns : | TRUE on success. |
void gimp_attach_new_parasite (constgchar *name,gint flags,gint size, constgpointer data);
Convenience function that creates a parasite and attaches it to the GIMP.
See Also: gimp_parasite_attach()
name : | the name of the |
flags : | the flags set on the |
size : | the size of the parasite data in bytes. |
data : | a pointer to the data attached with the |
<< Part II. GIMP Library | gimpbrushes >> |