diff options
Diffstat (limited to 'pango/fonts.c')
| -rw-r--r-- | pango/fonts.c | 1177 |
1 files changed, 615 insertions, 562 deletions
diff --git a/pango/fonts.c b/pango/fonts.c index 0b76d9dd..b199e785 100644 --- a/pango/fonts.c +++ b/pango/fonts.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 @@ -19,19 +19,6 @@ * Boston, MA 02111-1307, USA. */ -/** - * SECTION:fonts - * @short_description:Structures representing abstract fonts - * @title: Fonts - * - * Pango supports a flexible architecture where a - * particular rendering architecture can supply an - * implementation of fonts. The #PangoFont structure - * represents an abstract rendering-system-independent font. - * Pango provides routines to list available fonts, and - * to load a font matching a given description. - */ - #include "config.h" #include <stdlib.h> #include <math.h> @@ -69,21 +56,21 @@ G_DEFINE_BOXED_TYPE (PangoFontDescription, pango_font_description, pango_font_description_free); static const PangoFontDescription pfd_defaults = { - NULL, /* family_name */ + NULL, /* family_name */ - PANGO_STYLE_NORMAL, /* style */ - PANGO_VARIANT_NORMAL, /* variant */ - PANGO_WEIGHT_NORMAL, /* weight */ - PANGO_STRETCH_NORMAL, /* stretch */ + PANGO_STYLE_NORMAL, /* style */ + PANGO_VARIANT_NORMAL, /* variant */ + PANGO_WEIGHT_NORMAL, /* weight */ + PANGO_STRETCH_NORMAL, /* stretch */ PANGO_GRAVITY_SOUTH, /* gravity */ NULL, /* variations */ - 0, /* mask */ - 0, /* static_family */ - 0, /* static_variations*/ - 0, /* size_is_absolute */ + 0, /* mask */ + 0, /* static_family */ + 0, /* static_variations*/ + 0, /* size_is_absolute */ - 0, /* size */ + 0, /* size */ }; /** @@ -91,9 +78,9 @@ static const PangoFontDescription pfd_defaults = { * * Creates a new font description structure with all fields unset. * - * Return value: the newly allocated #PangoFontDescription, which - * should be freed using pango_font_description_free(). - **/ + * Return value: the newly allocated `PangoFontDescription`, which + * should be freed using [method@Pango.FontDescription.free]. + */ PangoFontDescription * pango_font_description_new (void) { @@ -106,18 +93,20 @@ pango_font_description_new (void) /** * pango_font_description_set_family: - * @desc: a #PangoFontDescription. + * @desc: a `PangoFontDescription`. * @family: a string representing the family name. * - * Sets the family name field of a font description. The family + * Sets the family name field of a font description. + * + * The family * name represents a family of related font styles, and will - * resolve to a particular #PangoFontFamily. In some uses of - * #PangoFontDescription, it is also possible to use a comma + * resolve to a particular `PangoFontFamily`. In some uses of + * `PangoFontDescription`, it is also possible to use a comma * separated list of family names for this field. - **/ + */ void pango_font_description_set_family (PangoFontDescription *desc, - const char *family) + const char *family) { g_return_if_fail (desc != NULL); @@ -128,19 +117,20 @@ pango_font_description_set_family (PangoFontDescription *desc, /** * pango_font_description_set_family_static: - * @desc: a #PangoFontDescription - * @family: a string representing the family name. + * @desc: a `PangoFontDescription` + * @family: a string representing the family name * - * Like pango_font_description_set_family(), except that no + * Sets the family name field of a font description, without copying the string. + * + * This is like [method@Pango.FontDescription.set_family], except that no * copy of @family is made. The caller must make sure that the - * string passed in stays around until @desc has been freed - * or the name is set again. This function can be used if - * @family is a static string such as a C string literal, or - * if @desc is only needed temporarily. - **/ + * string passed in stays around until @desc has been freed or the + * name is set again. This function can be used if @family is a static + * string such as a C string literal, or if @desc is only needed temporarily. + */ void pango_font_description_set_family_static (PangoFontDescription *desc, - const char *family) + const char *family) { g_return_if_fail (desc != NULL); @@ -166,16 +156,16 @@ pango_font_description_set_family_static (PangoFontDescription *desc, /** * pango_font_description_get_family: - * @desc: a #PangoFontDescription. + * @desc: a `PangoFontDescription`. + * + * Gets the family name field of a font description. * - * Gets the family name field of a font description. See - * pango_font_description_set_family(). + * See [method@Pango.FontDescription.set_family]. * * Return value: (nullable): the family name field for the font - * description, or %NULL if not previously set. This - * has the same life-time as the font description itself - * and should not be freed. - **/ + * description, or %NULL if not previously set. This has the same + * life-time as the font description itself and should not be freed. + */ const char * pango_font_description_get_family (const PangoFontDescription *desc) { @@ -186,21 +176,23 @@ pango_font_description_get_family (const PangoFontDescription *desc) /** * pango_font_description_set_style: - * @desc: a #PangoFontDescription + * @desc: a `PangoFontDescription` * @style: the style for the font description * - * Sets the style field of a #PangoFontDescription. The - * #PangoStyle enumeration describes whether the font is slanted and - * the manner in which it is slanted; it can be either + * Sets the style field of a `PangoFontDescription`. + * + * The [enum@Pango.Style] enumeration describes whether the font is + * slanted and the manner in which it is slanted; it can be either * #PANGO_STYLE_NORMAL, #PANGO_STYLE_ITALIC, or #PANGO_STYLE_OBLIQUE. - * Most fonts will either have a italic style or an oblique - * style, but not both, and font matching in Pango will - * match italic specifications with oblique fonts and vice-versa - * if an exact match is not found. - **/ + * + * Most fonts will either have a italic style or an oblique style, + * but not both, and font matching in Pango will match italic + * specifications with oblique fonts and vice-versa if an exact + * match is not found. + */ void pango_font_description_set_style (PangoFontDescription *desc, - PangoStyle style) + PangoStyle style) { g_return_if_fail (desc != NULL); @@ -210,15 +202,16 @@ pango_font_description_set_style (PangoFontDescription *desc, /** * pango_font_description_get_style: - * @desc: a #PangoFontDescription + * @desc: a `PangoFontDescription` + * + * Gets the style field of a `PangoFontDescription`. * - * Gets the style field of a #PangoFontDescription. See - * pango_font_description_set_style(). + * See [method@Pango.FontDescription.set_style]. * * Return value: the style field for the font description. - * Use pango_font_description_get_set_fields() to find out if - * the field was explicitly set or not. - **/ + * Use [method@Pango.FontDescription.get_set_fields] to + * find out if the field was explicitly set or not. + */ PangoStyle pango_font_description_get_style (const PangoFontDescription *desc) { @@ -229,15 +222,17 @@ pango_font_description_get_style (const PangoFontDescription *desc) /** * pango_font_description_set_variant: - * @desc: a #PangoFontDescription + * @desc: a `PangoFontDescription` * @variant: the variant type for the font description. * - * Sets the variant field of a font description. The #PangoVariant - * can either be %PANGO_VARIANT_NORMAL or %PANGO_VARIANT_SMALL_CAPS. - **/ + * Sets the variant field of a font description. + * + * The [enum@Pango.Variant] can either be %PANGO_VARIANT_NORMAL + * or %PANGO_VARIANT_SMALL_CAPS. + */ void pango_font_description_set_variant (PangoFontDescription *desc, - PangoVariant variant) + PangoVariant variant) { g_return_if_fail (desc != NULL); @@ -247,15 +242,16 @@ pango_font_description_set_variant (PangoFontDescription *desc, /** * pango_font_description_get_variant: - * @desc: a #PangoFontDescription. + * @desc: a `PangoFontDescription`. + * + * Gets the variant field of a `PangoFontDescription`. * - * Gets the variant field of a #PangoFontDescription. See - * pango_font_description_set_variant(). + * See [method@Pango.FontDescription.set_variant]. * - * Return value: the variant field for the font description. Use - * pango_font_description_get_set_fields() to find out if - * the field was explicitly set or not. - **/ + * Return value: the variant field for the font description. + * Use [method@Pango.FontDescription.get_set_fields] to find + * out if the field was explicitly set or not. + */ PangoVariant pango_font_description_get_variant (const PangoFontDescription *desc) { @@ -266,17 +262,19 @@ pango_font_description_get_variant (const PangoFontDescription *desc) /** * pango_font_description_set_weight: - * @desc: a #PangoFontDescription + * @desc: a `PangoFontDescription` * @weight: the weight for the font description. * - * Sets the weight field of a font description. The weight field + * Sets the weight field of a font description. + * + * The weight field * specifies how bold or light the font should be. In addition - * to the values of the #PangoWeight enumeration, other intermediate - * numeric values are possible. - **/ + * to the values of the [enum@Pango.Weight] enumeration, other + * intermediate numeric values are possible. + */ void pango_font_description_set_weight (PangoFontDescription *desc, - PangoWeight weight) + PangoWeight weight) { g_return_if_fail (desc != NULL); @@ -286,15 +284,16 @@ pango_font_description_set_weight (PangoFontDescription *desc, /** * pango_font_description_get_weight: - * @desc: a #PangoFontDescription + * @desc: a `PangoFontDescription` + * + * Gets the weight field of a font description. * - * Gets the weight field of a font description. See - * pango_font_description_set_weight(). + * See [method@Pango.FontDescription.set_weight]. * - * Return value: the weight field for the font description. Use - * pango_font_description_get_set_fields() to find out if - * the field was explicitly set or not. - **/ + * Return value: the weight field for the font description. + * Use [method@Pango.FontDescription.get_set_fields] to find + * out if the field was explicitly set or not. + */ PangoWeight pango_font_description_get_weight (const PangoFontDescription *desc) { @@ -305,15 +304,17 @@ pango_font_description_get_weight (const PangoFontDescription *desc) /** * pango_font_description_set_stretch: - * @desc: a #PangoFontDescription + * @desc: a `PangoFontDescription` * @stretch: the stretch for the font description * - * Sets the stretch field of a font description. The stretch field - * specifies how narrow or wide the font should be. - **/ + * Sets the stretch field of a font description. + * + * The [enum@Pango.Stretch] field specifies how narrow or + * wide the font should be. + */ void pango_font_description_set_stretch (PangoFontDescription *desc, - PangoStretch stretch) + PangoStretch stretch) { g_return_if_fail (desc != NULL); @@ -323,15 +324,16 @@ pango_font_description_set_stretch (PangoFontDescription *desc, /** * pango_font_description_get_stretch: - * @desc: a #PangoFontDescription. + * @desc: a `PangoFontDescription`. * * Gets the stretch field of a font description. - * See pango_font_description_set_stretch(). * - * Return value: the stretch field for the font description. Use - * pango_font_description_get_set_fields() to find out if - * the field was explicitly set or not. - **/ + * See [method@Pango.FontDescription.set_stretch]. + * + * Return value: the stretch field for the font description. + * Use [method@Pango.FontDescription.get_set_fields] to find + * out if the field was explicitly set or not. + */ PangoStretch pango_font_description_get_stretch (const PangoFontDescription *desc) { @@ -342,21 +344,24 @@ pango_font_description_get_stretch (const PangoFontDescription *desc) /** * pango_font_description_set_size: - * @desc: a #PangoFontDescription - * @size: the size of the font in points, scaled by PANGO_SCALE. (That is, - * a @size value of 10 * PANGO_SCALE is a 10 point font. The conversion - * factor between points and device units depends on system configuration - * and the output device. For screen display, a logical DPI of 96 is - * common, in which case a 10 point font corresponds to a 10 * (96 / 72) = 13.3 - * pixel font. Use pango_font_description_set_absolute_size() if you need - * a particular size in device units. - * - * Sets the size field of a font description in fractional points. This is mutually - * exclusive with pango_font_description_set_absolute_size(). - **/ + * @desc: a `PangoFontDescription` + * @size: the size of the font in points, scaled by %PANGO_SCALE. + * (That is, a @size value of 10 * PANGO_SCALE is a 10 point font. + * The conversion factor between points and device units depends on + * system configuration and the output device. For screen display, a + * logical DPI of 96 is common, in which case a 10 point font corresponds + * to a 10 * (96 / 72) = 13.3 pixel font. + * Use [method@Pango.FontDescription.set_absolute_size] if you need + * a particular size in device units. + * + * Sets the size field of a font description in fractional points. + * + * This is mutually exclusive with + * [method@Pango.FontDescription.set_absolute_size]. + */ void pango_font_description_set_size (PangoFontDescription *desc, - gint size) + gint size) { g_return_if_fail (desc != NULL); g_return_if_fail (size >= 0); @@ -368,18 +373,20 @@ pango_font_description_set_size (PangoFontDescription *desc, /** * pango_font_description_get_size: - * @desc: a #PangoFontDescription + * @desc: a `PangoFontDescription` * * Gets the size field of a font description. - * See pango_font_description_set_size(). * - * Return value: the size field for the font description in points or device units. - * You must call pango_font_description_get_size_is_absolute() - * to find out which is the case. Returns 0 if the size field has not - * previously been set or it has been set to 0 explicitly. - * Use pango_font_description_get_set_fields() to - * find out if the field was explicitly set or not. - **/ + * See [method@Pango.FontDescription.set_size]. + * + * Return value: the size field for the font description in points + * or device units. You must call + * [method@Pango.FontDescription.get_size_is_absolute] to find out + * which is the case. Returns 0 if the size field has not previously + * been set or it has been set to 0 explicitly. + * Use [method@Pango.FontDescription.get_set_fields] to find out + * if the field was explicitly set or not. + */ gint pango_font_description_get_size (const PangoFontDescription *desc) { @@ -390,20 +397,21 @@ pango_font_description_get_size (const PangoFontDescription *desc) /** * pango_font_description_set_absolute_size: - * @desc: a #PangoFontDescription - * @size: the new size, in Pango units. There are %PANGO_SCALE Pango units in one - * device unit. For an output backend where a device unit is a pixel, a @size - * value of 10 * PANGO_SCALE gives a 10 pixel font. + * @desc: a `PangoFontDescription` + * @size: the new size, in Pango units. There are %PANGO_SCALE Pango units + * in one device unit. For an output backend where a device unit is a pixel, + * a @size value of 10 * PANGO_SCALE gives a 10 pixel font. + * + * Sets the size field of a font description, in device units. * - * Sets the size field of a font description, in device units. This is mutually - * exclusive with pango_font_description_set_size() which sets the font size - * in points. + * This is mutually exclusive with [method@Pango.FontDescription.set_size] + * which sets the font size in points. * * Since: 1.8 - **/ + */ void pango_font_description_set_absolute_size (PangoFontDescription *desc, - double size) + double size) { g_return_if_fail (desc != NULL); g_return_if_fail (size >= 0); @@ -415,17 +423,21 @@ pango_font_description_set_absolute_size (PangoFontDescription *desc, /** * pango_font_description_get_size_is_absolute: - * @desc: a #PangoFontDescription + * @desc: a `PangoFontDescription` + * + * Determines whether the size of the font is in points (not absolute) + * or device units (absolute). * - * Determines whether the size of the font is in points (not absolute) or device units (absolute). - * See pango_font_description_set_size() and pango_font_description_set_absolute_size(). + * See [method@Pango.FontDescription.set_size] + * and [method@Pango.FontDescription.set_absolute_size]. * * Return value: whether the size for the font description is in - * points or device units. Use pango_font_description_get_set_fields() to - * find out if the size field of the font description was explicitly set or not. + * points or device units. Use [method@Pango.FontDescription.get_set_fields] + * to find out if the size field of the font description was explicitly + * set or not. * * Since: 1.8 - **/ + */ gboolean pango_font_description_get_size_is_absolute (const PangoFontDescription *desc) { @@ -436,22 +448,24 @@ pango_font_description_get_size_is_absolute (const PangoFontDescription *desc) /** * pango_font_description_set_gravity: - * @desc: a #PangoFontDescription + * @desc: a `PangoFontDescription` * @gravity: the gravity for the font description. * - * Sets the gravity field of a font description. The gravity field - * specifies how the glyphs should be rotated. If @gravity is + * Sets the gravity field of a font description. + * + * The gravity field + * specifies how the glyphs should be rotated. If @gravity is * %PANGO_GRAVITY_AUTO, this actually unsets the gravity mask on * the font description. * - * This function is seldom useful to the user. Gravity should normally - * be set on a #PangoContext. + * This function is seldom useful to the user. Gravity should normally + * be set on a `PangoContext`. * * Since: 1.16 - **/ + */ void pango_font_description_set_gravity (PangoFontDescription *desc, - PangoGravity gravity) + PangoGravity gravity) { g_return_if_fail (desc != NULL); @@ -467,17 +481,18 @@ pango_font_description_set_gravity (PangoFontDescription *desc, /** * pango_font_description_get_gravity: - * @desc: a #PangoFontDescription + * @desc: a `PangoFontDescription` * - * Gets the gravity field of a font description. See - * pango_font_description_set_gravity(). + * Gets the gravity field of a font description. * - * Return value: the gravity field for the font description. Use - * pango_font_description_get_set_fields() to find out if - * the field was explicitly set or not. + * See [method@Pango.FontDescription.set_gravity]. + * + * Return value: the gravity field for the font description. + * Use [method@Pango.FontDescription.get_set_fields] to find out + * if the field was explicitly set or not. * * Since: 1.16 - **/ + */ PangoGravity pango_font_description_get_gravity (const PangoFontDescription *desc) { @@ -488,18 +503,20 @@ pango_font_description_get_gravity (const PangoFontDescription *desc) /** * pango_font_description_set_variations_static: - * @desc: a #PangoFontDescription + * @desc: a `PangoFontDescription` * @variations: a string representing the variations * - * Like pango_font_description_set_variations(), except that no - * copy of @variations is made. The caller must make sure that the - * string passed in stays around until @desc has been freed + * Sets the variations field of a font description. + * + * This is like [method@Pango.FontDescription.set_variations], except + * that no copy of @variations is made. The caller must make sure that + * the string passed in stays around until @desc has been freed * or the name is set again. This function can be used if - * @variations is a static string such as a C string literal, or - * if @desc is only needed temporarily. + * @variations is a static string such as a C string literal, + * or if @desc is only needed temporarily. * * Since: 1.42 - **/ + */ void pango_font_description_set_variations_static (PangoFontDescription *desc, const char *variations) @@ -528,14 +545,18 @@ pango_font_description_set_variations_static (PangoFontDescription *desc, /** * pango_font_description_set_variations: - * @desc: a #PangoFontDescription. + * @desc: a `PangoFontDescription`. * @variations: a string representing the variations * - * Sets the variations field of a font description. OpenType - * font variations allow to select a font instance by specifying - * values for a number of axes, such as width or weight. + * Sets the variations field of a font description. + * + * OpenType font variations allow to select a font instance by + * specifying values for a number of axes, such as width or weight. + * + * The format of the variations string is + * + * AXIS1=VALUE,AXIS2=VALUE... * - * The format of the variations string is AXIS1=VALUE,AXIS2=VALUE..., * with each AXIS a 4 character tag that identifies a font axis, * and each VALUE a floating point number. Unknown axes are ignored, * and values are clamped to their allowed range. @@ -544,7 +565,7 @@ pango_font_description_set_variations_static (PangoFontDescription *desc, * a font. Both harfbuzz or freetype have API for this. * * Since: 1.42 - **/ + */ void pango_font_description_set_variations (PangoFontDescription *desc, const char *variations) @@ -558,18 +579,18 @@ pango_font_description_set_variations (PangoFontDescription *desc, /** * pango_font_description_get_variations: - * @desc: a #PangoFontDescription + * @desc: a `PangoFontDescription` + * + * Gets the variations field of a font description. * - * Gets the variations field of a font description. See - * pango_font_description_set_variations(). + * See [method@Pango.FontDescription.set_variations]. * - * Return value: (nullable): the varitions field for the font - * description, or %NULL if not previously set. This - * has the same life-time as the font description itself - * and should not be freed. + * Return value: (nullable): the variations field for the font + * description, or %NULL if not previously set. This has the same + * life-time as the font description itself and should not be freed. * * Since: 1.42 - **/ + */ const char * pango_font_description_get_variations (const PangoFontDescription *desc) { @@ -580,13 +601,13 @@ pango_font_description_get_variations (const PangoFontDescription *desc) /** * pango_font_description_get_set_fields: - * @desc: a #PangoFontDescription + * @desc: a `PangoFontDescription` * * Determines which fields in a font description have been set. * * Return value: a bitmask with bits set corresponding to the * fields in @desc that have been set. - **/ + */ PangoFontMask pango_font_description_get_set_fields (const PangoFontDescription *desc) { @@ -597,15 +618,16 @@ pango_font_description_get_set_fields (const PangoFontDescription *desc) /** * pango_font_description_unset_fields: - * @desc: a #PangoFontDescription + * @desc: a `PangoFontDescription` * @to_unset: bitmask of fields in the @desc to unset. * - * Unsets some of the fields in a #PangoFontDescription. The unset - * fields will get back to their default values. - **/ + * Unsets some of the fields in a `PangoFontDescription`. + * + * The unset fields will get back to their default values. + */ void pango_font_description_unset_fields (PangoFontDescription *desc, - PangoFontMask to_unset) + PangoFontMask to_unset) { PangoFontDescription unset_desc; @@ -621,23 +643,26 @@ pango_font_description_unset_fields (PangoFontDescription *desc, /** * pango_font_description_merge: - * @desc: a #PangoFontDescription - * @desc_to_merge: (allow-none): the #PangoFontDescription to merge from, or %NULL + * @desc: a `PangoFontDescription` + * @desc_to_merge: (allow-none): the `PangoFontDescription` to merge from, + * or %NULL * @replace_existing: if %TRUE, replace fields in @desc with the * corresponding values from @desc_to_merge, even if they * are already exist. * * Merges the fields that are set in @desc_to_merge into the fields in - * @desc. If @replace_existing is %FALSE, only fields in @desc that + * @desc. + * + * If @replace_existing is %FALSE, only fields in @desc that * are not already set are affected. If %TRUE, then fields that are * already set will be replaced as well. * * If @desc_to_merge is %NULL, this function performs nothing. - **/ + */ void pango_font_description_merge (PangoFontDescription *desc, - const PangoFontDescription *desc_to_merge, - gboolean replace_existing) + const PangoFontDescription *desc_to_merge, + gboolean replace_existing) { gboolean family_merged; gboolean variations_merged; @@ -667,21 +692,24 @@ pango_font_description_merge (PangoFontDescription *desc, /** * pango_font_description_merge_static: - * @desc: a #PangoFontDescription - * @desc_to_merge: the #PangoFontDescription to merge from + * @desc: a `PangoFontDescription` + * @desc_to_merge: the `PangoFontDescription` to merge from * @replace_existing: if %TRUE, replace fields in @desc with the * corresponding values from @desc_to_merge, even if they * are already exist. * - * Like pango_font_description_merge(), but only a shallow copy is made - * of the family name and other allocated fields. @desc can only be - * used until @desc_to_merge is modified or freed. This is meant - * to be used when the merged font description is only needed temporarily. - **/ + * Merges the fields that are set in @desc_to_merge into the fields in + * @desc, without copying allocated fields. + * + * This is like [method@Pango.FontDescription.merge], but only a shallow copy + * is made of the family name and other allocated fields. @desc can only + * be used until @desc_to_merge is modified or freed. This is meant to + * be used when the merged font description is only needed temporarily. + */ void pango_font_description_merge_static (PangoFontDescription *desc, - const PangoFontDescription *desc_to_merge, - gboolean replace_existing) + const PangoFontDescription *desc_to_merge, + gboolean replace_existing) { PangoFontMask new_mask; @@ -718,14 +746,14 @@ pango_font_description_merge_static (PangoFontDescription *desc, static gint compute_distance (const PangoFontDescription *a, - const PangoFontDescription *b) + const PangoFontDescription *b) { if (a->style == b->style) { return abs((int)(a->weight) - (int)(b->weight)); } else if (a->style != PANGO_STYLE_NORMAL && - b->style != PANGO_STYLE_NORMAL) + b->style != PANGO_STYLE_NORMAL) { /* Equate oblique and italic, but with a big penalty */ @@ -737,28 +765,28 @@ compute_distance (const PangoFontDescription *a, /** * pango_font_description_better_match: - * @desc: a #PangoFontDescription - * @old_match: (allow-none): a #PangoFontDescription, or %NULL - * @new_match: a #PangoFontDescription + * @desc: a `PangoFontDescription` + * @old_match: (allow-none): a `PangoFontDescription`, or %NULL + * @new_match: a `PangoFontDescription` * * Determines if the style attributes of @new_match are a closer match * for @desc than those of @old_match are, or if @old_match is %NULL, * determines if @new_match is a match at all. - * Approximate matching is done for - * weight and style; other style attributes must match exactly. - * Style attributes are all attributes other than family and size-related - * attributes. Approximate matching for style considers PANGO_STYLE_OBLIQUE - * and PANGO_STYLE_ITALIC as matches, but not as good a match as when the - * styles are equal. + * + * Approximate matching is done for weight and style; other style attributes + * must match exactly. Style attributes are all attributes other than family + * and size-related attributes. Approximate matching for style considers + * %PANGO_STYLE_OBLIQUE and %PANGO_STYLE_ITALIC as matches, but not as good + * a match as when the styles are equal. * * Note that @old_match must match @desc. * * Return value: %TRUE if @new_match is a better match - **/ + */ gboolean pango_font_description_better_match (const PangoFontDescription *desc, - const PangoFontDescription *old_match, - const PangoFontDescription *new_match) + const PangoFontDescription *old_match, + const PangoFontDescription *new_match) { g_return_val_if_fail (desc != NULL, G_MAXINT); g_return_val_if_fail (new_match != NULL, G_MAXINT); @@ -771,7 +799,7 @@ pango_font_description_better_match (const PangoFontDescription *desc, int new_distance = compute_distance (desc, new_match); if (new_distance < old_distance) - return TRUE; + return TRUE; } return FALSE; @@ -779,17 +807,16 @@ pango_font_description_better_match (const PangoFontDescription *desc, /** * pango_font_description_copy: - * @desc: (nullable): a #PangoFontDescription, may be %NULL + * @desc: (nullable): a `PangoFontDescription`, may be %NULL * - * Make a copy of a #PangoFontDescription. + * Make a copy of a `PangoFontDescription`. * - * Return value: (nullable): the newly allocated - * #PangoFontDescription, which should be freed with - * pango_font_description_free(), or %NULL if @desc was - * %NULL. - **/ + * Return value: (nullable): the newly allocated `PangoFontDescription`, + * which should be freed with [method@Pango.FontDescription.free], + * or %NULL if @desc was %NULL. + */ PangoFontDescription * -pango_font_description_copy (const PangoFontDescription *desc) +pango_font_description_copy (const PangoFontDescription *desc) { PangoFontDescription *result; @@ -814,18 +841,20 @@ pango_font_description_copy (const PangoFontDescription *desc) /** * pango_font_description_copy_static: - * @desc: (nullable): a #PangoFontDescription, may be %NULL - * - * Like pango_font_description_copy(), but only a shallow copy is made - * of the family name and other allocated fields. The result can only - * be used until @desc is modified or freed. This is meant to be used - * when the copy is only needed temporarily. - * - * Return value: (nullable): the newly allocated - * #PangoFontDescription, which should be freed with - * pango_font_description_free(), or %NULL if @desc was - * %NULL. - **/ + * @desc: (nullable): a `PangoFontDescription`, may be %NULL + * + * Make a copy of a `PangoFontDescription`, but don't duplicate + * allocated fields. + * + * This is like [method@Pango.FontDescription.copy], but only a shallow + * copy is made of the family name and other allocated fields. The result + * can only be used until @desc is modified or freed. This is meant + * to be used when the copy is only needed temporarily. + * + * Return value: (nullable): the newly allocated `PangoFontDescription`, + * which should be freed with [method@Pango.FontDescription.free], + * or %NULL if @desc was %NULL. + */ PangoFontDescription * pango_font_description_copy_static (const PangoFontDescription *desc) { @@ -849,34 +878,35 @@ pango_font_description_copy_static (const PangoFontDescription *desc) /** * pango_font_description_equal: - * @desc1: a #PangoFontDescription - * @desc2: another #PangoFontDescription + * @desc1: a `PangoFontDescription` + * @desc2: another `PangoFontDescription` * - * Compares two font descriptions for equality. Two font descriptions - * are considered equal if the fonts they describe are provably identical. - * This means that their masks do not have to match, as long as other fields - * are all the same. (Two font descriptions may result in identical fonts - * being loaded, but still compare %FALSE.) + * Compares two font descriptions for equality. + * + * Two font descriptions are considered equal if the fonts they describe + * are provably identical. This means that their masks do not have to match, + * as long as other fields are all the same. (Two font descriptions may + * result in identical fonts being loaded, but still compare %FALSE.) * * Return value: %TRUE if the two font descriptions are identical, - * %FALSE otherwise. - **/ + * %FALSE otherwise. + */ gboolean -pango_font_description_equal (const PangoFontDescription *desc1, - const PangoFontDescription *desc2) +pango_font_description_equal (const PangoFontDescription *desc1, + const PangoFontDescription *desc2) { g_return_val_if_fail (desc1 != NULL, FALSE); g_return_val_if_fail (desc2 != NULL, FALSE); return desc1->style == desc2->style && - desc1->variant == desc2->variant && - desc1->weight == desc2->weight && - desc1->stretch == desc2->stretch && - desc1->size == desc2->size && - desc1->size_is_absolute == desc2->size_is_absolute && - desc1->gravity == desc2->gravity && - (desc1->family_name == desc2->family_name || - (desc1->family_name && desc2->family_name && g_ascii_strcasecmp (desc1->family_name, desc2->family_name) == 0)) && + desc1->variant == desc2->variant && + desc1->weight == desc2->weight && + desc1->stretch == desc2->stretch && + desc1->size == desc2->size && + desc1->size_is_absolute == desc2->size_is_absolute && + desc1->gravity == desc2->gravity && + (desc1->family_name == desc2->family_name || + (desc1->family_name && desc2->family_name && g_ascii_strcasecmp (desc1->family_name, desc2->family_name) == 0)) && (g_strcmp0 (desc1->variations, desc2->variations) == 0); } @@ -892,7 +922,7 @@ case_insensitive_hash (const char *key) if (h) { for (p += 1; *p != '\0'; p++) - h = (h << 5) - h + TOLOWER (*p); + h = (h << 5) - h + TOLOWER (*p); } return h; @@ -900,14 +930,15 @@ case_insensitive_hash (const char *key) /** * pango_font_description_hash: - * @desc: a #PangoFontDescription + * @desc: a `PangoFontDescription` + * + * Computes a hash of a `PangoFontDescription` structure. * - * Computes a hash of a #PangoFontDescription structure suitable - * to be used, for example, as an argument to g_hash_table_new(). - * The hash value is independent of @desc->mask. + * This is suitable to be used, for example, as an argument + * to g_hash_table_new(). The hash value is independent of @desc->mask. * * Return value: the hash value. - **/ + */ guint pango_font_description_hash (const PangoFontDescription *desc) { @@ -932,12 +963,12 @@ pango_font_description_hash (const PangoFontDescription *desc) /** * pango_font_description_free: - * @desc: (nullable): a #PangoFontDescription, may be %NULL + * @desc: (nullable): a `PangoFontDescription`, may be %NULL * * Frees a font description. - **/ + */ void -pango_font_description_free (PangoFontDescription *desc) +pango_font_description_free (PangoFontDescription *desc) { if (desc == NULL) return; @@ -954,14 +985,14 @@ pango_font_description_free (PangoFontDescription *desc) /** * pango_font_descriptions_free: * @descs: (allow-none) (array length=n_descs) (transfer full): a pointer - * to an array of #PangoFontDescription, may be %NULL + * to an array of `PangoFontDescription`, may be %NULL * @n_descs: number of font descriptions in @descs * * Frees an array of font descriptions. - **/ + */ void pango_font_descriptions_free (PangoFontDescription **descs, - int n_descs) + int n_descs) { int i; @@ -1040,8 +1071,8 @@ static const FieldMap gravity_map[] = { static gboolean field_matches (const gchar *s1, - const gchar *s2, - gsize n) + const gchar *s2, + gsize n) { gint c1, c2; @@ -1054,10 +1085,10 @@ field_matches (const gchar *s1, c2 = (gint)(guchar) TOLOWER (*s2); if (c1 != c2) { if (c1 == '-') { - s1++; - continue; - } - return FALSE; + s1++; + continue; + } + return FALSE; } s1++; s2++; n--; @@ -1068,8 +1099,8 @@ field_matches (const gchar *s1, static gboolean parse_int (const char *word, - size_t wordlen, - int *out) + size_t wordlen, + int *out) { char *end; long val = strtol (word, &end, 10); @@ -1088,11 +1119,11 @@ parse_int (const char *word, static gboolean find_field (const char *what, - const FieldMap *map, - int n_elements, - const char *str, - int len, - int *val) + const FieldMap *map, + int n_elements, + const char *str, + int len, + int *val) { int i; gboolean had_prefix = FALSE; @@ -1101,21 +1132,21 @@ find_field (const char *what, { i = strlen (what); if (len > i && 0 == strncmp (what, str, i) && str[i] == '=') - { - str += i + 1; - len -= i + 1; - had_prefix = TRUE; - } + { + str += i + 1; + len -= i + 1; + had_prefix = TRUE; + } } for (i=0; i<n_elements; i++) { if (map[i].str[0] && field_matches (map[i].str, str, len)) - { - if (val) - *val = map[i].value; - return TRUE; - } + { + if (val) + *val = map[i].value; + return TRUE; + } } if (!what || had_prefix) @@ -1133,10 +1164,10 @@ find_field_any (const char *str, int len, PangoFontDescription *desc) #define FIELD(NAME, MASK) \ G_STMT_START { \ if (find_field (G_STRINGIFY (NAME), NAME##_map, G_N_ELEMENTS (NAME##_map), str, len, \ - desc ? (int *)(void *)&desc->NAME : NULL)) \ + desc ? (int *)(void *)&desc->NAME : NULL)) \ { \ if (desc) \ - desc->mask |= MASK; \ + desc->mask |= MASK; \ return TRUE; \ } \ } G_STMT_END @@ -1171,9 +1202,9 @@ getword (const char *str, const char *last, size_t *wordlen, const char *stop) static gboolean parse_size (const char *word, - size_t wordlen, - int *pango_size, - gboolean *size_is_absolute) + size_t wordlen, + int *pango_size, + gboolean *size_is_absolute) { char *end; double size = g_ascii_strtod (word, &end); @@ -1184,10 +1215,10 @@ parse_size (const char *word, ) && size >= 0 && size <= 1000000) /* word is a valid float */ { if (pango_size) - *pango_size = (int)(size * PANGO_SCALE + 0.5); + *pango_size = (int)(size * PANGO_SCALE + 0.5); if (size_is_absolute) - *size_is_absolute = end < word + wordlen; + *size_is_absolute = end < word + wordlen; return TRUE; } @@ -1216,10 +1247,11 @@ parse_variations (const char *word, * pango_font_description_from_string: * @str: string representation of a font description. * - * Creates a new font description from a string representation in the - * form + * Creates a new font description from a string representation. + * + * The string must have the form * - * "\[FAMILY-LIST] \[STYLE-OPTIONS] \[SIZE] \[VARIATIONS]", + * "\[FAMILY-LIST] \[STYLE-OPTIONS] \[SIZE] \[VARIATIONS]", * * where FAMILY-LIST is a comma-separated list of families optionally * terminated by a comma, STYLE_OPTIONS is a whitespace-separated list @@ -1257,10 +1289,10 @@ parse_variations (const char *word, * * A typical example: * - * "Cantarell Italic Light 15 \@wght=200" + * "Cantarell Italic Light 15 \@wght=200" * - * Return value: a new #PangoFontDescription. - **/ + * Return value: a new `PangoFontDescription`. + */ PangoFontDescription * pango_font_description_from_string (const char *str) { @@ -1273,9 +1305,9 @@ pango_font_description_from_string (const char *str) desc = pango_font_description_new (); desc->mask = PANGO_FONT_MASK_STYLE | - PANGO_FONT_MASK_WEIGHT | - PANGO_FONT_MASK_VARIANT | - PANGO_FONT_MASK_STRETCH; + PANGO_FONT_MASK_WEIGHT | + PANGO_FONT_MASK_VARIANT | + PANGO_FONT_MASK_STRETCH; len = strlen (str); last = str + len; @@ -1285,8 +1317,8 @@ pango_font_description_from_string (const char *str) { if (parse_variations (p, wordlen, &desc->variations)) { - desc->mask |= PANGO_FONT_MASK_VARIATIONS; - last = p; + desc->mask |= PANGO_FONT_MASK_VARIATIONS; + last = p; } } @@ -1296,11 +1328,11 @@ pango_font_description_from_string (const char *str) { gboolean size_is_absolute; if (parse_size (p, wordlen, &desc->size, &size_is_absolute)) - { - desc->size_is_absolute = size_is_absolute; - desc->mask |= PANGO_FONT_MASK_SIZE; - last = p; - } + { + desc->size_is_absolute = size_is_absolute; + desc->mask |= PANGO_FONT_MASK_SIZE; + last = p; + } } /* Now parse style words @@ -1309,12 +1341,12 @@ pango_font_description_from_string (const char *str) while (wordlen != 0) { if (!find_field_any (p, wordlen, desc)) - break; + break; else - { - last = p; - p = getword (str, last, &wordlen, ","); - } + { + last = p; + p = getword (str, last, &wordlen, ","); + } } /* Remainder (str => p) is family list. Trim off trailing commas and leading and trailing white space @@ -1345,7 +1377,7 @@ pango_font_description_from_string (const char *str) families = g_strsplit (desc->family_name, ",", -1); for (i = 0; families[i]; i++) - g_strstrip (families[i]); + g_strstrip (families[i]); g_free (desc->family_name); desc->family_name = g_strjoinv (",", families); @@ -1367,11 +1399,11 @@ append_field (GString *str, const char *what, const FieldMap *map, int n_element continue; if (G_LIKELY (map[i].str[0])) - { - if (G_LIKELY (str->len > 0 && str->str[str->len -1] != ' ')) - g_string_append_c (str, ' '); - g_string_append (str, map[i].str); - } + { + if (G_LIKELY (str->len > 0 && str->str[str->len -1] != ' ')) + g_string_append_c (str, ' '); + g_string_append (str, map[i].str); + } return; } @@ -1382,18 +1414,19 @@ append_field (GString *str, const char *what, const FieldMap *map, int n_element /** * pango_font_description_to_string: - * @desc: a #PangoFontDescription + * @desc: a `PangoFontDescription` * - * Creates a string representation of a font description. See - * pango_font_description_from_string() for a description of the - * format of the string representation. The family list in the - * string description will only have a terminating comma if the - * last word of the list is a valid style option. + * Creates a string representation of a font description. + * + * See [type_func@Pango.FontDescription.from_string] for a description + * of the format of the string representation. The family list in + * the string description will only have a terminating comma if + * the last word of the list is a valid style option. * * Return value: a new string that must be freed with g_free(). - **/ + */ char * -pango_font_description_to_string (const PangoFontDescription *desc) +pango_font_description_to_string (const PangoFontDescription *desc) { GString *result; @@ -1414,14 +1447,14 @@ pango_font_description_to_string (const PangoFontDescription *desc) */ p = getword (desc->family_name, desc->family_name + strlen(desc->family_name), &wordlen, ","); if (wordlen != 0 && - (find_field_any (p, wordlen, NULL) || - (parse_size (p, wordlen, NULL, NULL) && - desc->weight == PANGO_WEIGHT_NORMAL && - desc->style == PANGO_STYLE_NORMAL && - desc->stretch == PANGO_STRETCH_NORMAL && - desc->variant == PANGO_VARIANT_NORMAL && - (desc->mask & (PANGO_FONT_MASK_GRAVITY | PANGO_FONT_MASK_SIZE)) == 0))) - g_string_append_c (result, ','); + (find_field_any (p, wordlen, NULL) || + (parse_size (p, wordlen, NULL, NULL) && + desc->weight == PANGO_WEIGHT_NORMAL && + desc->style == PANGO_STYLE_NORMAL && + desc->stretch == PANGO_STRETCH_NORMAL && + desc->variant == PANGO_VARIANT_NORMAL && + (desc->mask & (PANGO_FONT_MASK_GRAVITY | PANGO_FONT_MASK_SIZE)) == 0))) + g_string_append_c (result, ','); } #define FIELD(NAME, MASK) \ @@ -1444,13 +1477,13 @@ pango_font_description_to_string (const PangoFontDescription *desc) char buf[G_ASCII_DTOSTR_BUF_SIZE]; if (result->len > 0 || result->str[result->len -1] != ' ') - g_string_append_c (result, ' '); + g_string_append_c (result, ' '); g_ascii_dtostr (buf, sizeof (buf), (double)desc->size / PANGO_SCALE); g_string_append (result, buf); if (desc->size_is_absolute) - g_string_append (result, "px"); + g_string_append (result, "px"); } if (desc->variations && desc->mask & PANGO_FONT_MASK_VARIATIONS) @@ -1464,17 +1497,19 @@ pango_font_description_to_string (const PangoFontDescription *desc) /** * pango_font_description_to_filename: - * @desc: a #PangoFontDescription + * @desc: a `PangoFontDescription` + * + * Creates a filename representation of a font description. * - * Creates a filename representation of a font description. The - * filename is identical to the result from calling - * pango_font_description_to_string(), but with underscores instead of - * characters that are untypical in filenames, and in lower case only. + * The filename is identical to the result from calling + * [method@Pango.FontDescription.to_string], but with underscores + * instead of characters that are untypical in filenames, and in + * lower case only. * * Return value: a new string that must be freed with g_free(). - **/ + */ char * -pango_font_description_to_filename (const PangoFontDescription *desc) +pango_font_description_to_filename (const PangoFontDescription *desc) { char *result; char *p; @@ -1489,23 +1524,22 @@ pango_font_description_to_filename (const PangoFontDescription *desc) if (G_UNLIKELY ((guchar) *p >= 128)) /* skip over non-ASCII chars */; else if (strchr ("-+_.", *p) == NULL && !g_ascii_isalnum (*p)) - *p = '_'; + *p = '_'; else - *p = g_ascii_tolower (*p); + *p = g_ascii_tolower (*p); p++; } return result; } - static gboolean parse_field (const char *what, - const FieldMap *map, - int n_elements, - const char *str, - int *val, - gboolean warn) + const FieldMap *map, + int n_elements, + const char *str, + int *val, + gboolean warn) { gboolean found; int len = strlen (str); @@ -1520,10 +1554,10 @@ parse_field (const char *what, for (i = 0; i < n_elements; i++) if (map[i].str[0] == '\0') - { - *val = map[i].value; - return TRUE; - } + { + *val = map[i].value; + return TRUE; + } *val = 0; return TRUE; @@ -1533,21 +1567,21 @@ parse_field (const char *what, if (!found && warn) { - int i; - GString *s = g_string_new (NULL); + int i; + GString *s = g_string_new (NULL); - for (i = 0; i < n_elements; i++) - { - if (i) - g_string_append_c (s, '/'); - g_string_append (s, map[i].str[0] == '\0' ? "Normal" : map[i].str); - } + for (i = 0; i < n_elements; i++) + { + if (i) + g_string_append_c (s, '/'); + g_string_append (s, map[i].str[0] == '\0' ? "Normal" : map[i].str); + } - g_warning ("%s must be one of %s or a number", - what, - s->str); + g_warning ("%s must be one of %s or a number", + what, + s->str); - g_string_free (s, TRUE); + g_string_free (s, TRUE); } return found; @@ -1559,20 +1593,21 @@ parse_field (const char *what, /** * pango_parse_style: * @str: a string to parse. - * @style: (out): a #PangoStyle to store the result - * in. + * @style: (out): a `PangoStyle` to store the result in. * @warn: if %TRUE, issue a g_warning() on bad input. * - * Parses a font style. The allowed values are "normal", - * "italic" and "oblique", case variations being + * Parses a font style. + * + * The allowed values are "normal", "italic" and "oblique", case + * variations being * ignored. * * Return value: %TRUE if @str was successfully parsed. - **/ + */ gboolean pango_parse_style (const char *str, - PangoStyle *style, - gboolean warn) + PangoStyle *style, + gboolean warn) { return FIELD (style, PANGO_FONT_MASK_STYLE); } @@ -1580,20 +1615,20 @@ pango_parse_style (const char *str, /** * pango_parse_variant: * @str: a string to parse. - * @variant: (out): a #PangoVariant to store the - * result in. + * @variant: (out): a `PangoVariant` to store the result in. * @warn: if %TRUE, issue a g_warning() on bad input. * - * Parses a font variant. The allowed values are "normal" - * and "smallcaps" or "small_caps", case variations being - * ignored. + * Parses a font variant. + * + * The allowed values are "normal" and "smallcaps" or "small_caps", + * case variations being ignored. * * Return value: %TRUE if @str was successfully parsed. - **/ + */ gboolean pango_parse_variant (const char *str, - PangoVariant *variant, - gboolean warn) + PangoVariant *variant, + gboolean warn) { return FIELD (variant, PANGO_FONT_MASK_VARIANT); } @@ -1601,20 +1636,21 @@ pango_parse_variant (const char *str, /** * pango_parse_weight: * @str: a string to parse. - * @weight: (out): a #PangoWeight to store the result - * in. + * @weight: (out): a `PangoWeight` to store the result in. * @warn: if %TRUE, issue a g_warning() on bad input. * - * Parses a font weight. The allowed values are "heavy", + * Parses a font weight. + * + * The allowed values are "heavy", * "ultrabold", "bold", "normal", "light", "ultraleight" * and integers. Case variations are ignored. * * Return value: %TRUE if @str was successfully parsed. - **/ + */ gboolean pango_parse_weight (const char *str, - PangoWeight *weight, - gboolean warn) + PangoWeight *weight, + gboolean warn) { return FIELD (weight, PANGO_FONT_MASK_WEIGHT); } @@ -1622,29 +1658,28 @@ pango_parse_weight (const char *str, /** * pango_parse_stretch: * @str: a string to parse. - * @stretch: (out): a #PangoStretch to store the - * result in. + * @stretch: (out): a `PangoStretch` to store the result in. * @warn: if %TRUE, issue a g_warning() on bad input. * - * Parses a font stretch. The allowed values are + * Parses a font stretch. + * + * The allowed values are * "ultra_condensed", "extra_condensed", "condensed", * "semi_condensed", "normal", "semi_expanded", "expanded", * "extra_expanded" and "ultra_expanded". Case variations are * ignored and the '_' characters may be omitted. * * Return value: %TRUE if @str was successfully parsed. - **/ + */ gboolean pango_parse_stretch (const char *str, - PangoStretch *stretch, - gboolean warn) + PangoStretch *stretch, + gboolean warn) { return FIELD (stretch, PANGO_FONT_MASK_STRETCH); } - - /* * PangoFont */ @@ -1681,16 +1716,17 @@ pango_font_init (PangoFont *font G_GNUC_UNUSED) /** * pango_font_describe: - * @font: a #PangoFont + * @font: a `PangoFont` * * Returns a description of the font, with font size set in points. - * Use pango_font_describe_with_absolute_size() if you want the font - * size in device units. * - * Return value: a newly-allocated #PangoFontDescription object. - **/ + * Use [method@Pango.Font.describe_with_absolute_size] if you want + * the font size in device units. + * + * Return value: a newly-allocated `PangoFontDescription` object. + */ PangoFontDescription * -pango_font_describe (PangoFont *font) +pango_font_describe (PangoFont *font) { g_return_val_if_fail (font != NULL, NULL); @@ -1699,18 +1735,19 @@ pango_font_describe (PangoFont *font) /** * pango_font_describe_with_absolute_size: - * @font: a #PangoFont + * @font: a `PangoFont` * * Returns a description of the font, with absolute font size set - * (in device units). Use pango_font_describe() if you want the font - * size in points. + * in device units. * - * Return value: a newly-allocated #PangoFontDescription object. + * Use [method@Pango.Font.describe] if you want the font size in points. + * + * Return value: a newly-allocated `PangoFontDescription` object. * * Since: 1.14 - **/ + */ PangoFontDescription * -pango_font_describe_with_absolute_size (PangoFont *font) +pango_font_describe_with_absolute_size (PangoFont *font) { g_return_val_if_fail (font != NULL, NULL); @@ -1725,17 +1762,17 @@ pango_font_describe_with_absolute_size (PangoFont *font) /** * pango_font_get_coverage: - * @font: a #PangoFont + * @font: a `PangoFont` * @language: the language tag * * Computes the coverage map for a given font and language tag. * - * Return value: (transfer full): a newly-allocated #PangoCoverage + * Return value: (transfer full): a newly-allocated `PangoCoverage` * object. - **/ + */ PangoCoverage * pango_font_get_coverage (PangoFont *font, - PangoLanguage *language) + PangoLanguage *language) { g_return_val_if_fail (font != NULL, NULL); @@ -1744,7 +1781,7 @@ pango_font_get_coverage (PangoFont *font, /** * pango_font_find_shaper: - * @font: a #PangoFont + * @font: a `PangoFont` * @language: the language tag * @ch: a Unicode character. * @@ -1753,26 +1790,27 @@ pango_font_get_coverage (PangoFont *font, * * Return value: (transfer none): the best matching shaper. * Deprecated: Shape engines are no longer used - **/ + */ PangoEngineShape * pango_font_find_shaper (PangoFont *font, - PangoLanguage *language, - guint32 ch) + PangoLanguage *language, + guint32 ch) { return NULL; } /** * pango_font_get_glyph_extents: - * @font: (nullable): a #PangoFont + * @font: (nullable): a `PangoFont` * @glyph: the glyph index * @ink_rect: (out) (allow-none): rectangle used to store the extents of the glyph * as drawn or %NULL to indicate that the result is not needed. * @logical_rect: (out) (allow-none): rectangle used to store the logical extents of * the glyph or %NULL to indicate that the result is not needed. * - * Gets the logical and ink extents of a glyph within a font. The - * coordinate system for each rectangle has its origin at the + * Gets the logical and ink extents of a glyph within a font. + * + * The coordinate system for each rectangle has its origin at the * base line and horizontal origin of the character with increasing * coordinates extending to the right and down. The macros PANGO_ASCENT(), * PANGO_DESCENT(), PANGO_LBEARING(), and PANGO_RBEARING() can be used to convert @@ -1781,29 +1819,29 @@ pango_font_find_shaper (PangoFont *font, * * If @font is %NULL, this function gracefully sets some sane values in the * output variables and returns. - **/ + */ void pango_font_get_glyph_extents (PangoFont *font, - PangoGlyph glyph, - PangoRectangle *ink_rect, - PangoRectangle *logical_rect) + PangoGlyph glyph, + PangoRectangle *ink_rect, + PangoRectangle *logical_rect) { if (G_UNLIKELY (!font)) { if (ink_rect) - { - ink_rect->x = PANGO_SCALE; - ink_rect->y = - (PANGO_UNKNOWN_GLYPH_HEIGHT - 1) * PANGO_SCALE; - ink_rect->height = (PANGO_UNKNOWN_GLYPH_HEIGHT - 2) * PANGO_SCALE; - ink_rect->width = (PANGO_UNKNOWN_GLYPH_WIDTH - 2) * PANGO_SCALE; - } + { + ink_rect->x = PANGO_SCALE; + ink_rect->y = - (PANGO_UNKNOWN_GLYPH_HEIGHT - 1) * PANGO_SCALE; + ink_rect->height = (PANGO_UNKNOWN_GLYPH_HEIGHT - 2) * PANGO_SCALE; + ink_rect->width = (PANGO_UNKNOWN_GLYPH_WIDTH - 2) * PANGO_SCALE; + } if (logical_rect) - { - logical_rect->x = 0; - logical_rect->y = - PANGO_UNKNOWN_GLYPH_HEIGHT * PANGO_SCALE; - logical_rect->height = PANGO_UNKNOWN_GLYPH_HEIGHT * PANGO_SCALE; - logical_rect->width = PANGO_UNKNOWN_GLYPH_WIDTH * PANGO_SCALE; - } + { + logical_rect->x = 0; + logical_rect->y = - PANGO_UNKNOWN_GLYPH_HEIGHT * PANGO_SCALE; + logical_rect->height = PANGO_UNKNOWN_GLYPH_HEIGHT * PANGO_SCALE; + logical_rect->width = PANGO_UNKNOWN_GLYPH_WIDTH * PANGO_SCALE; + } return; } @@ -1812,24 +1850,26 @@ pango_font_get_glyph_extents (PangoFont *font, /** * pango_font_get_metrics: - * @font: (nullable): a #PangoFont - * @language: (allow-none): language tag used to determine which script to get the metrics - * for, or %NULL to indicate to get the metrics for the entire font. + * @font: (nullable): a `PangoFont` + * @language: (allow-none): language tag used to determine which script + * to get the metrics for, or %NULL to indicate to get the metrics for + * the entire font. + * + * Gets overall metric information for a font. * - * Gets overall metric information for a font. Since the metrics may be - * substantially different for different scripts, a language tag can - * be provided to indicate that the metrics should be retrieved that - * correspond to the script(s) used by that language. + * Since the metrics may be substantially different for different scripts, + * a language tag can be provided to indicate that the metrics should be + * retrieved that correspond to the script(s) used by that language. * * If @font is %NULL, this function gracefully sets some sane values in the * output variables and returns. * - * Return value: a #PangoFontMetrics object. The caller must call pango_font_metrics_unref() - * when finished using the object. - **/ + * Return value: a `PangoFontMetrics` object. The caller must call + * [method@Pango.FontMetrics.unref] when finished using the object. + */ PangoFontMetrics * -pango_font_get_metrics (PangoFont *font, - PangoLanguage *language) +pango_font_get_metrics (PangoFont *font, + PangoLanguage *language) { if (G_UNLIKELY (!font)) { @@ -1853,23 +1893,24 @@ pango_font_get_metrics (PangoFont *font, /** * pango_font_get_font_map: - * @font: (nullable): a #PangoFont, or %NULL + * @font: (nullable): a `PangoFont`, or %NULL * * Gets the font map for which the font was created. * - * Note that the font maintains a <firstterm>weak</firstterm> reference - * to the font map, so if all references to font map are dropped, the font - * map will be finalized even if there are fonts created with the font - * map that are still alive. In that case this function will return %NULL. + * Note that the font maintains a *weak* reference to the font map, so if + * all references to font map are dropped, the font map will be finalized + * even if there are fonts created with the font map that are still alive. + * In that case this function will return %NULL. + * * It is the responsibility of the user to ensure that the font map is kept - * alive. In most uses this is not an issue as a #PangoContext holds + * alive. In most uses this is not an issue as a #PangoContext holds * a reference to the font map. * - * Return value: (transfer none) (nullable): the #PangoFontMap for the - * font, or %NULL if @font is %NULL. + * Return value: (transfer none) (nullable): the `PangoFontMap` for the + * font, or %NULL if @font is %NULL. * * Since: 1.10 - **/ + */ PangoFontMap * pango_font_get_font_map (PangoFont *font) { @@ -1884,11 +1925,11 @@ pango_font_get_font_map (PangoFont *font) /** * pango_font_get_face: - * @font: a #PangoFont + * @font: a `PangoFont` * - * Gets the #PangoFontFace to which @font belongs. + * Gets the `PangoFontFace` to which @font belongs. * - * Returns: (transfer none): the #PangoFontFace + * Returns: (transfer none): the `PangoFontFace` * * Since: 1.46 */ @@ -1902,16 +1943,15 @@ pango_font_get_face (PangoFont *font) /** * pango_font_get_hb_font: (skip) - * @font: a #PangoFont + * @font: a `PangoFont` * - * Get a hb_font_t object backing this font. + * Get a `hb_font_t` object backing this font. * - * Note that the objects returned by this function - * are cached and immutable. If you need to make - * changes to the hb_font_t, use hb_font_create_sub_font(). + * Note that the objects returned by this function are cached and immutable. + * If you need to make changes to the `hb_font_t`, use hb_font_create_sub_font(). * - * Returns: (transfer none) (nullable): the hb_font_t object backing the - * font, or %NULL if the font does not have one + * Returns: (transfer none) (nullable): the `hb_font_t` object backing the + * font, or %NULL if the font does not have one * * Since: 1.44 */ @@ -1939,13 +1979,14 @@ G_DEFINE_BOXED_TYPE (PangoFontMetrics, pango_font_metrics, /** * pango_font_metrics_new: * - * Creates a new #PangoFontMetrics structure. This is only for - * internal use by Pango backends and there is no public way - * to set the fields of the structure. + * Creates a new `PangoFontMetrics` structure. * - * Return value: a newly-created #PangoFontMetrics structure + * This is only for internal use by Pango backends and there is + * no public way to set the fields of the structure. + * + * Return value: a newly-created `PangoFontMetrics` structure * with a reference count of 1. - **/ + */ PangoFontMetrics * pango_font_metrics_new (void) { @@ -1957,12 +1998,12 @@ pango_font_metrics_new (void) /** * pango_font_metrics_ref: - * @metrics: (nullable): a #PangoFontMetrics structure, may be %NULL + * @metrics: (nullable): a `PangoFontMetrics` structure, may be %NULL * * Increase the reference count of a font metrics structure by one. * * Return value: (nullable): @metrics - **/ + */ PangoFontMetrics * pango_font_metrics_ref (PangoFontMetrics *metrics) { @@ -1976,12 +2017,11 @@ pango_font_metrics_ref (PangoFontMetrics *metrics) /** * pango_font_metrics_unref: - * @metrics: (nullable): a #PangoFontMetrics structure, may be %NULL + * @metrics: (nullable): a `PangoFontMetrics` structure, may be %NULL * - * Decrease the reference count of a font metrics structure by one. If - * the result is zero, frees the structure and any associated - * memory. - **/ + * Decrease the reference count of a font metrics structure by one. + * If the result is zero, frees the structure and any associated memory. + */ void pango_font_metrics_unref (PangoFontMetrics *metrics) { @@ -1996,16 +2036,17 @@ pango_font_metrics_unref (PangoFontMetrics *metrics) /** * pango_font_metrics_get_ascent: - * @metrics: a #PangoFontMetrics structure + * @metrics: a `PangoFontMetrics` structure + * + * Gets the ascent from a font metrics structure. * - * Gets the ascent from a font metrics structure. The ascent is - * the distance from the baseline to the logical top of a line - * of text. (The logical top may be above or below the top of the - * actual drawn ink. It is necessary to lay out the text to figure - * where the ink will be.) + * The ascent is the distance from the baseline to the logical top + * of a line of text. (The logical top may be above or below the top + * of the actual drawn ink. It is necessary to lay out the text to + * figure where the ink will be.) * * Return value: the ascent, in Pango units. - **/ + */ int pango_font_metrics_get_ascent (PangoFontMetrics *metrics) { @@ -2016,16 +2057,17 @@ pango_font_metrics_get_ascent (PangoFontMetrics *metrics) /** * pango_font_metrics_get_descent: - * @metrics: a #PangoFontMetrics structure + * @metrics: a `PangoFontMetrics` structure + * + * Gets the descent from a font metrics structure. * - * Gets the descent from a font metrics structure. The descent is - * the distance from the baseline to the logical bottom of a line - * of text. (The logical bottom may be above or below the bottom of the - * actual drawn ink. It is necessary to lay out the text to figure - * where the ink will be.) + * The descent is the distance from the baseline to the logical bottom + * of a line of text. (The logical bottom may be above or below the + * bottom of the actual drawn ink. It is necessary to lay out the text + * to figure where the ink will be.) * * Return value: the descent, in Pango units. - **/ + */ int pango_font_metrics_get_descent (PangoFontMetrics *metrics) { @@ -2036,10 +2078,11 @@ pango_font_metrics_get_descent (PangoFontMetrics *metrics) /** * pango_font_metrics_get_height: - * @metrics: a #PangoFontMetrics structure + * @metrics: a `PangoFontMetrics` structure * - * Gets the line height from a font metrics structure. The - * line height is the distance between successive baselines + * Gets the line height from a font metrics structure. + * + * The line height is the distance between successive baselines * in wrapped text. * * If the line height is not available, 0 is returned. @@ -2058,15 +2101,16 @@ pango_font_metrics_get_height (PangoFontMetrics *metrics) /** * pango_font_metrics_get_approximate_char_width: - * @metrics: a #PangoFontMetrics structure + * @metrics: a `PangoFontMetrics` structure * * Gets the approximate character width for a font metrics structure. + * * This is merely a representative value useful, for example, for * determining the initial size for a window. Actual characters in * text will be wider and narrower than this. * * Return value: the character width, in Pango units. - **/ + */ int pango_font_metrics_get_approximate_char_width (PangoFontMetrics *metrics) { @@ -2077,9 +2121,10 @@ pango_font_metrics_get_approximate_char_width (PangoFontMetrics *metrics) /** * pango_font_metrics_get_approximate_digit_width: - * @metrics: a #PangoFontMetrics structure + * @metrics: a `PangoFontMetrics` structure * * Gets the approximate digit width for a font metrics structure. + * * This is merely a representative value useful, for example, for * determining the initial size for a window. Actual digits in * text can be wider or narrower than this, though this value @@ -2087,7 +2132,7 @@ pango_font_metrics_get_approximate_char_width (PangoFontMetrics *metrics) * pango_font_metrics_get_approximate_char_width() for digits. * * Return value: the digit width, in Pango units. - **/ + */ int pango_font_metrics_get_approximate_digit_width (PangoFontMetrics *metrics) { @@ -2098,18 +2143,18 @@ pango_font_metrics_get_approximate_digit_width (PangoFontMetrics *metrics) /** * pango_font_metrics_get_underline_position: - * @metrics: a #PangoFontMetrics structure + * @metrics: a `PangoFontMetrics` structure * * Gets the suggested position to draw the underline. - * The value returned is the distance <emphasis>above</emphasis> the - * baseline of the top of the underline. Since most fonts have - * underline positions beneath the baseline, this value is typically - * negative. + * + * The value returned is the distance *above* the baseline of the top + * of the underline. Since most fonts have underline positions beneath + * the baseline, this value is typically negative. * * Return value: the suggested underline position, in Pango units. * * Since: 1.6 - **/ + */ int pango_font_metrics_get_underline_position (PangoFontMetrics *metrics) { @@ -2120,14 +2165,14 @@ pango_font_metrics_get_underline_position (PangoFontMetrics *metrics) /** * pango_font_metrics_get_underline_thickness: - * @metrics: a #PangoFontMetrics structure + * @metrics: a `PangoFontMetrics` structure * * Gets the suggested thickness to draw for the underline. * * Return value: the suggested underline thickness, in Pango units. * * Since: 1.6 - **/ + */ int pango_font_metrics_get_underline_thickness (PangoFontMetrics *metrics) { @@ -2138,16 +2183,17 @@ pango_font_metrics_get_underline_thickness (PangoFontMetrics *metrics) /** * pango_font_metrics_get_strikethrough_position: - * @metrics: a #PangoFontMetrics structure + * @metrics: a `PangoFontMetrics` structure * * Gets the suggested position to draw the strikethrough. - * The value returned is the distance <emphasis>above</emphasis> the + * + * The value returned is the distance *above* the * baseline of the top of the strikethrough. * * Return value: the suggested strikethrough position, in Pango units. * * Since: 1.6 - **/ + */ int pango_font_metrics_get_strikethrough_position (PangoFontMetrics *metrics) { @@ -2158,14 +2204,14 @@ pango_font_metrics_get_strikethrough_position (PangoFontMetrics *metrics) /** * pango_font_metrics_get_strikethrough_thickness: - * @metrics: a #PangoFontMetrics structure + * @metrics: a `PangoFontMetrics` structure * * Gets the suggested thickness to draw for the strikethrough. * * Return value: the suggested strikethrough thickness, in Pango units. * * Since: 1.6 - **/ + */ int pango_font_metrics_get_strikethrough_thickness (PangoFontMetrics *metrics) { @@ -2243,15 +2289,17 @@ pango_font_family_init (PangoFontFamily *family G_GNUC_UNUSED) /** * pango_font_family_get_name: - * @family: a #PangoFontFamily + * @family: a `PangoFontFamily` * - * Gets the name of the family. The name is unique among all - * fonts for the font backend and can be used in a #PangoFontDescription - * to specify that a face from this family is desired. + * Gets the name of the family. + * + * The name is unique among all fonts for the font backend and can + * be used in a `PangoFontDescription` to specify that a face from + * this family is desired. * * Return value: the name of the family. This string is owned * by the family object and must not be modified or freed. - **/ + */ const char * pango_font_family_get_name (PangoFontFamily *family) { @@ -2262,21 +2310,22 @@ pango_font_family_get_name (PangoFontFamily *family) /** * pango_font_family_list_faces: - * @family: a #PangoFontFamily + * @family: a `PangoFontFamily` * @faces: (out) (allow-none) (array length=n_faces) (transfer container): - * location to store an array of pointers to #PangoFontFace objects, + * location to store an array of pointers to `PangoFontFace` objects, * or %NULL. This array should be freed with g_free() when it is no * longer needed. * @n_faces: (out): location to store number of elements in @faces. * - * Lists the different font faces that make up @family. The faces - * in a family share a common design, but differ in slant, weight, + * Lists the different font faces that make up @family. + * + * The faces in a family share a common design, but differ in slant, weight, * width and other aspects. - **/ + */ void pango_font_family_list_faces (PangoFontFamily *family, - PangoFontFace ***faces, - int *n_faces) + PangoFontFace ***faces, + int *n_faces) { g_return_if_fail (PANGO_IS_FONT_FAMILY (family)); @@ -2318,14 +2367,14 @@ pango_font_family_real_get_face (PangoFontFamily *family, /** * pango_font_family_get_face: - * @family: a #PangoFontFamily + * @family: a `PangoFontFamily` * @name: (nullable): the name of a face. If the name is %NULL, * the family's default face (fontconfig calls it "Regular") * will be returned. * - * Gets the #PangoFontFace of @family with the given name. + * Gets the `PangoFontFace` of @family with the given name. * - * Returns: (transfer none) (nullable): the #PangoFontFace, + * Returns: (transfer none) (nullable): the `PangoFontFace`, * or %NULL if no face with the given name exists. * * Since: 1.46 @@ -2341,10 +2390,12 @@ pango_font_family_get_face (PangoFontFamily *family, /** * pango_font_family_is_monospace: - * @family: a #PangoFontFamily + * @family: a `PangoFontFamily` * * A monospace font is a font designed for text display where the the - * characters form a regular grid. For Western languages this would + * characters form a regular grid. + * + * For Western languages this would * mean that the advance width of all characters are the same, but * this categorization also includes Asian fonts which include * double-width characters: characters that occupy two grid cells. @@ -2352,14 +2403,14 @@ pango_font_family_get_face (PangoFontFamily *family, * character is typically double-width in a monospace font. * * The best way to find out the grid-cell size is to call - * pango_font_metrics_get_approximate_digit_width(), since the results - * of pango_font_metrics_get_approximate_char_width() may be affected - * by double-width characters. + * [method@Pango.FontMetrics.get_approximate_digit_width], since the + * results of [method@Pango.FontMetrics.get_approximate_char_width] may + * be affected by double-width characters. * * Return value: %TRUE if the family is monospace. * * Since: 1.4 - **/ + */ gboolean pango_font_family_is_monospace (PangoFontFamily *family) { @@ -2373,7 +2424,7 @@ pango_font_family_is_monospace (PangoFontFamily *family) /** * pango_font_family_is_variable: - * @family: a #PangoFontFamily + * @family: a `PangoFontFamily` * * A variable font is a font which has axes that can be modified to * produce different faces. @@ -2381,7 +2432,7 @@ pango_font_family_is_monospace (PangoFontFamily *family) * Return value: %TRUE if the family is variable * * Since: 1.44 - **/ + */ gboolean pango_font_family_is_variable (PangoFontFamily *family) { @@ -2411,16 +2462,16 @@ pango_font_face_init (PangoFontFace *face G_GNUC_UNUSED) /** * pango_font_face_describe: - * @face: a #PangoFontFace + * @face: a `PangoFontFace` * * Returns the family, style, variant, weight and stretch of - * a #PangoFontFace. The size field of the resulting font description + * a `PangoFontFace`. The size field of the resulting font description * will be unset. * - * Return value: a newly-created #PangoFontDescription structure - * holding the description of the face. Use pango_font_description_free() - * to free the result. - **/ + * Return value: a newly-created `PangoFontDescription` structure + * holding the description of the face. Use [method@Pango.FontDescription.free] + * to free the result. + */ PangoFontDescription * pango_font_face_describe (PangoFontFace *face) { @@ -2431,16 +2482,16 @@ pango_font_face_describe (PangoFontFace *face) /** * pango_font_face_is_synthesized: - * @face: a #PangoFontFace + * @face: a `PangoFontFace` * - * Returns whether a #PangoFontFace is synthesized by the underlying + * Returns whether a `PangoFontFace` is synthesized by the underlying * font rendering engine from another face, perhaps by shearing, emboldening, * or lightening it. * * Return value: whether @face is synthesized. * * Since: 1.18 - **/ + */ gboolean pango_font_face_is_synthesized (PangoFontFace *face) { @@ -2454,15 +2505,15 @@ pango_font_face_is_synthesized (PangoFontFace *face) /** * pango_font_face_get_face_name: - * @face: a #PangoFontFace. + * @face: a `PangoFontFace`. * * Gets a name representing the style of this face among the - * different faces in the #PangoFontFamily for the face. The + * different faces in the `PangoFontFamily` for the face. The * name is suitable for displaying to users. * * Return value: the face name for the face. This string is * owned by the face object and must not be modified or freed. - **/ + */ const char * pango_font_face_get_face_name (PangoFontFace *face) { @@ -2473,23 +2524,25 @@ pango_font_face_get_face_name (PangoFontFace *face) /** * pango_font_face_list_sizes: - * @face: a #PangoFontFace. + * @face: a `PangoFontFace`. * @sizes: (out) (array length=n_sizes) (nullable) (optional): * location to store a pointer to an array of int. This array * should be freed with g_free(). * @n_sizes: location to store the number of elements in @sizes * - * List the available sizes for a font. This is only applicable to bitmap - * fonts. For scalable fonts, stores %NULL at the location pointed to by - * @sizes and 0 at the location pointed to by @n_sizes. The sizes returned - * are in Pango units and are sorted in ascending order. + * List the available sizes for a font. + * + * This is only applicable to bitmap fonts. For scalable fonts, stores + * %NULL at the location pointed to by @sizes and 0 at the location pointed + * to by @n_sizes. The sizes returned are in Pango units and are sorted + * in ascending order. * * Since: 1.4 - **/ + */ void pango_font_face_list_sizes (PangoFontFace *face, - int **sizes, - int *n_sizes) + int **sizes, + int *n_sizes) { g_return_if_fail (PANGO_IS_FONT_FACE (face)); g_return_if_fail (sizes == NULL || n_sizes != NULL); @@ -2502,19 +2555,18 @@ pango_font_face_list_sizes (PangoFontFace *face, else { if (sizes != NULL) - *sizes = NULL; + *sizes = NULL; *n_sizes = 0; } } /** * pango_font_face_get_family: - * @face: a #PangoFontFace + * @face: a `PangoFontFace` * - * Gets the #PangoFontFamily that @face - * belongs to. + * Gets the `PangoFontFamily` that @face belongs to. * - * Returns: (transfer none): the #PangoFontFamily + * Returns: (transfer none): the `PangoFontFamily` * * Since: 1.46 */ @@ -2528,7 +2580,7 @@ pango_font_face_get_family (PangoFontFace *face) /** * pango_font_has_char: - * @font: a #PangoFont + * @font: a `PangoFont` * @wc: a Unicode character * * Returns whether the font provides a glyph for this character. @@ -2549,12 +2601,13 @@ pango_font_has_char (PangoFont *font, /** * pango_font_get_features: - * @font: a #PangoFont + * @font: a `PangoFont` * @features: (out caller-allocates) (array length=len): Array to features in * @len: the length of @features * @num_features: (inout): the number of used items in @features * * Obtain the OpenType features that are provided by the font. + * * These are passed to the rendering system, together with features * that have been explicitly set via attributes. * |