… the public API.
This was initially proposed by Niels De Graef in !101, and though I
still think this is much less practical for day-to-day development, it
is actually much nicer for the public part of the API. So let's use
these only in public libgimp* API only, not in core.
I actually already started to use these for some of the libgimpwidgets
classes and am now moving libgimp main classes to these macros.
* It doesn't expose the priv member (which is completely useless for
plug-in developers, only to be used for core development).
* It forces us to never have any variable members in the public API
(which we were doing fine so far in newest API, but it's nice to be
enforced with these macros).
* When using G_DECLARE_FINAL_TYPE in particular, it adds flexibility as
we can change the structure size and the members order as these are
not exposed. And if some day, we make the class derivable with some
signals to handle, only then will we expose the class with some
_gimp_reserved* padding (instead of from the start when none is
needed). Therefore we will allow for further extension far in the
future.
Moreover most of these libgimp classes were so far not using any private
values, so we were declaring a `priv` member with a bogus contents just
"in case we needed it in future" (as we couldn't change the struct
size). So even the easiness of having a priv member was very relative
for this public API so far (unlike in core code where we actually have
much more complex interactions and using priv data all the time).
Even when the function names may have stayed the same in most cases, the
API has changed. The "Since:" tag must therefore be bumped.
Also adding docs for gimp_drawable_get_sub_thumbnail_data() which had
none.
- hand out and leak proxy object objects to legacy API like candy,
bypassing the factory in GimpPlugIn, because there is no plug-in
singleton.
- gimpgpcompat.c: image, item etc. are now objects, simply forgot this
file.
Turn all ID param specs into object param specs (e.g. GimpParamImageID
becomes GimpParamImage) and convert between IDs and objects in
gimpgpparams.c directly above the the wire protocol, so all of app/,
libgimp/ and plug-ins/ can deal directly with objects down to the
lowest level and not care about IDs.
Use the actual object param specs for procedure arguments and return
values again instead of a plain g_param_spec_object() and bring back
the none_ok parameter.
This implies changing the PDB type checking functions to work on pure
integers instead of IDs (one can't check whether object creation is
possible if performing that check requires the object to already
exist).
For example gimp_foo_is_valid() becomes gimp_foo_id_is_valid() and is
not involved in automatic object creation magic at the protocol
level. Added wrappers which still say gimp_foo_is_valid() and take the
respective objects.
Adapted all code, and it all becomes nicer and less convoluted, even
the generated PDB wrappers in app/ and libgimp/.
We now have both variants, one returning a GList, and another
returning an array. Turns out that while a list is often nicer,
sometimes a random-access array really keeps the code much simpler.
Adapt all plug-ins, and clean up a bit (like use g_list_reverse() once
instead of iterating the list reversed).
Turn GimpPlugIn into the main factory for all proxies and keep the
main hash tables there. The hash tables keep the initial reference.
For each GimpProcedure::run(), have s "sub-factory" which hands out
proxies to the actual procedure code. Each run() has hash tables of
its own which hold additional references. When run() is done, get rid
of its hash tables and their references, *and* drop the main plug-in
reference counts from the global hashes if the proxies' refcount has
dropped to one.
It is theoretically possible for an id to be reused. Normally here this
should not happen, since the previous item would have been removed from
the hash table anyway, when it got destroyed. Let's still be thorough.
I.e.: gimp_image_get_(layers|channels|vectors)(), gimp_image_list() and
gimp_item_get_children().
Instead of returning an array of IDs, these will now return a GList with
the right objects ready to use.
Jehan