[pango/gi-docs: 33/47] docs: Start porting PangoFont to the new doc format
- From: Matthias Clasen <matthiasc src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [pango/gi-docs: 33/47] docs: Start porting PangoFont to the new doc format
- Date: Wed, 17 Feb 2021 05:28:16 +0000 (UTC)
commit 68cf60dcc67a0cbfae5d89a81bd5381ef201f937
Author: Matthias Clasen <mclasen redhat com>
Date: Sun Feb 14 23:20:05 2021 -0500
docs: Start porting PangoFont to the new doc format
Replace gtk-doc'isms and use gi-docgen links instead.
pango/fonts.c | 1075 ++++++++++++++++++++++++++--------------------------
pango/pango-font.h | 166 +++-----
2 files changed, 592 insertions(+), 649 deletions(-)
---
diff --git a/pango/fonts.c b/pango/fonts.c
index a778facd..10c6ca12 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
@@ -24,12 +24,11 @@
* @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.
+ * 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"
@@ -69,21 +68,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 +90,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 +105,18 @@ 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
* 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 +127,18 @@ 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
+ * 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 +164,15 @@ 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. See
- * pango_font_description_set_family().
+ * Gets the family name field of a font description.
+ * 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 +183,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 +209,15 @@ 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. See
- * pango_font_description_set_style().
+ * Gets the style field of a `PangoFontDescription`.
+ * 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 +228,16 @@ 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 +247,15 @@ 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. See
- * pango_font_description_set_variant().
+ * Gets the variant field of a `PangoFontDescription`.
+ * 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 +266,17 @@ 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
* 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 +286,15 @@ 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. See
- * pango_font_description_set_weight().
+ * Gets the weight field of a font description.
+ * 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 +305,16 @@ 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,15 @@ 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().
+ * See [method@Pango.FontDescription.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.
- **/
+ * 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 +343,23 @@ 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 +371,19 @@ 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 +394,20 @@ 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. This is mutually
- * exclusive with pango_font_description_set_size() which sets the font size
- * in points.
+ * Sets the size field of a font description, in device units.
+ * 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 +419,19 @@ 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).
- * See pango_font_description_set_size() and pango_font_description_set_absolute_size().
+ * Determines whether the size of the font is in points (not absolute)
+ * or device units (absolute). 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 +442,22 @@ 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
+ * 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 +473,17 @@ 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.
+ * See [method@Pango.FontDescription.set_gravity].
*
- * 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.
+ * 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 +494,18 @@ 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
+ * 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 +534,17 @@ 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.
*
- * 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 +553,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 +567,17 @@ 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. See
- * pango_font_description_set_variations().
+ * Gets the variations field of a font description.
+ * 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 +588,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 +605,15 @@ 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 +629,24 @@ 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 +676,21 @@ 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.
- **/
+ * 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 +727,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 +746,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 +780,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 +788,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 +822,17 @@ 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
+ *
+ * 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 +856,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.
*
- * 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.)
+ * 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 +900,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 +908,14 @@ case_insensitive_hash (const char *key)
/**
* pango_font_description_hash:
- * @desc: a #PangoFontDescription
+ * @desc: a `PangoFontDescription`
*
- * Computes a hash of a #PangoFontDescription structure suitable
+ * 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.
*
* Return value: the hash value.
- **/
+ */
guint
pango_font_description_hash (const PangoFontDescription *desc)
{
@@ -932,12 +940,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 +962,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 +1048,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 +1062,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 +1076,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 +1096,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 +1109,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 +1141,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 +1179,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 +1192,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;
}
@@ -1219,7 +1227,7 @@ parse_variations (const char *word,
* Creates a new font description from a string representation in 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 +1265,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 +1281,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 +1293,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 +1304,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 +1317,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 +1353,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 +1375,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 +1390,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 [method@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 +1423,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 +1453,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 +1473,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. 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.
+ * Creates a filename representation of a font description.
+ *
+ * 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 +1500,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 +1530,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 +1543,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,8 +1569,7 @@ 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",
@@ -1568,11 +1577,11 @@ parse_field (const char *what,
* 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,8 +1589,7 @@ 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"
@@ -1589,11 +1597,11 @@ pango_parse_style (const char *str,
* 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,8 +1609,7 @@ 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",
@@ -1610,11 +1617,11 @@ pango_parse_variant (const char *str,
* 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,8 +1629,7 @@ 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
@@ -1633,18 +1639,16 @@ pango_parse_weight (const char *str,
* 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 +1685,16 @@ 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.
+ * Use [method Pango Font.describe_with_absolute_size] if you want
+ * the font size in device units.
*
- * Return value: a newly-allocated #PangoFontDescription object.
- **/
+ * 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 +1703,18 @@ 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). Use [method Pango Font.describe] if you want
+ * the font size in points.
*
- * Return value: a newly-allocated #PangoFontDescription object.
+ * 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 +1729,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 +1748,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,18 +1757,18 @@ 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.
@@ -1781,29 +1785,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 +1816,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 +1859,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 *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.
+ * 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 +1891,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 +1909,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 +1945,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.
+ *
+ * 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
+ * Return value: a newly-created `PangoFontMetrics` structure
* with a reference count of 1.
- **/
+ */
PangoFontMetrics *
pango_font_metrics_new (void)
{
@@ -1957,12 +1964,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 +1983,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 +2002,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. 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.)
+ * 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.)
*
* Return value: the ascent, in Pango units.
- **/
+ */
int
pango_font_metrics_get_ascent (PangoFontMetrics *metrics)
{
@@ -2016,16 +2023,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. 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.)
+ * 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.)
*
* Return value: the descent, in Pango units.
- **/
+ */
int
pango_font_metrics_get_descent (PangoFontMetrics *metrics)
{
@@ -2036,10 +2044,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.
*
- * Gets the line height from a font metrics structure. The
- * line height is the distance between successive baselines
+ * The line height is the distance between successive baselines
* in wrapped text.
*
* If the line height is not available, 0 is returned.
@@ -2058,15 +2067,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 +2087,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 +2098,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 +2109,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 *above* 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 +2131,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 +2149,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 *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 +2170,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 +2255,15 @@ 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
+ * 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,9 +2274,9 @@ 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.
@@ -2272,11 +2284,11 @@ pango_font_family_get_name (PangoFontFamily *family)
* 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 +2330,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,7 +2353,7 @@ 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
@@ -2352,14 +2364,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 +2385,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 +2393,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 +2423,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 +2443,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 +2466,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 +2485,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 +2516,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 +2541,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,7 +2562,7 @@ 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
diff --git a/pango/pango-font.h b/pango/pango-font.h
index cc12a295..1fbade27 100644
--- a/pango/pango-font.h
+++ b/pango/pango-font.h
@@ -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
@@ -33,7 +33,7 @@ G_BEGIN_DECLS
/**
* PangoFontDescription:
*
- * The #PangoFontDescription structure represents the description
+ * The `PangoFontDescription` structure represents the description
* of an ideal font. These structures are used both to list
* what fonts are available on the system and also for specifying
* the characteristics of a font to load.
@@ -42,7 +42,7 @@ typedef struct _PangoFontDescription PangoFontDescription;
/**
* PangoFontMetrics:
*
- * A #PangoFontMetrics structure holds the overall metric information
+ * A `PangoFontMetrics` structure holds the overall metric information
* for a font (possibly restricted to a script). The fields of this
* structure are private to implementations of a font backend. See
* the documentation of the corresponding getters for documentation
@@ -148,8 +148,8 @@ typedef enum {
* @PANGO_FONT_MASK_GRAVITY: the font gravity is specified (Since: 1.16.)
* @PANGO_FONT_MASK_VARIATIONS: OpenType font variations are specified (Since: 1.42)
*
- * The bits in a #PangoFontMask correspond to fields in a
- * #PangoFontDescription that have been set.
+ * The bits in a `PangoFontMask` correspond to fields in a
+ * [struct@Pango.FontDescription] that have been set.
*/
typedef enum {
PANGO_FONT_MASK_FAMILY = 1 << 0,
@@ -210,11 +210,6 @@ typedef enum {
* PangoFontDescription
*/
-/**
- * PANGO_TYPE_FONT_DESCRIPTION:
- *
- * The #GObject type for #PangoFontDescription.
- */
#define PANGO_TYPE_FONT_DESCRIPTION (pango_font_description_get_type ())
PANGO_AVAILABLE_IN_ALL
@@ -229,54 +224,54 @@ PANGO_AVAILABLE_IN_ALL
guint pango_font_description_hash (const PangoFontDescription *desc) G_GNUC_PURE;
PANGO_AVAILABLE_IN_ALL
gboolean pango_font_description_equal (const PangoFontDescription *desc1,
- const PangoFontDescription *desc2) G_GNUC_PURE;
+ const PangoFontDescription *desc2) G_GNUC_PURE;
PANGO_AVAILABLE_IN_ALL
void pango_font_description_free (PangoFontDescription *desc);
PANGO_AVAILABLE_IN_ALL
void pango_font_descriptions_free (PangoFontDescription **descs,
- int n_descs);
+ int n_descs);
PANGO_AVAILABLE_IN_ALL
void pango_font_description_set_family (PangoFontDescription *desc,
- const char *family);
+ const char *family);
PANGO_AVAILABLE_IN_ALL
void pango_font_description_set_family_static (PangoFontDescription *desc,
- const char *family);
+ const char *family);
PANGO_AVAILABLE_IN_ALL
const char *pango_font_description_get_family (const PangoFontDescription *desc) G_GNUC_PURE;
PANGO_AVAILABLE_IN_ALL
void pango_font_description_set_style (PangoFontDescription *desc,
- PangoStyle style);
+ PangoStyle style);
PANGO_AVAILABLE_IN_ALL
PangoStyle pango_font_description_get_style (const PangoFontDescription *desc) G_GNUC_PURE;
PANGO_AVAILABLE_IN_ALL
void pango_font_description_set_variant (PangoFontDescription *desc,
- PangoVariant variant);
+ PangoVariant variant);
PANGO_AVAILABLE_IN_ALL
PangoVariant pango_font_description_get_variant (const PangoFontDescription *desc) G_GNUC_PURE;
PANGO_AVAILABLE_IN_ALL
void pango_font_description_set_weight (PangoFontDescription *desc,
- PangoWeight weight);
+ PangoWeight weight);
PANGO_AVAILABLE_IN_ALL
PangoWeight pango_font_description_get_weight (const PangoFontDescription *desc) G_GNUC_PURE;
PANGO_AVAILABLE_IN_ALL
void pango_font_description_set_stretch (PangoFontDescription *desc,
- PangoStretch stretch);
+ PangoStretch stretch);
PANGO_AVAILABLE_IN_ALL
PangoStretch pango_font_description_get_stretch (const PangoFontDescription *desc) G_GNUC_PURE;
PANGO_AVAILABLE_IN_ALL
void pango_font_description_set_size (PangoFontDescription *desc,
- gint size);
+ gint size);
PANGO_AVAILABLE_IN_ALL
gint pango_font_description_get_size (const PangoFontDescription *desc) G_GNUC_PURE;
PANGO_AVAILABLE_IN_1_8
void pango_font_description_set_absolute_size (PangoFontDescription *desc,
- double size);
+ double size);
PANGO_AVAILABLE_IN_1_8
gboolean pango_font_description_get_size_is_absolute (const PangoFontDescription *desc)
G_GNUC_PURE;
PANGO_AVAILABLE_IN_1_16
void pango_font_description_set_gravity (PangoFontDescription *desc,
- PangoGravity gravity);
+ PangoGravity gravity);
PANGO_AVAILABLE_IN_1_16
PangoGravity pango_font_description_get_gravity (const PangoFontDescription *desc) G_GNUC_PURE;
@@ -293,21 +288,21 @@ PANGO_AVAILABLE_IN_ALL
PangoFontMask pango_font_description_get_set_fields (const PangoFontDescription *desc) G_GNUC_PURE;
PANGO_AVAILABLE_IN_ALL
void pango_font_description_unset_fields (PangoFontDescription *desc,
- PangoFontMask to_unset);
+ PangoFontMask to_unset);
PANGO_AVAILABLE_IN_ALL
void pango_font_description_merge (PangoFontDescription *desc,
- const PangoFontDescription *desc_to_merge,
- gboolean replace_existing);
+ const PangoFontDescription *desc_to_merge,
+ gboolean replace_existing);
PANGO_AVAILABLE_IN_ALL
void pango_font_description_merge_static (PangoFontDescription *desc,
- const PangoFontDescription *desc_to_merge,
- gboolean replace_existing);
+ const PangoFontDescription *desc_to_merge,
+ gboolean replace_existing);
PANGO_AVAILABLE_IN_ALL
gboolean pango_font_description_better_match (const PangoFontDescription *desc,
- const PangoFontDescription *old_match,
- const PangoFontDescription *new_match) G_GNUC_PURE;
+ const PangoFontDescription *old_match,
+ const PangoFontDescription *new_match) G_GNUC_PURE;
PANGO_AVAILABLE_IN_ALL
PangoFontDescription *pango_font_description_from_string (const char *str);
@@ -320,11 +315,6 @@ char * pango_font_description_to_filename (const PangoFontDescrip
* PangoFontMetrics
*/
-/**
- * PANGO_TYPE_FONT_METRICS:
- *
- * The #GObject type for #PangoFontMetrics.
- */
#define PANGO_TYPE_FONT_METRICS (pango_font_metrics_get_type ())
struct _PangoFontMetrics
@@ -373,23 +363,6 @@ int pango_font_metrics_get_strikethrough_thickness (PangoFontMetri
* PangoFontFamily
*/
-/**
- * PANGO_TYPE_FONT_FAMILY:
- *
- * The #GObject type for #PangoFontFamily.
- */
-/**
- * PANGO_FONT_FAMILY:
- * @object: a #GObject.
- *
- * Casts a #GObject to a #PangoFontFamily.
- */
-/**
- * PANGO_IS_FONT_FAMILY:
- * @object: a #GObject.
- *
- * Returns: %TRUE if @object is a #PangoFontFamily.
- */
#define PANGO_TYPE_FONT_FAMILY (pango_font_family_get_type ())
#define PANGO_FONT_FAMILY(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONT_FAMILY,
PangoFontFamily))
#define PANGO_IS_FONT_FAMILY(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONT_FAMILY))
@@ -406,7 +379,7 @@ typedef struct _PangoFontFamilyClass PangoFontFamilyClass;
/**
* PangoFontFamily:
*
- * The #PangoFontFamily structure is used to represent a family of related
+ * The `PangoFontFamily` structure is used to represent a family of related
* font faces. The faces in a family share a common design, but differ in
* slant, weight, width and other aspects.
*/
@@ -445,8 +418,8 @@ GType pango_font_family_get_type (void) G_GNUC_CONST;
PANGO_AVAILABLE_IN_ALL
void pango_font_family_list_faces (PangoFontFamily *family,
- PangoFontFace ***faces,
- int *n_faces);
+ PangoFontFace ***faces,
+ int *n_faces);
PANGO_AVAILABLE_IN_ALL
const char *pango_font_family_get_name (PangoFontFamily *family) G_GNUC_PURE;
PANGO_AVAILABLE_IN_1_4
@@ -463,23 +436,6 @@ PangoFontFace *pango_font_family_get_face (PangoFontFamily *family,
* PangoFontFace
*/
-/**
- * PANGO_TYPE_FONT_FACE:
- *
- * The #GObject type for #PangoFontFace.
- */
-/**
- * PANGO_FONT_FACE:
- * @object: a #GObject.
- *
- * Casts a #GObject to a #PangoFontFace.
- */
-/**
- * PANGO_IS_FONT_FACE:
- * @object: a #GObject.
- *
- * Returns: %TRUE if @object is a #PangoFontFace.
- */
#define PANGO_TYPE_FONT_FACE (pango_font_face_get_type ())
#define PANGO_FONT_FACE(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONT_FACE,
PangoFontFace))
#define PANGO_IS_FONT_FACE(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONT_FACE))
@@ -494,7 +450,7 @@ typedef struct _PangoFontFaceClass PangoFontFaceClass;
/**
* PangoFontFace:
*
- * The #PangoFontFace structure is used to represent a group of fonts with
+ * The `PangoFontFace` structure is used to represent a group of fonts with
* the same family, slant, weight, width, but varying sizes.
*/
struct _PangoFontFace
@@ -534,8 +490,8 @@ PANGO_AVAILABLE_IN_ALL
const char *pango_font_face_get_face_name (PangoFontFace *face) G_GNUC_PURE;
PANGO_AVAILABLE_IN_1_4
void pango_font_face_list_sizes (PangoFontFace *face,
- int **sizes,
- int *n_sizes);
+ int **sizes,
+ int *n_sizes);
PANGO_AVAILABLE_IN_1_18
gboolean pango_font_face_is_synthesized (PangoFontFace *face) G_GNUC_PURE;
@@ -547,23 +503,6 @@ PangoFontFamily * pango_font_face_get_family (PangoFontFace *face);
* PangoFont
*/
-/**
- * PANGO_TYPE_FONT:
- *
- * The #GObject type for #PangoFont.
- */
-/**
- * PANGO_FONT:
- * @object: a #GObject.
- *
- * Casts a #GObject to a #PangoFont.
- */
-/**
- * PANGO_IS_FONT:
- * @object: a #GObject.
- *
- * Returns: %TRUE if @object is a #PangoFont.
- */
#define PANGO_TYPE_FONT (pango_font_get_type ())
#define PANGO_FONT(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONT, PangoFont))
#define PANGO_IS_FONT(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONT))
@@ -577,18 +516,8 @@ PangoFontFamily * pango_font_face_get_family (PangoFontFace *face);
/**
* PangoFont:
*
- * The #PangoFont structure is used to represent
- * a font in a rendering-system-independent matter.
- * To create an implementation of a #PangoFont,
- * the rendering-system specific code should allocate
- * a larger structure that contains a nested
- * #PangoFont, fill in the `klass` member of
- * the nested #PangoFont with a pointer to
- * a appropriate #PangoFontClass, then call
- * pango_font_init() on the structure.
- *
- * The #PangoFont structure contains one member
- * which the implementation fills in.
+ * The `PangoFont` structure is used to represent a font in a
+ * rendering-system-independent matter.
*/
struct _PangoFont
{
@@ -631,19 +560,19 @@ PANGO_AVAILABLE_IN_1_14
PangoFontDescription *pango_font_describe_with_absolute_size (PangoFont *font);
PANGO_AVAILABLE_IN_ALL
PangoCoverage * pango_font_get_coverage (PangoFont *font,
- PangoLanguage *language);
+ PangoLanguage *language);
PANGO_DEPRECATED_IN_1_44
PangoEngineShape * pango_font_find_shaper (PangoFont *font,
- PangoLanguage *language,
- guint32 ch);
+ PangoLanguage *language,
+ guint32 ch);
PANGO_AVAILABLE_IN_ALL
PangoFontMetrics * pango_font_get_metrics (PangoFont *font,
- PangoLanguage *language);
+ PangoLanguage *language);
PANGO_AVAILABLE_IN_ALL
void pango_font_get_glyph_extents (PangoFont *font,
- PangoGlyph glyph,
- PangoRectangle *ink_rect,
- PangoRectangle *logical_rect);
+ PangoGlyph glyph,
+ PangoRectangle *ink_rect,
+ PangoRectangle *logical_rect);
PANGO_AVAILABLE_IN_1_10
PangoFontMap *pango_font_get_font_map (PangoFont *font);
@@ -664,16 +593,17 @@ hb_font_t * pango_font_get_hb_font (PangoFont *font);
/**
* PANGO_GLYPH_EMPTY:
*
- * The %PANGO_GLYPH_EMPTY macro represents a #PangoGlyph value that has a
- * special meaning, which is a zero-width empty glyph. This is useful for
+ * The %PANGO_GLYPH_EMPTY macro represents a `PangoGlyph` value that has a
+ * special meaning, which is a zero-width empty glyph. This is useful for
* example in shaper modules, to use as the glyph for various zero-width
- * Unicode characters (those passing pango_is_zero_width()).
+ * Unicode characters (those passing [func@is_zero_width]).
*/
+
/**
* PANGO_GLYPH_INVALID_INPUT:
*
- * The %PANGO_GLYPH_INVALID_INPUT macro represents a #PangoGlyph value that has a
- * special meaning of invalid input. #PangoLayout produces one such glyph
+ * The %PANGO_GLYPH_INVALID_INPUT macro represents a `PangoGlyph` value that
+ * has a special meaning of invalid input. `PangoLayout` produces one such glyph
* per invalid input UTF-8 byte and such a glyph is rendered as a crossed
* box.
*
@@ -686,18 +616,18 @@ hb_font_t * pango_font_get_hb_font (PangoFont *font);
* PANGO_GLYPH_UNKNOWN_FLAG:
*
* The %PANGO_GLYPH_UNKNOWN_FLAG macro is a flag value that can be added to
- * a #gunichar value of a valid Unicode character, to produce a #PangoGlyph
- * value, representing an unknown-character glyph for the respective #gunichar.
+ * a `gunichar` value of a valid Unicode character, to produce a `PangoGlyph`
+ * value, representing an unknown-character glyph for the respective `gunichar`.
*/
/**
* PANGO_GET_UNKNOWN_GLYPH:
* @wc: a Unicode character
*
- * The way this unknown glyphs are rendered is backend specific. For example,
+ * The way this unknown glyphs are rendered is backend specific. For example,
* a box with the hexadecimal Unicode code-point of the character written in it
* is what is done in the most common backends.
*
- * Returns: a #PangoGlyph value that means no glyph was found for @wc.
+ * Returns: a `PangoGlyph` value that means no glyph was found for @wc.
*/
#define PANGO_GLYPH_EMPTY ((PangoGlyph)0x0FFFFFFF)
#define PANGO_GLYPH_INVALID_INPUT ((PangoGlyph)0xFFFFFFFF)
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
