Though I am not fond of these macros for our core code (it makes the
code more cumbersome especially for using private data in derivable
types), this definitely makes sense for public API, since it would allow
easier modifications with less chances of messing API/ABI stability.
Same for gimp_procedure_add_aux_argument() and gimp_procedure_add_return_value().
We now have specific public functions for every supported type and it's
in fact much better to use them. The generic functions gave the feeling
that we could use any GParamSpec as procedure argument, whereas we in
fact depend on what the PDB support, and only these subtypes.
These were created because of some limitation/bug in pygobject, which is
now much better worked around by having specific functions for every
argument type supported by the PDB.
Previous gimp_procedure_run_config() was in fact only good for private usage
inside the various run() methods for the different GimpProcedure subtypes. The
problem with this implementation is that the returned config object is not
complete. For instance, for a GimpLoadProcedure, the "run-mode" and "file"
properties are not part of the config object so you cannot call a
GimpLoadProcedure with any of the gimp_procedure_run*() functions.
Note: we had some working usage, e.g. in file-openraster, but only because it
was running the load procedure as a GimpPDBProcedure whose returned config
object was indeed always complete!
As a consequence, I rename gimp_procedure_run_config() as an internal-only
function _gimp_procedure_create_run_config() and I create a new
gimp_procedure_run_config() which always return a full config with all
arguments.
The gimp_procedure_run() already existed, though it was with an ordered
GimpValueArray array of arguments. Its usage feels redundant to the series of
gimp_pdb_run_procedure*() functions (which is confusing), but
gimp_procedure_run() was actually a bit more generic, because it does not
necessarily calls GimpProcedure-s through the PDB! For instance, it can runs a
local GimpProcedure, such as the case of one procedure which would want to call
another procedure in the same plug-in, but without having to go through PDB. Of
course, for local code, you may as well run relevant functions directly, yet it
makes sense that if one of the redundant-looking function is removed, it should
be the more specific one. Also gimp_procedure_run() feels a lot simpler and
logical, API wise.
A main difference in usage is that now, plug-in developers have to first
explicitly look up the GimpPdbProcedure with gimp_pdb_lookup_procedure() when
they wish to call PDB procedures on the wire. This was done anyway in the
gimp_pdb_run_procedure*() code, now it's explicit (rather than calling by name
directly).
Concretely:
* gimp_pdb_run_procedure(), gimp_pdb_run_procedure_config() and
gimp_pdb_run_procedure_valist() are removed.
* gimp_procedure_run() API is modified to use a variable args list instead of a
GimpValueArray.
* gimp_procedure_run_config() and gimp_procedure_run_valist() are added.
* gimp_procedure_run_config() in particular will be the one used in bindings
which don't have variable args support through a (rename-to
gimp_procedure_run) annotation.
While we definitely should not use this inside app/, because having the private
structure easily accessible as a member is very convenient, it is clear that it
makes for a much nicer public signature. Also the priv member is of no help to
third-party developers using this API to make plug-ins and is better hidden in
such a case.
This new function is meant to replace gimp_procedure_new() when all plug-in
usage will have been switched.
This function creates the GimpProcedureConfig object on behalf of the plug-in
and calls gimp_procedure_config_begin_run() and gimp_procedure_config_end_run().
This way we ensure that all plug-in calls with successful result are properly
stored without asking the developer not to forget to call these (if a "good
practice" is in fact something we request to do every time, especially for good
user experience, we might as well make it rather a core process).
Advantages:
* Better interactive experience: using any plug-in will result in saved
previously used settings.
* for developers, working on config objects is also much more comfortable than
working on GValueArray;
* step forward for the future macro infrastructure: if we can ensure that all
plug-in calls are properly logged, then we can replay plug-in actions, in
NON_INTERACTIVE with the same settings.
When GIMP_PROCEDURE_SENSITIVE_NO_IMAGE is set on a GimpImageProcedure,
add GIMP_PARAM_NO_VALIDATE to the param spec flags, allowing to pass a
NULL image.
The new function gimp_procedure_set_sensitivity_mask() allows plug-ins
to tell when a procedure should be marked as sensitive or not.
gimp_procedure_get_sensitivity_mask() retrieves this information.
Currently plug-ins are automatically marked as sensitive when an image
is present and a single drawable is selected. Nowadays, we can have
multiple selected layers so we should allow plug-ins to tell us if they
support working on multiple drawables. Actually we could even imagine
new plug-ins which would be made to work only on multiple drawables.
Oppositely, there are a lot of plug-ins which don't care at all if any
drawable is selected at all (so we should allow no drawable selected).
Finally why not even imagine plug-ins which don't care if no image is
shown? E.g. plug-ins to create new images or whatnot. This new API
allows our core to know all this and show procedure sensitivity
accordingly. By default, when the function is not called, the 1 image
with 1 drawable selected case is the default, allowing existing plug-ins
easier update.
Note: this only handles the sensitivity part right now. A plug-in which
would advertize working on several layer would still not work, because
the core won't allow sending several layers. It's coming in further
commits.
which can be set to GIMP_ARGUMENT_SYNC_NONE (the default) or
GIMP_ARGUMENT_SYNC_PARASITE, which indicates that the argument should
be synced with an image parasite of the same name.
Aux arguments are arbitrary values the procedure wants managed and
remembered across invocations in GimpProcedureConfig. They are not
passed to run() and are not known to the PDB, they only exist in the
procedure's config object.
Though it is still possible to use an image ID as procedure parameter,
it is now possible to pass a GimpImage GParamSpecObject.
Over the wire, this will transform back and forth into a GimpImageID,
totally transparently for the plug-in which will only always get a
GimpImage.
which are GimpProcedure subclasses with API to register as load/save
handlers and their own kind of run functions that get their standard
arguments passed directly instead of packed into a GimpValueArray.
They also register their standard arguments themselves, which removes
quite some boilerplate from load/save plug-ins.
Remove gimpprocedure-private.[ch] because install() and uninstall()
are now virtual functions of GimpProcedure.
because they are deprecated.
Change GIMP_ICON_TYPE_INLINE_PIXBUF to GIMP_ICON_TYPE_PIXBUF and the
libgimp API to (icon-name, GdkPixbuf, GFile). Use the file's uri and a
PNG blob of the pixbuf to pass around on the wire and for storage in
pluginrc.
gimp_procedure_set_icon() and gimp_procedure_get_icon() are not very
nice functions for bindings. They are still usable, but in most
bindings, the data parameter/returned value would end up like a uint
list which you'd want to convert to a string in the icon name or file
path case. It's still possible but very cumbersome.
Instead, I skip both functions for bindings and create specific
gimp_procedure_set_icon_*() and gimp_procedure_get_icon_*() functions,
which are much more binding-friendly.
for procedure arguments. This implies creating a new value array in
gimp_procedure_run() if the passed array is too short, instead of
just appending to the passed array, which was ugly anyway.
The idea is that we already have a GimpProcedure object in libgimp
which has name, help, blurb, arguments, return values and everything,
so we really don't need a parallel API to query PDB procedures for
their properties.
- make run() a virtual function of GimpProcedure
- move GIMP_PDB_ERROR to GimpPDB
- GimpPDBProcedure is a trivial subblass which populates
GimpProcedure's members by querying the PDB.
- make "plug-in", "procedure-type" and "name" construct-only
properties of GimpProcedure.
This is all work in progress.
This will be used at least for the Python plug-ins. There is currently a
bug preventing to set a GParamSpec in a binded API.
See pygobject#227.
Please don't revert this. At least it allows to use the new GimpPlugIn
API for Python plug-ins. Anyway even with the old API, I had to add ugly
temporary API for the introspection (which I will now remove as they
never made it to release). So we are trading an ugly situation for a
less ugly one.
We can always remove these 2 new functions before release if we find or
implement better solutions before.
which must be called by GIMP_EXTENSION procedures when they are ready
to run their temporary procedures. Move gimp_extension_ack() to
gimpobsolete.[ch].
... gimp_procedure_new_return_values().
When we see how this has been used in help or goat-exercise plug-ins so
far, we clearly see that we expect this function to be used as last call
in a run callback. Well we could save the result, free the error, then
return the result, but it's cumbersome.
So instead let's officially expect gimp_procedure_new_return_values() to
take ownership of the GError (i.e. it will free it in the end).
For this reason, remove the `const`.
- Change the wire protocol's GPProcInstall to transmit the entire
information needed for constructing all GParamSpecs we use, don't
use GimpPDBArgType in GPProcInstall but an enum private to the wire
protocol plus the GParamSpec's GType name. Bump the wire protocol
version.
- Add gimpgpparamspecs.[ch] in both app/plug-in/ and libgimp/ which
take care of converting between GPParamDef and GParamSpec. They
share code as far as possible.
- Change pluginrc writing and parsing to re-use GPParamDef and the
utility functions from gimpgpparamspecs.
- Remove gimp_pdb_compat_param_spec() from app/pdb/gimp-pdb-compat.[ch],
the entire core uses proper GParamSpecs from the wire protocol now,
the whole file will follow down the drain once we use a GValue
representation on the wire too.
- In gimp_plug_in_handle_proc_install(), change the "run-mode"
parameter to a GParamSpecEnum(GIMP_TYPE_RUN_MODE) (if it is not
already an enum). and change all places in app/ to treat it as an
enum value.
- plug-ins: fix cml-explorer to register correctly, a typo in
"run-mode" was never noticed until now.
- Add gimpgpcompat.[ch] in libgimp to deal with all the transforms
between old-style wire communication and using GParamSpec and
GValue, it contains some functions that are subject to change or
even removal in the next steps.
- Change the libgimp GimpProcedure and GimpPlugIn in many ways to be
able to actually install procedures the new way.
- plug-ins: change goat-exercise to completely use the new GimpPlugIn
and GimpProcedure API, look here to see how plug-ins will look in
the future, of course subject to change until this is finished.
- Next: changing GPParam to transmit all information about a GValue.
Mostly the same code as GimpProcedure in app/pdb/.
Move the "run" function to GimpProcedure. Add API to GimpPlugIn to
list and create procedures, and always keep a list of the plug-ins
procedures around. Still only using the old params and return_vals.
Jehan