From 5092a32e7542cf208247ea1b77b8a3d34a30ca4d Mon Sep 17 00:00:00 2001 From: Niels De Graef Date: Sat, 6 Jun 2020 13:22:57 +0200 Subject: [PATCH] gimpparamspecs: Add GIR annotations I assume that we won't need most of these explicitly in bindings, but _if_ it's needed, then it's best to make sure that people don't struggle because they don't have proper API without annotations. --- libgimpbase/gimpparamspecs.c | 251 +++++++++++++++++++++++++++++++++++ libgimpbase/gimpparamspecs.h | 42 +++--- 2 files changed, 272 insertions(+), 21 deletions(-) diff --git a/libgimpbase/gimpparamspecs.c b/libgimpbase/gimpparamspecs.c index 7a8e086648..281715dcfd 100644 --- a/libgimpbase/gimpparamspecs.c +++ b/libgimpbase/gimpparamspecs.c @@ -334,6 +334,14 @@ gimp_param_spec_uint8_array (const gchar *name, return G_PARAM_SPEC (array_spec); } +/** + * gimp_value_get_uint8_array: + * @value: A valid value of type %GIMP_TYPE_UINT8_ARRAY + * + * Gets the contents of a %GIMP_TYPE_UINT8_ARRAY #GValue + * + * Returns: (transfer none) (array): The contents of @value + */ const guint8 * gimp_value_get_uint8_array (const GValue *value) { @@ -342,6 +350,14 @@ gimp_value_get_uint8_array (const GValue *value) return gimp_value_get_array (value); } +/** + * gimp_value_dup_uint8_array: + * @value: A valid value of type %GIMP_TYPE_UINT8_ARRAY + * + * Gets the contents of a %GIMP_TYPE_UINT8_ARRAY #GValue + * + * Returns: (transfer full) (array): The contents of @value + */ guint8 * gimp_value_dup_uint8_array (const GValue *value) { @@ -350,6 +366,14 @@ gimp_value_dup_uint8_array (const GValue *value) return gimp_value_dup_array (value); } +/** + * gimp_value_set_uint8_array: + * @value: A valid value of type %GIMP_TYPE_UINT8_ARRAY + * @data: (array length=length): A #guint8 array + * @length: The number of elements in @data + * + * Sets the contents of @value to @data. + */ void gimp_value_set_uint8_array (GValue *value, const guint8 *data, @@ -360,6 +384,14 @@ gimp_value_set_uint8_array (GValue *value, gimp_value_set_array (value, data, length); } +/** + * gimp_value_set_static_uint8_array: + * @value: A valid value of type %GIMP_TYPE_UINT8_ARRAY + * @data: (array length=length): A #guint8 array + * @length: The number of elements in @data + * + * Sets the contents of @value to @data, without copying the data. + */ void gimp_value_set_static_uint8_array (GValue *value, const guint8 *data, @@ -370,6 +402,14 @@ gimp_value_set_static_uint8_array (GValue *value, gimp_value_set_static_array (value, data, length); } +/** + * gimp_value_take_uint8_array: + * @value: A valid value of type %GIMP_TYPE_UINT8_ARRAY + * @data: (transfer full) (array length=length): A #guint8 array + * @length: The number of elements in @data + * + * Sets the contents of @value to @data, and takes ownership of @data. + */ void gimp_value_take_uint8_array (GValue *value, guint8 *data, @@ -462,6 +502,14 @@ gimp_param_spec_int16_array (const gchar *name, return G_PARAM_SPEC (array_spec); } +/** + * gimp_value_get_int16_array: + * @value: A valid value of type %GIMP_TYPE_INT16_ARRAY + * + * Gets the contents of a %GIMP_TYPE_INT16_ARRAY #GValue + * + * Returns: (transfer none) (array): The contents of @value + */ const gint16 * gimp_value_get_int16_array (const GValue *value) { @@ -470,6 +518,14 @@ gimp_value_get_int16_array (const GValue *value) return (const gint16 *) gimp_value_get_array (value); } +/** + * gimp_value_dup_int16_array: + * @value: A valid value of type %GIMP_TYPE_INT16_ARRAY + * + * Gets the contents of a %GIMP_TYPE_INT16_ARRAY #GValue + * + * Returns: (transfer full) (array): The contents of @value + */ gint16 * gimp_value_dup_int16_array (const GValue *value) { @@ -478,6 +534,14 @@ gimp_value_dup_int16_array (const GValue *value) return (gint16 *) gimp_value_dup_array (value); } +/** + * gimp_value_set_int16_array: + * @value: A valid value of type %GIMP_TYPE_INT16_ARRAY + * @data: (array length=length): A #gint16 array + * @length: The number of elements in @data + * + * Sets the contents of @value to @data. + */ void gimp_value_set_int16_array (GValue *value, const gint16 *data, @@ -489,6 +553,14 @@ gimp_value_set_int16_array (GValue *value, length * sizeof (gint16)); } +/** + * gimp_value_set_static_int16_array: + * @value: A valid value of type %GIMP_TYPE_INT16_ARRAY + * @data: (array length=length): A #gint16 array + * @length: The number of elements in @data + * + * Sets the contents of @value to @data, without copying the data. + */ void gimp_value_set_static_int16_array (GValue *value, const gint16 *data, @@ -500,6 +572,14 @@ gimp_value_set_static_int16_array (GValue *value, length * sizeof (gint16)); } +/** + * gimp_value_take_int16_array: + * @value: A valid value of type %GIMP_TYPE_INT16_ARRAY + * @data: (transfer full) (array length=length): A #gint16 array + * @length: The number of elements in @data + * + * Sets the contents of @value to @data, and takes ownership of @data. + */ void gimp_value_take_int16_array (GValue *value, gint16 *data, @@ -592,6 +672,14 @@ gimp_param_spec_int32_array (const gchar *name, return G_PARAM_SPEC (array_spec); } +/** + * gimp_value_get_int32_array: + * @value: A valid value of type %GIMP_TYPE_INT32_ARRAY + * + * Gets the contents of a %GIMP_TYPE_INT32_ARRAY #GValue + * + * Returns: (transfer none) (array): The contents of @value + */ const gint32 * gimp_value_get_int32_array (const GValue *value) { @@ -600,6 +688,14 @@ gimp_value_get_int32_array (const GValue *value) return (const gint32 *) gimp_value_get_array (value); } +/** + * gimp_value_dup_int32_array: + * @value: A valid value of type %GIMP_TYPE_INT32_ARRAY + * + * Gets the contents of a %GIMP_TYPE_INT32_ARRAY #GValue + * + * Returns: (transfer full) (array): The contents of @value + */ gint32 * gimp_value_dup_int32_array (const GValue *value) { @@ -608,6 +704,14 @@ gimp_value_dup_int32_array (const GValue *value) return (gint32 *) gimp_value_dup_array (value); } +/** + * gimp_value_set_int32_array: + * @value: A valid value of type %GIMP_TYPE_INT32_ARRAY + * @data: (array length=length): A #gint32 array + * @length: The number of elements in @data + * + * Sets the contents of @value to @data. + */ void gimp_value_set_int32_array (GValue *value, const gint32 *data, @@ -619,6 +723,14 @@ gimp_value_set_int32_array (GValue *value, length * sizeof (gint32)); } +/** + * gimp_value_set_static_int32_array: + * @value: A valid value of type %GIMP_TYPE_INT32_ARRAY + * @data: (array length=length): A #gint32 array + * @length: The number of elements in @data + * + * Sets the contents of @value to @data, without copying the data. + */ void gimp_value_set_static_int32_array (GValue *value, const gint32 *data, @@ -630,6 +742,14 @@ gimp_value_set_static_int32_array (GValue *value, length * sizeof (gint32)); } +/** + * gimp_value_take_int32_array: + * @value: A valid value of type %GIMP_TYPE_int32_ARRAY + * @data: (transfer full) (array length=length): A #gint32 array + * @length: The number of elements in @data + * + * Sets the contents of @value to @data, and takes ownership of @data. + */ void gimp_value_take_int32_array (GValue *value, gint32 *data, @@ -722,6 +842,14 @@ gimp_param_spec_float_array (const gchar *name, return G_PARAM_SPEC (array_spec); } +/** + * gimp_value_get_float_array: + * @value: A valid value of type %GIMP_TYPE_FLOAT_ARRAY + * + * Gets the contents of a %GIMP_TYPE_FLOAT_ARRAY #GValue + * + * Returns: (transfer none) (array): The contents of @value + */ const gdouble * gimp_value_get_float_array (const GValue *value) { @@ -730,6 +858,14 @@ gimp_value_get_float_array (const GValue *value) return (const gdouble *) gimp_value_get_array (value); } +/** + * gimp_value_dup_float_array: + * @value: A valid value of type %GIMP_TYPE_FLOAT_ARRAY + * + * Gets the contents of a %GIMP_TYPE_FLOAT_ARRAY #GValue + * + * Returns: (transfer full) (array): The contents of @value + */ gdouble * gimp_value_dup_float_array (const GValue *value) { @@ -738,6 +874,14 @@ gimp_value_dup_float_array (const GValue *value) return (gdouble *) gimp_value_dup_array (value); } +/** + * gimp_value_set_float_array: + * @value: A valid value of type %GIMP_TYPE_FLOAT_ARRAY + * @data: (array length=length): A #gfloat array + * @length: The number of elements in @data + * + * Sets the contents of @value to @data. + */ void gimp_value_set_float_array (GValue *value, const gdouble *data, @@ -749,6 +893,14 @@ gimp_value_set_float_array (GValue *value, length * sizeof (gdouble)); } +/** + * gimp_value_set_static_float_array: + * @value: A valid value of type %GIMP_TYPE_FLOAT_ARRAY + * @data: (array length=length): A #gfloat array + * @length: The number of elements in @data + * + * Sets the contents of @value to @data, without copying the data. + */ void gimp_value_set_static_float_array (GValue *value, const gdouble *data, @@ -760,6 +912,14 @@ gimp_value_set_static_float_array (GValue *value, length * sizeof (gdouble)); } +/** + * gimp_value_take_float_array: + * @value: A valid value of type %GIMP_TYPE_FLOAT_ARRAY + * @data: (transfer full) (array length=length): A #gfloat array + * @length: The number of elements in @data + * + * Sets the contents of @value to @data, and takes ownership of @data. + */ void gimp_value_take_float_array (GValue *value, gdouble *data, @@ -1038,6 +1198,14 @@ gimp_value_dup_string_array (const GValue *value) return NULL; } +/** + * gimp_value_set_string_array: + * @value: A valid value of type %GIMP_TYPE_STRING_ARRAY + * @data: (array length=length): A string array + * @length: The number of elements in @data + * + * Sets the contents of @value to @data. + */ void gimp_value_set_string_array (GValue *value, const gchar **data, @@ -1052,6 +1220,14 @@ gimp_value_set_string_array (GValue *value, g_value_take_boxed (value, array); } +/** + * gimp_value_set_static_string_array: + * @value: A valid value of type %GIMP_TYPE_STRING_ARRAY + * @data: (array length=length): A string array + * @length: The number of elements in @data + * + * Sets the contents of @value to @data, without copying the data. + */ void gimp_value_set_static_string_array (GValue *value, const gchar **data, @@ -1066,6 +1242,14 @@ gimp_value_set_static_string_array (GValue *value, g_value_take_boxed (value, array); } +/** + * gimp_value_take_string_array: + * @value: A valid value of type %GIMP_TYPE_STRING_ARRAY + * @data: (transfer full) (array length=length): A string array + * @length: The number of elements in @data + * + * Sets the contents of @value to @data, and takes ownership of @data. + */ void gimp_value_take_string_array (GValue *value, gchar **data, @@ -1163,6 +1347,14 @@ gimp_param_spec_rgb_array (const gchar *name, return G_PARAM_SPEC (array_spec); } +/** + * gimp_value_get_rgb_array: + * @value: A valid value of type %GIMP_TYPE_RGB_ARRAY + * + * Gets the contents of a %GIMP_TYPE_RGB_ARRAY #GValue + * + * Returns: (transfer none) (array): The contents of @value + */ const GimpRGB * gimp_value_get_rgb_array (const GValue *value) { @@ -1171,6 +1363,14 @@ gimp_value_get_rgb_array (const GValue *value) return (const GimpRGB *) gimp_value_get_array (value); } +/** + * gimp_value_dup_rgb_array: + * @value: A valid value of type %GIMP_TYPE_RGB_ARRAY + * + * Gets the contents of a %GIMP_TYPE_RGB_ARRAY #GValue + * + * Returns: (transfer full) (array): The contents of @value + */ GimpRGB * gimp_value_dup_rgb_array (const GValue *value) { @@ -1179,6 +1379,14 @@ gimp_value_dup_rgb_array (const GValue *value) return (GimpRGB *) gimp_value_dup_array (value); } +/** + * gimp_value_set_rgb_array: + * @value: A valid value of type %GIMP_TYPE_RGB_ARRAY + * @data: (array length=length): A #GimpRGB array + * @length: The number of elements in @data + * + * Sets the contents of @value to @data. + */ void gimp_value_set_rgb_array (GValue *value, const GimpRGB *data, @@ -1190,6 +1398,14 @@ gimp_value_set_rgb_array (GValue *value, length * sizeof (GimpRGB)); } +/** + * gimp_value_set_static_rgb_array: + * @value: A valid value of type %GIMP_TYPE_RGB_ARRAY + * @data: (array length=length): A #GimpRGB array + * @length: The number of elements in @data + * + * Sets the contents of @value to @data, without copying the data. + */ void gimp_value_set_static_rgb_array (GValue *value, const GimpRGB *data, @@ -1201,6 +1417,14 @@ gimp_value_set_static_rgb_array (GValue *value, length * sizeof (GimpRGB)); } +/** + * gimp_value_take_rgb_array: + * @value: A valid value of type %GIMP_TYPE_RGB_ARRAY + * @data: (transfer full) (array length=length): A #GimpRGB array + * @length: The number of elements in @data + * + * Sets the contents of @value to @data, and takes ownership of @data. + */ void gimp_value_take_rgb_array (GValue *value, GimpRGB *data, @@ -1511,6 +1735,15 @@ gimp_value_dup_object_array (const GValue *value) return NULL; } +/** + * gimp_value_set_object_array: + * @value: A valid value of type %GIMP_TYPE_OBJECT_ARRAY + * @object_type: The #GType of the object elements + * @data: (array length=length): A #GObject array + * @length: The number of elements in @data + * + * Sets the contents of @value to @data. + */ void gimp_value_set_object_array (GValue *value, GType object_type, @@ -1527,6 +1760,15 @@ gimp_value_set_object_array (GValue *value, g_value_take_boxed (value, array); } +/** + * gimp_value_set_static_object_array: + * @value: A valid value of type %GIMP_TYPE_OBJECT_ARRAY + * @object_type: The #GType of the object elements + * @data: (array length=length): A #GObject array + * @length: The number of elements in @data + * + * Sets the contents of @value to @data, without copying the data. + */ void gimp_value_set_static_object_array (GValue *value, GType object_type, @@ -1543,6 +1785,15 @@ gimp_value_set_static_object_array (GValue *value, g_value_take_boxed (value, array); } +/** + * gimp_value_take_object_array: + * @value: A valid value of type %GIMP_TYPE_OBJECT_ARRAY + * @object_type: The #GType of the object elements + * @data: (transfer full) (array length=length): A #GObject array + * @length: The number of elements in @data + * + * Sets the contents of @value to @data, and takes ownership of @data. + */ void gimp_value_take_object_array (GValue *value, GType object_type, diff --git a/libgimpbase/gimpparamspecs.h b/libgimpbase/gimpparamspecs.h index 8ed24f93b8..a9c3831aee 100644 --- a/libgimpbase/gimpparamspecs.h +++ b/libgimpbase/gimpparamspecs.h @@ -163,13 +163,13 @@ GParamSpec * gimp_param_spec_uint8_array (const gchar *name, const guint8 * gimp_value_get_uint8_array (const GValue *value); guint8 * gimp_value_dup_uint8_array (const GValue *value); void gimp_value_set_uint8_array (GValue *value, - const guint8 *array, + const guint8 *data, gsize length); void gimp_value_set_static_uint8_array (GValue *value, - const guint8 *array, + const guint8 *data, gsize length); void gimp_value_take_uint8_array (GValue *value, - guint8 *array, + guint8 *data, gsize length); @@ -208,13 +208,13 @@ GParamSpec * gimp_param_spec_int16_array (const gchar *name, const gint16 * gimp_value_get_int16_array (const GValue *value); gint16 * gimp_value_dup_int16_array (const GValue *value); void gimp_value_set_int16_array (GValue *value, - const gint16 *array, + const gint16 *data, gsize length); void gimp_value_set_static_int16_array (GValue *value, - const gint16 *array, + const gint16 *data, gsize length); void gimp_value_take_int16_array (GValue *value, - gint16 *array, + gint16 *data, gsize length); @@ -253,13 +253,13 @@ GParamSpec * gimp_param_spec_int32_array (const gchar *name, const gint32 * gimp_value_get_int32_array (const GValue *value); gint32 * gimp_value_dup_int32_array (const GValue *value); void gimp_value_set_int32_array (GValue *value, - const gint32 *array, + const gint32 *data, gsize length); void gimp_value_set_static_int32_array (GValue *value, - const gint32 *array, + const gint32 *data, gsize length); void gimp_value_take_int32_array (GValue *value, - gint32 *array, + gint32 *data, gsize length); @@ -298,13 +298,13 @@ GParamSpec * gimp_param_spec_float_array (const gchar *name, const gdouble * gimp_value_get_float_array (const GValue *value); gdouble * gimp_value_dup_float_array (const GValue *value); void gimp_value_set_float_array (GValue *value, - const gdouble *array, + const gdouble *data, gsize length); void gimp_value_set_static_float_array (GValue *value, - const gdouble *array, + const gdouble *data, gsize length); void gimp_value_take_float_array (GValue *value, - gdouble *array, + gdouble *data, gsize length); @@ -364,13 +364,13 @@ GParamSpec * gimp_param_spec_string_array (const gchar *name, const gchar ** gimp_value_get_string_array (const GValue *value); gchar ** gimp_value_dup_string_array (const GValue *value); void gimp_value_set_string_array (GValue *value, - const gchar **array, + const gchar **data, gsize length); void gimp_value_set_static_string_array (GValue *value, - const gchar **array, + const gchar **data, gsize length); void gimp_value_take_string_array (GValue *value, - gchar **array, + gchar **data, gsize length); @@ -409,13 +409,13 @@ GParamSpec * gimp_param_spec_rgb_array (const gchar *name, const GimpRGB * gimp_value_get_rgb_array (const GValue *value); GimpRGB * gimp_value_dup_rgb_array (const GValue *value); void gimp_value_set_rgb_array (GValue *value, - const GimpRGB *array, + const GimpRGB *data, gsize length); void gimp_value_set_static_rgb_array (GValue *value, - const GimpRGB *array, + const GimpRGB *data, gsize length); void gimp_value_take_rgb_array (GValue *value, - GimpRGB *array, + GimpRGB *data, gsize length); @@ -482,15 +482,15 @@ GObject ** gimp_value_get_object_array (const GValue *value); GObject ** gimp_value_dup_object_array (const GValue *value); void gimp_value_set_object_array (GValue *value, GType object_type, - GObject **array, + GObject **data, gsize length); void gimp_value_set_static_object_array (GValue *value, GType object_type, - GObject **array, + GObject **data, gsize length); void gimp_value_take_object_array (GValue *value, GType object_type, - GObject **array, + GObject **data, gsize length);