From 51a558bc2aa3f69671190ce7f21cb6d0005f92ca Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sun, 14 Feb 2021 16:40:19 -0500 Subject: docs: Port PangoAttribute to the new doc format Replace gtk-doc'isms and use gi-docgen links instead. --- pango/pango-attributes.c | 796 +++++++++++++++++++++++------------------------ pango/pango-attributes.h | 189 +++++------ 2 files changed, 494 insertions(+), 491 deletions(-) diff --git a/pango/pango-attributes.c b/pango/pango-attributes.c index 85640b34..b607445a 100644 --- a/pango/pango-attributes.c +++ b/pango/pango-attributes.c @@ -10,7 +10,7 @@ * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Library General Public License for more details. * * You should have received a copy of the GNU Library General Public @@ -27,17 +27,17 @@ #include "pango-impl-utils.h" static PangoAttribute *pango_attr_color_new (const PangoAttrClass *klass, - guint16 red, - guint16 green, - guint16 blue); + guint16 red, + guint16 green, + guint16 blue); static PangoAttribute *pango_attr_string_new (const PangoAttrClass *klass, - const char *str); + const char *str); static PangoAttribute *pango_attr_int_new (const PangoAttrClass *klass, - int value); + int value); static PangoAttribute *pango_attr_float_new (const PangoAttrClass *klass, - double value); + double value); static PangoAttribute *pango_attr_size_new_internal (int size, - gboolean absolute); + gboolean absolute); G_LOCK_DEFINE_STATIC (attr_type); @@ -47,11 +47,11 @@ static GHashTable *name_map = NULL; /* MT-safe */ * pango_attr_type_register: * @name: an identifier for the type * - * Allocate a new attribute type ID. The attribute type name can be accessed - * later by using pango_attr_type_get_name(). + * Allocate a new attribute type ID. The attribute type name can be accessed + * later by using [func@attr_type_get_name]. * * Return value: the new type ID. - **/ + */ PangoAttrType pango_attr_type_register (const gchar *name) { @@ -65,7 +65,7 @@ pango_attr_type_register (const gchar *name) if (name) { if (G_UNLIKELY (!name_map)) - name_map = g_hash_table_new (NULL, NULL); + name_map = g_hash_table_new (NULL, NULL); g_hash_table_insert (name_map, GUINT_TO_POINTER (type), (gpointer) g_intern_string (name)); } @@ -80,16 +80,16 @@ pango_attr_type_register (const gchar *name) * @type: an attribute type ID to fetch the name for * * Fetches the attribute type name passed in when registering the type using - * pango_attr_type_register(). + * [func@attr_type_register]. * * The returned value is an interned string (see g_intern_string() for what * that means) that should not be modified or freed. * * Return value: (nullable): the type ID name (which may be %NULL), or - * %NULL if @type is a built-in Pango attribute type or invalid. + * %NULL if @type is a built-in Pango attribute type or invalid. * * Since: 1.22 - **/ + */ const char * pango_attr_type_get_name (PangoAttrType type) { @@ -107,20 +107,19 @@ pango_attr_type_get_name (PangoAttrType type) /** * pango_attribute_init: - * @attr: a #PangoAttribute - * @klass: a #PangoAttrClass + * @attr: a `PangoAttribute` + * @klass: a `PangoAttrClass` * - * Initializes @attr's klass to @klass, - * it's start_index to %PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING - * and end_index to %PANGO_ATTR_INDEX_TO_TEXT_END - * such that the attribute applies + * Initializes @attr's klass to @klass, it's start_index to + * %PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING and end_index to + * %PANGO_ATTR_INDEX_TO_TEXT_END such that the attribute applies * to the entire text by default. * * Since: 1.20 - **/ + */ void pango_attribute_init (PangoAttribute *attr, - const PangoAttrClass *klass) + const PangoAttrClass *klass) { g_return_if_fail (attr != NULL); g_return_if_fail (klass != NULL); @@ -132,13 +131,13 @@ pango_attribute_init (PangoAttribute *attr, /** * pango_attribute_copy: - * @attr: a #PangoAttribute + * @attr: a `PangoAttribute` * * Make a copy of an attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attribute_copy (const PangoAttribute *attr) { @@ -155,10 +154,10 @@ pango_attribute_copy (const PangoAttribute *attr) /** * pango_attribute_destroy: - * @attr: a #PangoAttribute. + * @attr: a `PangoAttribute`. * - * Destroy a #PangoAttribute and free all associated memory. - **/ + * Destroy a `PangoAttribute` and free all associated memory. + */ void pango_attribute_destroy (PangoAttribute *attr) { @@ -173,18 +172,18 @@ G_DEFINE_BOXED_TYPE (PangoAttribute, pango_attribute, /** * pango_attribute_equal: - * @attr1: a #PangoAttribute - * @attr2: another #PangoAttribute + * @attr1: a `PangoAttribute` + * @attr2: another `PangoAttribute` * * Compare two attributes for equality. This compares only the * actual value of the two attributes and not the ranges that the * attributes apply to. * * Return value: %TRUE if the two attributes have the same value. - **/ + */ gboolean pango_attribute_equal (const PangoAttribute *attr1, - const PangoAttribute *attr2) + const PangoAttribute *attr2) { g_return_val_if_fail (attr1 != NULL, FALSE); g_return_val_if_fail (attr2 != NULL, FALSE); @@ -212,14 +211,14 @@ pango_attr_string_destroy (PangoAttribute *attr) static gboolean pango_attr_string_equal (const PangoAttribute *attr1, - const PangoAttribute *attr2) + const PangoAttribute *attr2) { return strcmp (((PangoAttrString *)attr1)->value, ((PangoAttrString *)attr2)->value) == 0; } static PangoAttribute * pango_attr_string_new (const PangoAttrClass *klass, - const char *str) + const char *str) { PangoAttrString *result = g_slice_new (PangoAttrString); pango_attribute_init (&result->attr, klass); @@ -234,9 +233,9 @@ pango_attr_string_new (const PangoAttrClass *klass, * * Create a new font family attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute` + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attr_family_new (const char *family) { @@ -268,7 +267,7 @@ pango_attr_language_destroy (PangoAttribute *attr) static gboolean pango_attr_language_equal (const PangoAttribute *attr1, - const PangoAttribute *attr2) + const PangoAttribute *attr2) { return ((PangoAttrLanguage *)attr1)->value == ((PangoAttrLanguage *)attr2)->value; } @@ -279,9 +278,9 @@ pango_attr_language_equal (const PangoAttribute *attr1, * * Create a new language tag attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attr_language_new (PangoLanguage *language) { @@ -307,9 +306,9 @@ pango_attr_color_copy (const PangoAttribute *attr) const PangoAttrColor *color_attr = (PangoAttrColor *)attr; return pango_attr_color_new (attr->klass, - color_attr->color.red, - color_attr->color.green, - color_attr->color.blue); + color_attr->color.red, + color_attr->color.green, + color_attr->color.blue); } static void @@ -322,21 +321,21 @@ pango_attr_color_destroy (PangoAttribute *attr) static gboolean pango_attr_color_equal (const PangoAttribute *attr1, - const PangoAttribute *attr2) + const PangoAttribute *attr2) { const PangoAttrColor *color_attr1 = (const PangoAttrColor *)attr1; const PangoAttrColor *color_attr2 = (const PangoAttrColor *)attr2; return (color_attr1->color.red == color_attr2->color.red && - color_attr1->color.blue == color_attr2->color.blue && - color_attr1->color.green == color_attr2->color.green); + color_attr1->color.blue == color_attr2->color.blue && + color_attr1->color.green == color_attr2->color.green); } static PangoAttribute * pango_attr_color_new (const PangoAttrClass *klass, - guint16 red, - guint16 green, - guint16 blue) + guint16 red, + guint16 green, + guint16 blue) { PangoAttrColor *result = g_slice_new (PangoAttrColor); pango_attribute_init (&result->attr, klass); @@ -355,13 +354,13 @@ pango_attr_color_new (const PangoAttrClass *klass, * * Create a new foreground color attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attr_foreground_new (guint16 red, - guint16 green, - guint16 blue) + guint16 green, + guint16 blue) { static const PangoAttrClass klass = { PANGO_ATTR_FOREGROUND, @@ -381,13 +380,13 @@ pango_attr_foreground_new (guint16 red, * * Create a new background color attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attr_background_new (guint16 red, - guint16 green, - guint16 blue) + guint16 green, + guint16 blue) { static const PangoAttrClass klass = { PANGO_ATTR_BACKGROUND, @@ -417,7 +416,7 @@ pango_attr_int_destroy (PangoAttribute *attr) static gboolean pango_attr_int_equal (const PangoAttribute *attr1, - const PangoAttribute *attr2) + const PangoAttribute *attr2) { const PangoAttrInt *int_attr1 = (const PangoAttrInt *)attr1; const PangoAttrInt *int_attr2 = (const PangoAttrInt *)attr2; @@ -427,7 +426,7 @@ pango_attr_int_equal (const PangoAttribute *attr1, static PangoAttribute * pango_attr_int_new (const PangoAttrClass *klass, - int value) + int value) { PangoAttrInt *result = g_slice_new (PangoAttrInt); pango_attribute_init (&result->attr, klass); @@ -454,7 +453,7 @@ pango_attr_float_destroy (PangoAttribute *attr) static gboolean pango_attr_float_equal (const PangoAttribute *attr1, - const PangoAttribute *attr2) + const PangoAttribute *attr2) { const PangoAttrFloat *float_attr1 = (const PangoAttrFloat *)attr1; const PangoAttrFloat *float_attr2 = (const PangoAttrFloat *)attr2; @@ -464,7 +463,7 @@ pango_attr_float_equal (const PangoAttribute *attr1, static PangoAttribute* pango_attr_float_new (const PangoAttrClass *klass, - double value) + double value) { PangoAttrFloat *result = g_slice_new (PangoAttrFloat); pango_attribute_init (&result->attr, klass); @@ -494,7 +493,7 @@ pango_attr_size_destroy (PangoAttribute *attr) static gboolean pango_attr_size_equal (const PangoAttribute *attr1, - const PangoAttribute *attr2) + const PangoAttribute *attr2) { const PangoAttrSize *size_attr1 = (const PangoAttrSize *)attr1; const PangoAttrSize *size_attr2 = (const PangoAttrSize *)attr2; @@ -504,7 +503,7 @@ pango_attr_size_equal (const PangoAttribute *attr1, static PangoAttribute * pango_attr_size_new_internal (int size, - gboolean absolute) + gboolean absolute) { PangoAttrSize *result; @@ -535,9 +534,9 @@ pango_attr_size_new_internal (int size, * * Create a new font-size attribute in fractional points. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attr_size_new (int size) { @@ -550,11 +549,11 @@ pango_attr_size_new (int size) * * Create a new font-size attribute in device units. * - * Return value: the newly allocated #PangoAttribute, which should be - * freed with pango_attribute_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.8 - **/ + */ PangoAttribute * pango_attr_size_new_absolute (int size) { @@ -567,9 +566,9 @@ pango_attr_size_new_absolute (int size) * * Create a new font slant style attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attr_style_new (PangoStyle style) { @@ -589,9 +588,9 @@ pango_attr_style_new (PangoStyle style) * * Create a new font weight attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attr_weight_new (PangoWeight weight) { @@ -609,11 +608,11 @@ pango_attr_weight_new (PangoWeight weight) * pango_attr_variant_new: * @variant: the variant * - * Create a new font variant attribute (normal or small caps) + * Create a new font variant attribute (normal or small caps). * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attr_variant_new (PangoVariant variant) { @@ -631,11 +630,11 @@ pango_attr_variant_new (PangoVariant variant) * pango_attr_stretch_new: * @stretch: the stretch * - * Create a new font stretch attribute + * Create a new font stretch attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attr_stretch_new (PangoStretch stretch) { @@ -668,14 +667,14 @@ pango_attr_font_desc_destroy (PangoAttribute *attr) static gboolean pango_attr_font_desc_equal (const PangoAttribute *attr1, - const PangoAttribute *attr2) + const PangoAttribute *attr2) { const PangoAttrFontDesc *desc_attr1 = (const PangoAttrFontDesc *)attr1; const PangoAttrFontDesc *desc_attr2 = (const PangoAttrFontDesc *)attr2; return pango_font_description_get_set_fields (desc_attr1->desc) == pango_font_description_get_set_fields (desc_attr2->desc) && - pango_font_description_equal (desc_attr1->desc, desc_attr2->desc); + pango_font_description_equal (desc_attr1->desc, desc_attr2->desc); } /** @@ -686,9 +685,9 @@ pango_attr_font_desc_equal (const PangoAttribute *attr1, * allows setting family, style, weight, variant, stretch, * and size simultaneously. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attr_font_desc_new (const PangoFontDescription *desc) { @@ -713,9 +712,9 @@ pango_attr_font_desc_new (const PangoFontDescription *desc) * * Create a new underline-style attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attr_underline_new (PangoUnderline underline) { @@ -739,15 +738,15 @@ pango_attr_underline_new (PangoUnderline underline) * modifies the color of underlines. If not set, underlines * will use the foreground color. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.8 - **/ + */ PangoAttribute * pango_attr_underline_color_new (guint16 red, - guint16 green, - guint16 blue) + guint16 green, + guint16 blue) { static const PangoAttrClass klass = { PANGO_ATTR_UNDERLINE_COLOR, @@ -765,9 +764,9 @@ pango_attr_underline_color_new (guint16 red, * * Create a new strike-through attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attr_strikethrough_new (gboolean strikethrough) { @@ -791,15 +790,15 @@ pango_attr_strikethrough_new (gboolean strikethrough) * modifies the color of strikethrough lines. If not set, strikethrough * lines will use the foreground color. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.8 - **/ + */ PangoAttribute * pango_attr_strikethrough_color_new (guint16 red, - guint16 green, - guint16 blue) + guint16 green, + guint16 blue) { static const PangoAttrClass klass = { PANGO_ATTR_STRIKETHROUGH_COLOR, @@ -814,13 +813,13 @@ pango_attr_strikethrough_color_new (guint16 red, /** * pango_attr_rise_new: * @rise: the amount that the text should be displaced vertically, - * in Pango units. Positive values displace the text upwards. + * in Pango units. Positive values displace the text upwards. * * Create a new baseline displacement attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attr_rise_new (int rise) { @@ -841,9 +840,9 @@ pango_attr_rise_new (int rise) * Create a new font size scale attribute. The base font for the * affected text will have its size multiplied by @scale_factor. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute* pango_attr_scale_new (double scale_factor) { @@ -860,7 +859,7 @@ pango_attr_scale_new (double scale_factor) /** * pango_attr_fallback_new: * @enable_fallback: %TRUE if we should fall back on other fonts - * for characters the active font is missing. + * for characters the active font is missing. * * Create a new font fallback attribute. * @@ -869,11 +868,11 @@ pango_attr_scale_new (double scale_factor) * other fonts on the system that might contain the characters in the * text. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.4 - **/ + */ PangoAttribute * pango_attr_fallback_new (gboolean enable_fallback) { @@ -894,11 +893,11 @@ pango_attr_fallback_new (gboolean enable_fallback) * * Create a new letter-spacing attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.6 - **/ + */ PangoAttribute * pango_attr_letter_spacing_new (int letter_spacing) { @@ -924,7 +923,7 @@ pango_attr_shape_copy (const PangoAttribute *attr) data = shape_attr->data; return pango_attr_shape_new_with_data (&shape_attr->ink_rect, &shape_attr->logical_rect, - data, shape_attr->copy_func, shape_attr->destroy_func); + data, shape_attr->copy_func, shape_attr->destroy_func); } static void @@ -940,48 +939,46 @@ pango_attr_shape_destroy (PangoAttribute *attr) static gboolean pango_attr_shape_equal (const PangoAttribute *attr1, - const PangoAttribute *attr2) + const PangoAttribute *attr2) { const PangoAttrShape *shape_attr1 = (const PangoAttrShape *)attr1; const PangoAttrShape *shape_attr2 = (const PangoAttrShape *)attr2; return (shape_attr1->logical_rect.x == shape_attr2->logical_rect.x && - shape_attr1->logical_rect.y == shape_attr2->logical_rect.y && - shape_attr1->logical_rect.width == shape_attr2->logical_rect.width && - shape_attr1->logical_rect.height == shape_attr2->logical_rect.height && - shape_attr1->ink_rect.x == shape_attr2->ink_rect.x && - shape_attr1->ink_rect.y == shape_attr2->ink_rect.y && - shape_attr1->ink_rect.width == shape_attr2->ink_rect.width && - shape_attr1->ink_rect.height == shape_attr2->ink_rect.height && - shape_attr1->data == shape_attr2->data); + shape_attr1->logical_rect.y == shape_attr2->logical_rect.y && + shape_attr1->logical_rect.width == shape_attr2->logical_rect.width && + shape_attr1->logical_rect.height == shape_attr2->logical_rect.height && + shape_attr1->ink_rect.x == shape_attr2->ink_rect.x && + shape_attr1->ink_rect.y == shape_attr2->ink_rect.y && + shape_attr1->ink_rect.width == shape_attr2->ink_rect.width && + shape_attr1->ink_rect.height == shape_attr2->ink_rect.height && + shape_attr1->data == shape_attr2->data); } /** * pango_attr_shape_new_with_data: - * @ink_rect: ink rectangle to assign to each character + * @ink_rect: ink rectangle to assign to each character * @logical_rect: logical rectangle to assign to each character - * @data: user data pointer + * @data: user data pointer * @copy_func: (allow-none): function to copy @data when the - * attribute is copied. If %NULL, @data is simply - * copied as a pointer. + * attribute is copied. If %NULL, @data is simply copied as a pointer. * @destroy_func: (allow-none): function to free @data when the - * attribute is freed, or %NULL + * attribute is freed, or %NULL * * Like pango_attr_shape_new(), but a user data pointer is also - * provided; this pointer can be accessed when later - * rendering the glyph. + * provided; this pointer can be accessed when later rendering the glyph. * - * Return value: the newly allocated #PangoAttribute, which should be - * freed with pango_attribute_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.8 - **/ + */ PangoAttribute * pango_attr_shape_new_with_data (const PangoRectangle *ink_rect, - const PangoRectangle *logical_rect, - gpointer data, - PangoAttrDataCopyFunc copy_func, - GDestroyNotify destroy_func) + const PangoRectangle *logical_rect, + gpointer data, + PangoAttrDataCopyFunc copy_func, + GDestroyNotify destroy_func) { static const PangoAttrClass klass = { PANGO_ATTR_SHAPE, @@ -1008,26 +1005,26 @@ pango_attr_shape_new_with_data (const PangoRectangle *ink_rect, /** * pango_attr_shape_new: - * @ink_rect: ink rectangle to assign to each character + * @ink_rect: ink rectangle to assign to each character * @logical_rect: logical rectangle to assign to each character * * Create a new shape attribute. A shape is used to impose a * particular ink and logical rectangle on the result of shaping a * particular glyph. This might be used, for instance, for - * embedding a picture or a widget inside a #PangoLayout. + * embedding a picture or a widget inside a `PangoLayout`. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attr_shape_new (const PangoRectangle *ink_rect, - const PangoRectangle *logical_rect) + const PangoRectangle *logical_rect) { g_return_val_if_fail (ink_rect != NULL, NULL); g_return_val_if_fail (logical_rect != NULL, NULL); return pango_attr_shape_new_with_data (ink_rect, logical_rect, - NULL, NULL, NULL); + NULL, NULL, NULL); } /** @@ -1036,11 +1033,11 @@ pango_attr_shape_new (const PangoRectangle *ink_rect, * * Create a new gravity attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.16 - **/ + */ PangoAttribute * pango_attr_gravity_new (PangoGravity gravity) { @@ -1062,11 +1059,11 @@ pango_attr_gravity_new (PangoGravity gravity) * * Create a new gravity hint attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.16 - **/ + */ PangoAttribute * pango_attr_gravity_hint_new (PangoGravityHint hint) { @@ -1086,11 +1083,11 @@ pango_attr_gravity_hint_new (PangoGravityHint hint) * * Create a new font features tag attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.38 - **/ + */ PangoAttribute * pango_attr_font_features_new (const gchar *features) { @@ -1112,8 +1109,8 @@ pango_attr_font_features_new (const gchar *features) * * Create a new foreground alpha attribute. * - * Return value: (transfer full): the new allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.38 */ @@ -1136,8 +1133,8 @@ pango_attr_foreground_alpha_new (guint16 alpha) * * Create a new background alpha attribute. * - * Return value: (transfer full): the new allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.38 */ @@ -1163,8 +1160,8 @@ pango_attr_background_alpha_new (guint16 alpha) * If breaks are disabled, the range will be kept in a * single run, as far as possible. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy() + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.44 */ @@ -1190,8 +1187,8 @@ pango_attr_allow_breaks_new (gboolean allow_breaks) * Pango will insert hyphens when breaking lines in the middle * of a word. This attribute can be used to suppress the hyphen. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy() + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.44 */ @@ -1210,13 +1207,13 @@ pango_attr_insert_hyphens_new (gboolean insert_hyphens) /** * pango_attr_show_new: - * @flags: #PangoShowFlags to apply + * @flags: `PangoShowFlags` to apply * * Create a new attribute that influences how invisible * characters are rendered. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.44 **/ @@ -1239,11 +1236,11 @@ pango_attr_show_new (PangoShowFlags flags) * * Create a new overline-style attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.46 - **/ + */ PangoAttribute * pango_attr_overline_new (PangoOverline overline) { @@ -1267,11 +1264,11 @@ pango_attr_overline_new (PangoOverline overline) * modifies the color of overlines. If not set, overlines * will use the foreground color. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.46 - **/ + */ PangoAttribute * pango_attr_overline_color_new (guint16 red, guint16 green, @@ -1307,9 +1304,9 @@ _pango_attr_list_init (PangoAttrList *list) * * Create a new empty attribute list with a reference count of one. * - * Return value: (transfer full): the newly allocated #PangoAttrList, - * which should be freed with pango_attr_list_unref(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttrList`, + * which should be freed with [method@Pango.AttrList.unref]. + */ PangoAttrList * pango_attr_list_new (void) { @@ -1322,14 +1319,14 @@ pango_attr_list_new (void) /** * pango_attr_list_ref: - * @list: (nullable): a #PangoAttrList, may be %NULL + * @list: (nullable): a `PangoAttrList`, may be %NULL * * Increase the reference count of the given attribute list by one. * * Return value: The attribute list passed in * * Since: 1.10 - **/ + */ PangoAttrList * pango_attr_list_ref (PangoAttrList *list) { @@ -1361,12 +1358,12 @@ _pango_attr_list_destroy (PangoAttrList *list) /** * pango_attr_list_unref: - * @list: (nullable): a #PangoAttrList, may be %NULL + * @list: (nullable): a `PangoAttrList`, may be %NULL * * Decrease the reference count of the given attribute list by one. * If the result is zero, free the attribute list and the attributes * it contains. - **/ + */ void pango_attr_list_unref (PangoAttrList *list) { @@ -1384,15 +1381,14 @@ pango_attr_list_unref (PangoAttrList *list) /** * pango_attr_list_copy: - * @list: (nullable): a #PangoAttrList, may be %NULL + * @list: (nullable): a `PangoAttrList`, may be %NULL * * Copy @list and return an identical new list. * - * Return value: (nullable): the newly allocated #PangoAttrList, with a - * reference count of one, which should - * be freed with pango_attr_list_unref(). - * Returns %NULL if @list was %NULL. - **/ + * Return value: (nullable): the newly allocated `PangoAttrList`, + * with a reference count of one, which should be freed with + * [method@Pango.AttrList.unref]. Returns %NULL if @list was %NULL. + */ PangoAttrList * pango_attr_list_copy (PangoAttrList *list) { @@ -1412,8 +1408,8 @@ pango_attr_list_copy (PangoAttrList *list) static void pango_attr_list_insert_internal (PangoAttrList *list, - PangoAttribute *attr, - gboolean before) + PangoAttribute *attr, + gboolean before) { const guint start_index = attr->start_index; PangoAttribute *last_attr; @@ -1456,17 +1452,18 @@ pango_attr_list_insert_internal (PangoAttrList *list, /** * pango_attr_list_insert: - * @list: a #PangoAttrList + * @list: a `PangoAttrList` * @attr: (transfer full): the attribute to insert. Ownership of this - * value is assumed by the list. + * value is assumed by the list. * - * Insert the given attribute into the #PangoAttrList. It will - * be inserted after all other attributes with a matching - * @start_index. - **/ + * Insert the given attribute into the `PangoAttrList`. + * + * It will be inserted after all other attributes with a + * matching @start_index. + */ void pango_attr_list_insert (PangoAttrList *list, - PangoAttribute *attr) + PangoAttribute *attr) { g_return_if_fail (list != NULL); g_return_if_fail (attr != NULL); @@ -1476,17 +1473,18 @@ pango_attr_list_insert (PangoAttrList *list, /** * pango_attr_list_insert_before: - * @list: a #PangoAttrList + * @list: a `PangoAttrList` * @attr: (transfer full): the attribute to insert. Ownership of this - * value is assumed by the list. + * value is assumed by the list. * - * Insert the given attribute into the #PangoAttrList. It will - * be inserted before all other attributes with a matching - * @start_index. - **/ + * Insert the given attribute into the `PangoAttrList`. + * + * It will be inserted before all other attributes with a + * matching @start_index. + */ void pango_attr_list_insert_before (PangoAttrList *list, - PangoAttribute *attr) + PangoAttribute *attr) { g_return_if_fail (list != NULL); g_return_if_fail (attr != NULL); @@ -1496,20 +1494,21 @@ pango_attr_list_insert_before (PangoAttrList *list, /** * pango_attr_list_change: - * @list: a #PangoAttrList + * @list: a `PangoAttrList` * @attr: (transfer full): the attribute to insert. Ownership of this - * value is assumed by the list. + * value is assumed by the list. + * + * Insert the given attribute into the `PangoAttrList`. * - * Insert the given attribute into the #PangoAttrList. It will - * replace any attributes of the same type on that segment + * It will replace any attributes of the same type on that segment * and be merged with any adjoining attributes that are identical. * - * This function is slower than pango_attr_list_insert() for - * creating an attribute list in order (potentially much slower - * for large lists). However, pango_attr_list_insert() is not - * suitable for continually changing a set of attributes - * since it never removes or combines existing attributes. - **/ + * This function is slower than [method@Pango.AttrList.insert] for + * creating an attribute list in order (potentially much slower for + * large lists). However, [method@Pango.AttrList.insert] is not + * suitable for continually changing a set of attributes since it + * never removes or combines existing attributes. + */ void pango_attr_list_change (PangoAttrList *list, PangoAttribute *attr) @@ -1654,27 +1653,25 @@ pango_attr_list_change (PangoAttrList *list, /** * pango_attr_list_update: - * @list: a #PangoAttrList + * @list: a `PangoAttrList` * @pos: the position of the change * @remove: the number of removed bytes * @add: the number of added bytes * - * Update indices of attributes in @list for - * a change in the text they refer to. + * Update indices of attributes in @list for a change in the + * text they refer to. * - * The change that this function applies is - * removing @remove bytes at position @pos - * and inserting @add bytes instead. + * The change that this function applies is removing @remove + * bytes at position @pos and inserting @add bytes instead. * - * Attributes that fall entirely in the - * (@pos, @pos + @remove) range are removed. + * Attributes that fall entirely in the (@pos, @pos + @remove) + * range are removed. * - * Attributes that start or end inside the - * (@pos, @pos + @remove) range are shortened to - * reflect the removal. + * Attributes that start or end inside the (@pos, @pos + @remove) + * range are shortened to reflect the removal. * - * Attributes start and end positions are updated - * if they are behind @pos + @remove. + * Attributes start and end positions are updated if they are + * behind @pos + @remove. * * Since: 1.44 */ @@ -1732,29 +1729,30 @@ pango_attr_list_update (PangoAttrList *list, /** * pango_attr_list_splice: - * @list: a #PangoAttrList - * @other: another #PangoAttrList + * @list: a `PangoAttrList` + * @other: another `PangoAttrList` * @pos: the position in @list at which to insert @other * @len: the length of the spliced segment. (Note that this - * must be specified since the attributes in @other - * may only be present at some subsection of this range) + * must be specified since the attributes in @other may only + * be present at some subsection of this range) * - * This function opens up a hole in @list, fills it in with attributes from - * the left, and then merges @other on top of the hole. + * This function opens up a hole in @list, fills it in with attributes + * from the left, and then merges @other on top of the hole. * * This operation is equivalent to stretching every attribute * that applies at position @pos in @list by an amount @len, - * and then calling pango_attr_list_change() with a copy - * of each attribute in @other in sequence (offset in position by @pos). + * and then calling [method@Pango.AttrList.change] with a copy + * of each attribute in @other in sequence (offset in position + * by @pos). * * This operation proves useful for, for instance, inserting * a pre-edit string in the middle of an edit buffer. - **/ + */ void pango_attr_list_splice (PangoAttrList *list, - PangoAttrList *other, - gint pos, - gint len) + PangoAttrList *other, + gint pos, + gint len) { guint i, p; guint upos, ulen; @@ -1816,13 +1814,13 @@ pango_attr_list_splice (PangoAttrList *list, /** * pango_attr_list_get_attributes: - * @list: a #PangoAttrList + * @list: a `PangoAttrList` * * Gets a list of all attributes in @list. * * Return value: (element-type Pango.Attribute) (transfer full): * a list of all attributes in @list. To free this value, call - * pango_attribute_destroy() on each value and g_slist_free() + * [mehod@Pango.Attribute.destroy] on each value and g_slist_free() * on the list. * * Since: 1.44 @@ -1850,8 +1848,8 @@ pango_attr_list_get_attributes (PangoAttrList *list) /** * pango_attr_list_equal: - * @list: a #PangoAttrList - * @other_list: the other #PangoAttrList + * @list: a `PangoAttrList` + * @other_list: the other `PangoAttrList` * * Checks whether @list and @other_list contain the same attributes and * whether those attributes apply to the same ranges. Beware that this @@ -1945,13 +1943,13 @@ _pango_attr_list_get_iterator (PangoAttrList *list, /** * pango_attr_list_get_iterator: - * @list: a #PangoAttrList + * @list: a `PangoAttrList` * * Create a iterator initialized to the beginning of the list. * @list must not be modified until this iterator is freed. * - * Return value: (transfer full): the newly allocated #PangoAttrIterator, which should - * be freed with pango_attr_iterator_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttrIterator`, + * which should be freed with [method@Pango.AttrIterator.destroy]. **/ PangoAttrIterator * pango_attr_list_get_iterator (PangoAttrList *list) @@ -1974,14 +1972,14 @@ pango_attr_list_get_iterator (PangoAttrList *list) * * Get the range of the current segment. Note that the * stored return values are signed, not unsigned like - * the values in #PangoAttribute. To deal with this API + * the values in `PangoAttribute`. To deal with this API * oversight, stored return values that wouldn't fit into * a signed integer are clamped to %G_MAXINT. - **/ + */ void pango_attr_iterator_range (PangoAttrIterator *iterator, - gint *start, - gint *end) + gint *start, + gint *end) { g_return_if_fail (iterator != NULL); @@ -1993,12 +1991,13 @@ pango_attr_iterator_range (PangoAttrIterator *iterator, /** * pango_attr_iterator_next: - * @iterator: a #PangoAttrIterator + * @iterator: a `PangoAttrIterator` * * Advance the iterator until the next change of style. * - * Return value: %FALSE if the iterator is at the end of the list, otherwise %TRUE - **/ + * Return value: %FALSE if the iterator is at the end of the list, + * otherwise %TRUE + */ gboolean pango_attr_iterator_next (PangoAttrIterator *iterator) { @@ -2063,14 +2062,13 @@ pango_attr_iterator_next (PangoAttrIterator *iterator) /** * pango_attr_iterator_copy: - * @iterator: a #PangoAttrIterator. + * @iterator: a `PangoAttrIterator` * - * Copy a #PangoAttrIterator + * Copy a `PangoAttrIterator`. * - * Return value: (transfer full): the newly allocated - * #PangoAttrIterator, which should be freed with - * pango_attr_iterator_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttrIterator`, + * which should be freed with [method@Pango.AttrIterator.destroy]. + */ PangoAttrIterator * pango_attr_iterator_copy (PangoAttrIterator *iterator) { @@ -2099,10 +2097,10 @@ _pango_attr_iterator_destroy (PangoAttrIterator *iterator) /** * pango_attr_iterator_destroy: - * @iterator: a #PangoAttrIterator. + * @iterator: a `PangoAttrIterator` * - * Destroy a #PangoAttrIterator and free all associated memory. - **/ + * Destroy a `PangoAttrIterator` and free all associated memory. + */ void pango_attr_iterator_destroy (PangoAttrIterator *iterator) { @@ -2114,21 +2112,21 @@ pango_attr_iterator_destroy (PangoAttrIterator *iterator) /** * pango_attr_iterator_get: - * @iterator: a #PangoAttrIterator - * @type: the type of attribute to find. + * @iterator: a `PangoAttrIterator` + * @type: the type of attribute to find * * Find the current attribute of a particular type at the iterator * location. When multiple attributes of the same type overlap, * the attribute whose range starts closest to the current location * is used. * - * Return value: (nullable) (transfer none): the current attribute of the given type, - * or %NULL if no attribute of that type applies to the - * current location. - **/ + * Return value: (nullable) (transfer none): the current attribute of + * the given type, or %NULL if no attribute of that type applies to + * the current location. + */ PangoAttribute * pango_attr_iterator_get (PangoAttrIterator *iterator, - PangoAttrType type) + PangoAttrType type) { int i; @@ -2150,29 +2148,28 @@ pango_attr_iterator_get (PangoAttrIterator *iterator, /** * pango_attr_iterator_get_font: - * @iterator: a #PangoAttrIterator - * @desc: a #PangoFontDescription to fill in with the current values. - * The family name in this structure will be set using - * pango_font_description_set_family_static() using values from - * an attribute in the #PangoAttrList associated with the iterator, - * so if you plan to keep it around, you must call: - * pango_font_description_set_family (desc, pango_font_description_get_family (desc)). - * @language: (allow-none): if non-%NULL, location to store language tag for item, or %NULL - * if none is found. - * @extra_attrs: (allow-none) (element-type Pango.Attribute) (transfer full): if non-%NULL, - * location in which to store a list of non-font - * attributes at the the current position; only the highest priority - * value of each attribute will be added to this list. In order - * to free this value, you must call pango_attribute_destroy() on - * each member. + * @iterator: a `PangoAttrIterator` + * @desc: a `PangoFontDescription` to fill in with the current values. + * The family name in this structure will be set using + * [method@Pango.FontDescription.set_family_static] using values from + * an attribute in the `PangoAttrList` associated with the iterator, + * so if you plan to keep it around, you must call: + * pango_font_description_set_family (desc, pango_font_description_get_family (desc)). + * @language: (allow-none): if non-%NULL, location to store language tag + * for item, or %NULL if none is found. + * @extra_attrs: (allow-none) (element-type Pango.Attribute) (transfer full): + * if non-%NULL, location in which to store a list of non-font attributes + * at the the current position; only the highest priority value of each + * attribute will be added to this list. In order to free this value, you + * must call [method@Pango.Attribute.destroy] on each member. * * Get the font and other attributes at the current iterator position. - **/ + */ void pango_attr_iterator_get_font (PangoAttrIterator *iterator, - PangoFontDescription *desc, - PangoLanguage **language, - GSList **extra_attrs) + PangoFontDescription *desc, + PangoLanguage **language, + GSList **extra_attrs) { PangoFontMask mask = 0; gboolean have_language = FALSE; @@ -2197,91 +2194,91 @@ pango_attr_iterator_get_font (PangoAttrIterator *iterator, const PangoAttribute *attr = g_ptr_array_index (iterator->attribute_stack, i); switch ((int) attr->klass->type) - { - case PANGO_ATTR_FONT_DESC: - { - PangoFontMask new_mask = pango_font_description_get_set_fields (((PangoAttrFontDesc *)attr)->desc) & ~mask; - mask |= new_mask; - pango_font_description_unset_fields (desc, new_mask); - pango_font_description_merge_static (desc, ((PangoAttrFontDesc *)attr)->desc, FALSE); - - break; - } - case PANGO_ATTR_FAMILY: - if (!(mask & PANGO_FONT_MASK_FAMILY)) - { - mask |= PANGO_FONT_MASK_FAMILY; - pango_font_description_set_family (desc, ((PangoAttrString *)attr)->value); - } - break; - case PANGO_ATTR_STYLE: - if (!(mask & PANGO_FONT_MASK_STYLE)) - { - mask |= PANGO_FONT_MASK_STYLE; - pango_font_description_set_style (desc, ((PangoAttrInt *)attr)->value); - } - break; - case PANGO_ATTR_VARIANT: - if (!(mask & PANGO_FONT_MASK_VARIANT)) - { - mask |= PANGO_FONT_MASK_VARIANT; - pango_font_description_set_variant (desc, ((PangoAttrInt *)attr)->value); - } - break; - case PANGO_ATTR_WEIGHT: - if (!(mask & PANGO_FONT_MASK_WEIGHT)) - { - mask |= PANGO_FONT_MASK_WEIGHT; - pango_font_description_set_weight (desc, ((PangoAttrInt *)attr)->value); - } - break; - case PANGO_ATTR_STRETCH: - if (!(mask & PANGO_FONT_MASK_STRETCH)) - { - mask |= PANGO_FONT_MASK_STRETCH; - pango_font_description_set_stretch (desc, ((PangoAttrInt *)attr)->value); - } - break; - case PANGO_ATTR_SIZE: - if (!(mask & PANGO_FONT_MASK_SIZE)) - { - mask |= PANGO_FONT_MASK_SIZE; - pango_font_description_set_size (desc, ((PangoAttrSize *)attr)->size); - } - break; - case PANGO_ATTR_ABSOLUTE_SIZE: - if (!(mask & PANGO_FONT_MASK_SIZE)) - { - mask |= PANGO_FONT_MASK_SIZE; - pango_font_description_set_absolute_size (desc, ((PangoAttrSize *)attr)->size); - } - break; - case PANGO_ATTR_SCALE: - if (!have_scale) - { - have_scale = TRUE; - scale = ((PangoAttrFloat *)attr)->value; - } - break; - case PANGO_ATTR_LANGUAGE: - if (language) - { - if (!have_language) - { - have_language = TRUE; - *language = ((PangoAttrLanguage *)attr)->value; - } - } - break; - default: - if (extra_attrs) - { - gboolean found = FALSE; - - /* Hack: special-case FONT_FEATURES. We don't want them to - * override each other, so we never merge them. This should - * be fixed when we implement attr-merging. */ - if (attr->klass->type != PANGO_ATTR_FONT_FEATURES) + { + case PANGO_ATTR_FONT_DESC: + { + PangoFontMask new_mask = pango_font_description_get_set_fields (((PangoAttrFontDesc *)attr)->desc) & ~mask; + mask |= new_mask; + pango_font_description_unset_fields (desc, new_mask); + pango_font_description_merge_static (desc, ((PangoAttrFontDesc *)attr)->desc, FALSE); + + break; + } + case PANGO_ATTR_FAMILY: + if (!(mask & PANGO_FONT_MASK_FAMILY)) + { + mask |= PANGO_FONT_MASK_FAMILY; + pango_font_description_set_family (desc, ((PangoAttrString *)attr)->value); + } + break; + case PANGO_ATTR_STYLE: + if (!(mask & PANGO_FONT_MASK_STYLE)) + { + mask |= PANGO_FONT_MASK_STYLE; + pango_font_description_set_style (desc, ((PangoAttrInt *)attr)->value); + } + break; + case PANGO_ATTR_VARIANT: + if (!(mask & PANGO_FONT_MASK_VARIANT)) + { + mask |= PANGO_FONT_MASK_VARIANT; + pango_font_description_set_variant (desc, ((PangoAttrInt *)attr)->value); + } + break; + case PANGO_ATTR_WEIGHT: + if (!(mask & PANGO_FONT_MASK_WEIGHT)) + { + mask |= PANGO_FONT_MASK_WEIGHT; + pango_font_description_set_weight (desc, ((PangoAttrInt *)attr)->value); + } + break; + case PANGO_ATTR_STRETCH: + if (!(mask & PANGO_FONT_MASK_STRETCH)) + { + mask |= PANGO_FONT_MASK_STRETCH; + pango_font_description_set_stretch (desc, ((PangoAttrInt *)attr)->value); + } + break; + case PANGO_ATTR_SIZE: + if (!(mask & PANGO_FONT_MASK_SIZE)) + { + mask |= PANGO_FONT_MASK_SIZE; + pango_font_description_set_size (desc, ((PangoAttrSize *)attr)->size); + } + break; + case PANGO_ATTR_ABSOLUTE_SIZE: + if (!(mask & PANGO_FONT_MASK_SIZE)) + { + mask |= PANGO_FONT_MASK_SIZE; + pango_font_description_set_absolute_size (desc, ((PangoAttrSize *)attr)->size); + } + break; + case PANGO_ATTR_SCALE: + if (!have_scale) + { + have_scale = TRUE; + scale = ((PangoAttrFloat *)attr)->value; + } + break; + case PANGO_ATTR_LANGUAGE: + if (language) + { + if (!have_language) + { + have_language = TRUE; + *language = ((PangoAttrLanguage *)attr)->value; + } + } + break; + default: + if (extra_attrs) + { + gboolean found = FALSE; + + /* Hack: special-case FONT_FEATURES. We don't want them to + * override each other, so we never merge them. This should + * be fixed when we implement attr-merging. */ + if (attr->klass->type != PANGO_ATTR_FONT_FEATURES) { GSList *tmp_list = *extra_attrs; while (tmp_list) @@ -2297,10 +2294,10 @@ pango_attr_iterator_get_font (PangoAttrIterator *iterator, } } - if (!found) - *extra_attrs = g_slist_prepend (*extra_attrs, pango_attribute_copy (attr)); - } - } + if (!found) + *extra_attrs = g_slist_prepend (*extra_attrs, pango_attribute_copy (attr)); + } + } } if (have_scale) @@ -2314,24 +2311,23 @@ pango_attr_iterator_get_font (PangoAttrIterator *iterator, /** * pango_attr_list_filter: - * @list: a #PangoAttrList + * @list: a `PangoAttrList` * @func: (scope call) (closure data): callback function; returns %TRUE * if an attribute should be filtered out. * @data: (closure): Data to be passed to @func * - * Given a #PangoAttrList and callback function, removes any elements - * of @list for which @func returns %TRUE and inserts them into - * a new list. + * Given a `PangoAttrList` and callback function, removes any elements + * of @list for which @func returns %TRUE and inserts them into a new list. * - * Return value: (transfer full) (nullable): the new #PangoAttrList or + * Return value: (transfer full) (nullable): the new `PangoAttrList` or * %NULL if no attributes of the given types were found. * * Since: 1.2 - **/ + */ PangoAttrList * pango_attr_list_filter (PangoAttrList *list, - PangoAttrFilterFunc func, - gpointer data) + PangoAttrFilterFunc func, + gpointer data) { PangoAttrList *new = NULL; @@ -2367,18 +2363,18 @@ pango_attr_list_filter (PangoAttrList *list, /** * pango_attr_iterator_get_attrs: - * @iterator: a #PangoAttrIterator + * @iterator: a `PangoAttrIterator` * * Gets a list of all attributes at the current position of the * iterator. * - * Return value: (element-type Pango.Attribute) (transfer full): a list of - * all attributes for the current range. - * To free this value, call pango_attribute_destroy() on - * each value and g_slist_free() on the list. + * Return value: (element-type Pango.Attribute) (transfer full): + * a list of all attributes for the current range. To free this value, + * call [method@Pango.Attribute.destroy] on each value and g_slist_free() + * on the list. * * Since: 1.2 - **/ + */ GSList * pango_attr_iterator_get_attrs (PangoAttrIterator *iterator) { @@ -2396,17 +2392,17 @@ pango_attr_iterator_get_attrs (PangoAttrIterator *iterator) gboolean found = FALSE; for (tmp_list2 = attrs; tmp_list2; tmp_list2 = tmp_list2->next) - { - PangoAttribute *old_attr = tmp_list2->data; + { + PangoAttribute *old_attr = tmp_list2->data; if (attr->klass->type == old_attr->klass->type) { found = TRUE; break; } - } + } if (!found) - attrs = g_slist_prepend (attrs, pango_attribute_copy (attr)); + attrs = g_slist_prepend (attrs, pango_attribute_copy (attr)); } return attrs; diff --git a/pango/pango-attributes.h b/pango/pango-attributes.h index aecd1199..5ef7a132 100644 --- a/pango/pango-attributes.h +++ b/pango/pango-attributes.h @@ -37,7 +37,7 @@ typedef struct _PangoColor PangoColor; * @green: value of green component * @blue: value of blue component * - * The #PangoColor structure is used to + * The `PangoColor` structure is used to * represent a color in an uncalibrated RGB color-space. */ struct _PangoColor @@ -50,7 +50,7 @@ struct _PangoColor /** * PANGO_TYPE_COLOR: * - * The #GObject type for #PangoColor. + * The `GObject` type for `PangoColor`. */ #define PANGO_TYPE_COLOR pango_color_get_type () PANGO_AVAILABLE_IN_ALL @@ -93,32 +93,34 @@ typedef struct _PangoAttrFontFeatures PangoAttrFontFeatures; /** * PANGO_TYPE_ATTR_LIST: * - * The #GObject type for #PangoAttrList. + * The `GObject` type for `PangoAttrList`. */ #define PANGO_TYPE_ATTR_LIST pango_attr_list_get_type () + /** * PangoAttrIterator: * - * The #PangoAttrIterator structure is used to represent an - * iterator through a #PangoAttrList. A new iterator is created - * with pango_attr_list_get_iterator(). Once the iterator - * is created, it can be advanced through the style changes - * in the text using pango_attr_iterator_next(). At each - * style change, the range of the current style segment and the - * attributes currently in effect can be queried. + * The `PangoAttrIterator` structure is used to represent an + * iterator through a [struct@Pango.AttrList]. A new iterator + * is created with [method@Pango.AttrList.get_iterator]. Once + * the iterator is created, it can be advanced through the style + * changes in the text using [method@Pango.AttrIterator.next]. + * At each style change, the range of the current style segment + * and the attributes currently in effect can be queried. */ + /** * PangoAttrList: * - * The #PangoAttrList structure represents a list of attributes + * The `PangoAttrList` structure represents a list of attributes * that apply to a section of text. The attributes are, in general, * allowed to overlap in an arbitrary fashion, however, if the - * attributes are manipulated only through pango_attr_list_change(), + * attributes are manipulated only through [method@Pango.AttrList.change], * the overlap between properties will meet stricter criteria. * - * Since the #PangoAttrList structure is stored as a linear list, + * Since the `PangoAttrList` structure is stored as a linear list, * it is not suitable for storing attributes for large amounts - * of text. In general, you should not use a single #PangoAttrList + * of text. In general, you should not use a single `PangoAttrList` * for more than one paragraph of text. */ typedef struct _PangoAttrList PangoAttrList; @@ -127,43 +129,43 @@ typedef struct _PangoAttrIterator PangoAttrIterator; /** * PangoAttrType: * @PANGO_ATTR_INVALID: does not happen - * @PANGO_ATTR_LANGUAGE: language (#PangoAttrLanguage) - * @PANGO_ATTR_FAMILY: font family name list (#PangoAttrString) - * @PANGO_ATTR_STYLE: font slant style (#PangoAttrInt) - * @PANGO_ATTR_WEIGHT: font weight (#PangoAttrInt) - * @PANGO_ATTR_VARIANT: font variant (normal or small caps) (#PangoAttrInt) - * @PANGO_ATTR_STRETCH: font stretch (#PangoAttrInt) - * @PANGO_ATTR_SIZE: font size in points scaled by %PANGO_SCALE (#PangoAttrInt) - * @PANGO_ATTR_FONT_DESC: font description (#PangoAttrFontDesc) - * @PANGO_ATTR_FOREGROUND: foreground color (#PangoAttrColor) - * @PANGO_ATTR_BACKGROUND: background color (#PangoAttrColor) - * @PANGO_ATTR_UNDERLINE: whether the text has an underline (#PangoAttrInt) - * @PANGO_ATTR_STRIKETHROUGH: whether the text is struck-through (#PangoAttrInt) - * @PANGO_ATTR_RISE: baseline displacement (#PangoAttrInt) - * @PANGO_ATTR_SHAPE: shape (#PangoAttrShape) - * @PANGO_ATTR_SCALE: font size scale factor (#PangoAttrFloat) - * @PANGO_ATTR_FALLBACK: whether fallback is enabled (#PangoAttrInt) - * @PANGO_ATTR_LETTER_SPACING: letter spacing (#PangoAttrInt) - * @PANGO_ATTR_UNDERLINE_COLOR: underline color (#PangoAttrColor) - * @PANGO_ATTR_STRIKETHROUGH_COLOR: strikethrough color (#PangoAttrColor) - * @PANGO_ATTR_ABSOLUTE_SIZE: font size in pixels scaled by %PANGO_SCALE (#PangoAttrInt) - * @PANGO_ATTR_GRAVITY: base text gravity (#PangoAttrInt) - * @PANGO_ATTR_GRAVITY_HINT: gravity hint (#PangoAttrInt) - * @PANGO_ATTR_FONT_FEATURES: OpenType font features (#PangoAttrString). Since 1.38 - * @PANGO_ATTR_FOREGROUND_ALPHA: foreground alpha (#PangoAttrInt). Since 1.38 - * @PANGO_ATTR_BACKGROUND_ALPHA: background alpha (#PangoAttrInt). Since 1.38 - * @PANGO_ATTR_ALLOW_BREAKS: whether breaks are allowed (#PangoAttrInt). Since 1.44 - * @PANGO_ATTR_SHOW: how to render invisible characters (#PangoAttrInt). Since 1.44 - * @PANGO_ATTR_INSERT_HYPHENS: whether to insert hyphens at intra-word line breaks (#PangoAttrInt). Since 1.44 - * @PANGO_ATTR_OVERLINE: whether the text has an overline (#PangoAttrInt). Since 1.46 - * @PANGO_ATTR_OVERLINE_COLOR: overline color (#PangoAttrColor). Since 1.46 - * - * The #PangoAttrType - * distinguishes between different types of attributes. Along with the - * predefined values, it is possible to allocate additional values - * for custom attributes using pango_attr_type_register(). The predefined - * values are given below. The type of structure used to store the - * attribute is listed in parentheses after the description. + * @PANGO_ATTR_LANGUAGE: language ([struct@Pango.AttrLanguage]) + * @PANGO_ATTR_FAMILY: font family name list ([struct@Pango.AttrString]) + * @PANGO_ATTR_STYLE: font slant style ([struct@Pango.AttrInt]) + * @PANGO_ATTR_WEIGHT: font weight ([struct@Pango.AttrInt]) + * @PANGO_ATTR_VARIANT: font variant (normal or small caps) ([struct@Pango.AttrInt]) + * @PANGO_ATTR_STRETCH: font stretch ([struct@Pango.AttrInt]) + * @PANGO_ATTR_SIZE: font size in points scaled by %PANGO_SCALE ([struct@Pango.AttrInt]) + * @PANGO_ATTR_FONT_DESC: font description ([struct@Pango.AttrFontDesc]) + * @PANGO_ATTR_FOREGROUND: foreground color ([struct@Pango.AttrColor]) + * @PANGO_ATTR_BACKGROUND: background color ([struct@Pango.AttrColor]) + * @PANGO_ATTR_UNDERLINE: whether the text has an underline ([struct@Pango.AttrInt]) + * @PANGO_ATTR_STRIKETHROUGH: whether the text is struck-through ([struct@Pango.AttrInt]) + * @PANGO_ATTR_RISE: baseline displacement ([struct@Pango.AttrInt]) + * @PANGO_ATTR_SHAPE: shape ([struct@Pango.AttrShape]) + * @PANGO_ATTR_SCALE: font size scale factor ([struct@Pango.AttrFloat]) + * @PANGO_ATTR_FALLBACK: whether fallback is enabled ([struct@Pango.AttrInt]) + * @PANGO_ATTR_LETTER_SPACING: letter spacing ([struct@PangoAttrInt]) + * @PANGO_ATTR_UNDERLINE_COLOR: underline color ([struct@Pango.AttrColor]) + * @PANGO_ATTR_STRIKETHROUGH_COLOR: strikethrough color ([struct@Pango.AttrColor]) + * @PANGO_ATTR_ABSOLUTE_SIZE: font size in pixels scaled by %PANGO_SCALE ([struct@Pango.AttrInt]) + * @PANGO_ATTR_GRAVITY: base text gravity ([struct@Pango.AttrInt]) + * @PANGO_ATTR_GRAVITY_HINT: gravity hint ([struct@Pango.AttrInt]) + * @PANGO_ATTR_FONT_FEATURES: OpenType font features ([struct@Pango.AttrString]). Since 1.38 + * @PANGO_ATTR_FOREGROUND_ALPHA: foreground alpha ([struct@Pango.AttrInt]). Since 1.38 + * @PANGO_ATTR_BACKGROUND_ALPHA: background alpha ([struct@Pango.AttrInt]). Since 1.38 + * @PANGO_ATTR_ALLOW_BREAKS: whether breaks are allowed ([struct@Pango.AttrInt]). Since 1.44 + * @PANGO_ATTR_SHOW: how to render invisible characters ([struct@Pango.AttrInt]). Since 1.44 + * @PANGO_ATTR_INSERT_HYPHENS: whether to insert hyphens at intra-word line breaks ([struct@Pango.AttrInt]). Since 1.44 + * @PANGO_ATTR_OVERLINE: whether the text has an overline ([struct@Pango.AttrInt]). Since 1.46 + * @PANGO_ATTR_OVERLINE_COLOR: overline color ([struct@Pango.AttrColor]). Since 1.46 + * + * The `PangoAttrType` distinguishes between different types of attributes. + * + * Along with the predefined values, it is possible to allocate additional + * values for custom attributes using [func@attr_type_register]. The predefined + * values are given below. The type of structure used to store the attribute is + * listed in parentheses after the description. */ typedef enum { @@ -226,9 +228,8 @@ typedef enum * drawn continuously across multiple runs. This type * of underlining is available since Pango 1.46. * - * The #PangoUnderline enumeration is used to specify - * whether text should be underlined, and if so, the type - * of underlining. + * The `PangoUnderline` enumeration is used to specify whether text + * should be underlined, and if so, the type of underlining. */ typedef enum { PANGO_UNDERLINE_NONE, @@ -248,9 +249,8 @@ typedef enum { * @PANGO_OVERLINE_SINGLE: Draw a single line above the ink * extents of the text being underlined. * - * The #PangoOverline enumeration is used to specify - * whether text should be overlined, and if so, the type - * of line. + * The `PangoOverline` enumeration is used to specify whether text + * should be overlined, and if so, the type of line. * * Since: 1.46 */ @@ -262,8 +262,9 @@ typedef enum { /** * PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING: * - * This value can be used to set the start_index member of a #PangoAttribute - * such that the attribute covers from the beginning of the text. + * This value can be used to set the start_index member of a + * `PangoAttribute` such that the attribute covers from the + * beginning of the text. * * Since: 1.24 */ @@ -272,8 +273,9 @@ typedef enum { /** * PANGO_ATTR_INDEX_TO_TEXT_END: (value 4294967295) * - * This value can be used to set the end_index member of a #PangoAttribute - * such that the attribute covers to the end of the text. + * This value can be used to set the end_index member of a + * `PangoAttribute` such that the attribute covers to the + * end of the text. * * Since: 1.24 */ @@ -286,12 +288,14 @@ typedef enum { * @end_index: end index of the range (in bytes). The character at this index * is not included in the range. * - * The #PangoAttribute structure represents the common portions of all - * attributes. Particular types of attributes include this structure - * as their initial portion. The common portion of the attribute holds - * the range to which the value in the type-specific part of the attribute - * applies and should be initialized using pango_attribute_init(). - * By default an attribute will have an all-inclusive range of [0,%G_MAXUINT]. + * The `PangoAttribute` structure represents the common portions of all + * attributes. + * + * Particular types of attributes include this structure as their initial + * portion. The common portion of the attribute holds the range to which + * the value in the type-specific part of the attribute applies and should + * be initialized using [method@Pango.Attribute.init]. By default, an attribute + * will have an all-inclusive range of [0,%G_MAXUINT]. */ struct _PangoAttribute { @@ -308,8 +312,8 @@ struct _PangoAttribute * Type of a function filtering a list of attributes. * * Return value: %TRUE if the attribute should be selected for - * filtering, %FALSE otherwise. - **/ + * filtering, %FALSE otherwise. + */ typedef gboolean (*PangoAttrFilterFunc) (PangoAttribute *attribute, gpointer user_data); @@ -326,14 +330,17 @@ typedef gpointer (*PangoAttrDataCopyFunc) (gconstpointer user_data); /** * PangoAttrClass: * @type: the type ID for this attribute - * @copy: function to duplicate an attribute of this type (see pango_attribute_copy()) - * @destroy: function to free an attribute of this type (see pango_attribute_destroy()) - * @equal: function to check two attributes of this type for equality (see pango_attribute_equal()) - * - * The #PangoAttrClass structure stores the type and operations for + * @copy: function to duplicate an attribute of this type + * (see [method@Pango.Attribute.copy]) + * @destroy: function to free an attribute of this type + * (see [method@Pango.Attribute.destroy]) + * @equal: function to check two attributes of this type for equality + * (see [method@Pango.Attribute.equal]) + * + * The `PangoAttrClass` structure stores the type and operations for * a particular type of attribute. The functions in this structure should * not be called directly. Instead, one should use the wrapper functions - * provided for #PangoAttribute. + * provided for `PangoAttribute`. */ struct _PangoAttrClass { @@ -349,7 +356,7 @@ struct _PangoAttrClass * @attr: the common portion of the attribute * @value: the string which is the value of the attribute * - * The #PangoAttrString structure is used to represent attributes with + * The `PangoAttrString` structure is used to represent attributes with * a string value. */ struct _PangoAttrString @@ -360,9 +367,9 @@ struct _PangoAttrString /** * PangoAttrLanguage: * @attr: the common portion of the attribute - * @value: the #PangoLanguage which is the value of the attribute + * @value: the `PangoLanguage` which is the value of the attribute * - * The #PangoAttrLanguage structure is used to represent attributes that + * The `PangoAttrLanguage` structure is used to represent attributes that * are languages. */ struct _PangoAttrLanguage @@ -375,7 +382,7 @@ struct _PangoAttrLanguage * @attr: the common portion of the attribute * @value: the value of the attribute * - * The #PangoAttrInt structure is used to represent attributes with + * The `PangoAttrInt` structure is used to represent attributes with * an integer or enumeration value. */ struct _PangoAttrInt @@ -388,7 +395,7 @@ struct _PangoAttrInt * @attr: the common portion of the attribute * @value: the value of the attribute * - * The #PangoAttrFloat structure is used to represent attributes with + * The `PangoAttrFloat` structure is used to represent attributes with * a float or double value. */ struct _PangoAttrFloat @@ -399,9 +406,9 @@ struct _PangoAttrFloat /** * PangoAttrColor: * @attr: the common portion of the attribute - * @color: the #PangoColor which is the value of the attribute + * @color: the `PangoColor` which is the value of the attribute * - * The #PangoAttrColor structure is used to represent attributes that + * The `PangoAttrColor` structure is used to represent attributes that * are colors. */ struct _PangoAttrColor @@ -414,13 +421,13 @@ struct _PangoAttrColor * PangoAttrSize: * @attr: the common portion of the attribute * @size: size of font, in units of 1/%PANGO_SCALE of a point (for - * %PANGO_ATTR_SIZE) or of a device uni (for %PANGO_ATTR_ABSOLUTE_SIZE) + * %PANGO_ATTR_SIZE) or of a device unit (for %PANGO_ATTR_ABSOLUTE_SIZE) * @absolute: whether the font size is in device units or points. - * This field is only present for compatibility with Pango-1.8.0 - * (%PANGO_ATTR_ABSOLUTE_SIZE was added in 1.8.1); and always will - * be %FALSE for %PANGO_ATTR_SIZE and %TRUE for %PANGO_ATTR_ABSOLUTE_SIZE. + * This field is only present for compatibility with Pango-1.8.0 + * (%PANGO_ATTR_ABSOLUTE_SIZE was added in 1.8.1); and always will + * be %FALSE for %PANGO_ATTR_SIZE and %TRUE for %PANGO_ATTR_ABSOLUTE_SIZE. * - * The #PangoAttrSize structure is used to represent attributes which + * The `PangoAttrSize` structure is used to represent attributes which * set font size. */ struct _PangoAttrSize @@ -435,11 +442,11 @@ struct _PangoAttrSize * @attr: the common portion of the attribute * @ink_rect: the ink rectangle to restrict to * @logical_rect: the logical rectangle to restrict to - * @data: user data set (see pango_attr_shape_new_with_data()) + * @data: user data set (see [func@attr_shape_new_with_data]) * @copy_func: copy function for the user data * @destroy_func: destroy function for the user data * - * The #PangoAttrShape structure is used to represent attributes which + * The `PangoAttrShape` structure is used to represent attributes which * impose shape restrictions. */ struct _PangoAttrShape @@ -458,7 +465,7 @@ struct _PangoAttrShape * @attr: the common portion of the attribute * @desc: the font description which is the value of this attribute * - * The #PangoAttrFontDesc structure is used to store an attribute that + * The `PangoAttrFontDesc` structure is used to store an attribute that * sets all aspects of the font description at once. */ struct _PangoAttrFontDesc @@ -472,7 +479,7 @@ struct _PangoAttrFontDesc * @attr: the common portion of the attribute * @features: the featues, as a string in CSS syntax * - * The #PangoAttrFontFeatures structure is used to represent OpenType + * The `PangoAttrFontFeatures` structure is used to represent OpenType * font features as an attribute. * * Since: 1.38 -- cgit v1.2.1