mirror of https://github.com/GNOME/gimp.git
app, libgimp, pdb: improve gimp_image_get_layers() docs.
I always found the docs misleading because when it says "Returns the list of layers contained in the specified image", I really read "all the layers, at any level", except it doesn't. It only returns the root layers and it is up to the plug-in developer to loop through these if one needs to go deeper. So let's make the function docs clearer.
This commit is contained in:
parent
931b9fb539
commit
6dd48d1a82
|
@ -3266,8 +3266,9 @@ register_image_procs (GimpPDB *pdb)
|
|||
gimp_object_set_static_name (GIMP_OBJECT (procedure),
|
||||
"gimp-image-get-layers");
|
||||
gimp_procedure_set_static_help (procedure,
|
||||
"Returns the list of layers contained in the specified image.",
|
||||
"This procedure returns the list of layers contained in the specified image. The order of layers is from topmost to bottommost.",
|
||||
"Returns the list of root layers contained in the specified image.",
|
||||
"This procedure returns the list of root layers contained in the specified image. The order of layers is from topmost to bottommost.\n"
|
||||
"Note that this is not the full list of layers, but only the root layers, i.e. layers with no parents themselves. If you need all layers, it is up to you to verify that any of these layers is a group layer with 'gimp-item-is-group' and to obtain its children with 'gimp-item-get-children' (possibly recursively checking if these have children too).",
|
||||
NULL);
|
||||
gimp_procedure_set_static_attribution (procedure,
|
||||
"Spencer Kimball & Peter Mattis",
|
||||
|
@ -3282,7 +3283,7 @@ register_image_procs (GimpPDB *pdb)
|
|||
gimp_procedure_add_return_value (procedure,
|
||||
g_param_spec_int ("num-layers",
|
||||
"num layers",
|
||||
"The number of layers contained in the image",
|
||||
"The number of root layers contained in the image",
|
||||
0, G_MAXINT32, 0,
|
||||
GIMP_PARAM_READWRITE));
|
||||
gimp_procedure_add_return_value (procedure,
|
||||
|
|
|
@ -463,12 +463,18 @@ gimp_image_height (GimpImage *image)
|
|||
/**
|
||||
* gimp_image_get_layers:
|
||||
* @image: The image.
|
||||
* @num_layers: (out): The number of layers contained in the image.
|
||||
* @num_layers: (out): The number of root layers contained in the image.
|
||||
*
|
||||
* Returns the list of layers contained in the specified image.
|
||||
* Returns the list of root layers contained in the specified image.
|
||||
*
|
||||
* This procedure returns the list of layers contained in the specified
|
||||
* image. The order of layers is from topmost to bottommost.
|
||||
* This procedure returns the list of root layers contained in the
|
||||
* specified image. The order of layers is from topmost to bottommost.
|
||||
* Note that this is not the full list of layers, but only the root
|
||||
* layers, i.e. layers with no parents themselves. If you need all
|
||||
* layers, it is up to you to verify that any of these layers is a
|
||||
* group layer with gimp_item_is_group() and to obtain its children
|
||||
* with gimp_item_get_children() (possibly recursively checking if
|
||||
* these have children too).
|
||||
*
|
||||
* Returns: (array length=num_layers) (element-type GimpLayer) (transfer container):
|
||||
* The list of layers contained in the image.
|
||||
|
|
|
@ -238,11 +238,18 @@ CODE
|
|||
}
|
||||
|
||||
sub image_get_layers {
|
||||
$blurb = 'Returns the list of layers contained in the specified image.';
|
||||
$blurb = 'Returns the list of root layers contained in the specified image.';
|
||||
|
||||
$help = <<HELP;
|
||||
This procedure returns the list of layers contained in the specified image.
|
||||
This procedure returns the list of root layers contained in the specified image.
|
||||
The order of layers is from topmost to bottommost.
|
||||
|
||||
Note that this is not the full list of layers, but only the root layers,
|
||||
i.e. layers with no parents themselves. If you need all layers, it is up
|
||||
to you to verify that any of these layers is a group layer with
|
||||
gimp_item_is_group() and to obtain its children with
|
||||
gimp_item_get_children() (possibly recursively checking if these have
|
||||
children too).
|
||||
HELP
|
||||
|
||||
&std_pdb_misc;
|
||||
|
@ -256,7 +263,7 @@ HELP
|
|||
{ name => 'layers', type => 'layerarray',
|
||||
desc => 'The list of layers contained in the image.',
|
||||
array => { name => 'num_layers',
|
||||
desc => 'The number of layers contained in the image' } }
|
||||
desc => 'The number of root layers contained in the image' } }
|
||||
);
|
||||
|
||||
%invoke = (
|
||||
|
|
Loading…
Reference in New Issue