diff options
Diffstat (limited to 'pango')
69 files changed, 5295 insertions, 5739 deletions
diff --git a/pango/break.c b/pango/break.c index 58bf2f90..35b947c0 100644 --- a/pango/break.c +++ b/pango/break.c @@ -147,8 +147,9 @@ typedef enum * @attrs: logical attributes to fill in * @attrs_len: size of the array passed as @attrs * - * This is the default break algorithm. It applies Unicode - * rules without language-specific tailoring, therefore + * This is the default break algorithm. + * + * It applies Unicode rules without language-specific tailoring, therefore * the @analyis argument is unused and can be %NULL. * * See pango_tailor_break() for language-specific breaks. @@ -1612,8 +1613,9 @@ tailor_break (const char *text, * information in * @attrs_len: size of the array passed as @attrs * - * Determines possible line, word, and character breaks - * for a string of Unicode text with a single analysis. + * Determines possible line, word, and character breaks for a string of + * Unicode text with a single analysis. + * * For most purposes you may want to use pango_get_log_attrs(). * * Deprecated: 1.44: Use pango_default_break() and pango_tailor_break() @@ -1641,17 +1643,18 @@ pango_break (const gchar *text, * @next_paragraph_start: (out): return location for start of next * paragraph * - * Locates a paragraph boundary in @text. A boundary is caused by - * delimiter characters, such as a newline, carriage return, carriage - * return-newline pair, or Unicode paragraph separator character. The - * index of the run of delimiters is returned in - * @paragraph_delimiter_index. The index of the start of the paragraph - * (index after all delimiters) is stored in @next_paragraph_start. + * Locates a paragraph boundary in @text. + * + * A boundary is caused by delimiter characters, such as a newline, carriage + * return, carriage return-newline pair, or Unicode paragraph separator character. + * The index of the run of delimiters is returned in @paragraph_delimiter_index. + * The index of the start of the paragrap (index after all delimiters) is stored + * in @next_paragraph_start. * * If no delimiters are found, both @paragraph_delimiter_index and * @next_paragraph_start are filled with the length of @text (an index one * off the end). - **/ + */ void pango_find_paragraph_boundary (const gchar *text, gint length, @@ -1736,16 +1739,16 @@ pango_find_paragraph_boundary (const gchar *text, * pango_tailor_break: * @text: text to process. Must be valid UTF-8 * @length: length in bytes of @text - * @analysis: #PangoAnalysis structure from pango_itemize() for @text + * @analysis: `PangoAnalysis` structure from [func@itemize] for @text * @offset: Byte offset of @text from the beginning of the * paragraph, or -1 to ignore attributes from @analysis - * @log_attrs: (array length=log_attrs_len): array with one #PangoLogAttr + * @log_attrs: (array length=log_attrs_len): array with one `PangoLogAttr` * per character in @text, plus one extra, to be filled in * @log_attrs_len: length of @log_attrs array * - * Apply language-specific tailoring to the breaks in - * @log_attrs, which are assumed to have been produced - * by pango_default_break(). + * Apply language-specific tailoring to the breaks in @log_attrs. + * + * The line breaks are assumed to have been produced by [func@default_break]. * * If @offset is not -1, it is used to apply attributes * from @analysis that are relevant to line breaking. @@ -1805,17 +1808,17 @@ tailor_segment (const char *range_start, * @length: length in bytes of @text * @level: embedding level, or -1 if unknown * @language: language tag - * @log_attrs: (array length=attrs_len): array with one #PangoLogAttr + * @log_attrs: (array length=attrs_len): array with one `PangoLogAttr` * per character in @text, plus one extra, to be filled in * @attrs_len: length of @log_attrs array * - * Computes a #PangoLogAttr for each character in @text. The @log_attrs - * array must have one #PangoLogAttr for each position in @text; if - * @text contains N characters, it has N+1 positions, including the - * last position at the end of the text. @text should be an entire - * paragraph; logical attributes can't be computed without context - * (for example you need to see spaces on either side of a word to know - * the word is a word). + * Computes a `PangoLogAttr` for each character in @text. + * + * The @log_attrs array must have one `PangoLogAttr` for each position in @text; + * if @text contains N characters, it has N+1 positions, including the last + * position at the end of the text. @text should be an entire paragraph; logical + * attributes can't be computed without context (for example you need to see + * spaces on either side of a word to know the word is a word). */ void pango_get_log_attrs (const char *text, 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. * diff --git a/pango/glyphstring.c b/pango/glyphstring.c index 6c674e03..649e7758 100644 --- a/pango/glyphstring.c +++ b/pango/glyphstring.c @@ -28,10 +28,10 @@ /** * pango_glyph_string_new: * - * Create a new #PangoGlyphString. + * Create a new `PangoGlyphString`. * - * Return value: the newly allocated #PangoGlyphString, which - * should be freed with pango_glyph_string_free(). + * Return value: the newly allocated `PangoGlyphString`, which + * should be freed with [method@Pango.GlyphString.free]. */ PangoGlyphString * pango_glyph_string_new (void) @@ -48,7 +48,7 @@ pango_glyph_string_new (void) /** * pango_glyph_string_set_size: - * @string: a #PangoGlyphString. + * @string: a `PangoGlyphString`. * @new_len: the new length of the string. * * Resize a glyph string to the given length. @@ -97,12 +97,12 @@ G_DEFINE_BOXED_TYPE (PangoGlyphString, pango_glyph_string, /** * pango_glyph_string_copy: - * @string: (nullable): a #PangoGlyphString, may be %NULL + * @string: (nullable): a `PangoGlyphString`, may be %NULL * * Copy a glyph string and associated storage. * - * Return value: (nullable): the newly allocated #PangoGlyphString, - * which should be freed with pango_glyph_string_free(), + * Return value: (nullable): the newly allocated `PangoGlyphString`, + * which should be freed with [method@Pango.GlyphString.free], * or %NULL if @string was %NULL. */ PangoGlyphString * @@ -127,7 +127,7 @@ pango_glyph_string_copy (PangoGlyphString *string) /** * pango_glyph_string_free: - * @string: (nullable): a #PangoGlyphString, may be %NULL + * @string: (nullable): a `PangoGlyphString`, may be %NULL * * Free a glyph string and associated storage. */ @@ -144,11 +144,11 @@ pango_glyph_string_free (PangoGlyphString *string) /** * pango_glyph_string_extents_range: - * @glyphs: a #PangoGlyphString + * @glyphs: a `PangoGlyphString` * @start: start index * @end: end index (the range is the set of bytes with indices such that start <= index < end) - * @font: a #PangoFont + * @font: a `PangoFont` * @ink_rect: (out caller-allocates) (optional): rectangle used to * store the extents of the glyph string range as drawn or * %NULL to indicate that the result is not needed. @@ -156,11 +156,12 @@ pango_glyph_string_free (PangoGlyphString *string) * store the logical extents of the glyph string range or * %NULL to indicate that the result is not needed. * - * Computes the extents of a sub-portion of a glyph string. The extents are - * relative to the start of the glyph string range (the origin of their - * coordinate system is at the start of the range, not at the start of the entire - * glyph string). - **/ + * Computes the extents of a sub-portion of a glyph string. + * + * The extents are relative to the start of the glyph string range + * (the origin of their coordinate system is at the start of the range, + * not at the start of the entire glyph string). + */ void pango_glyph_string_extents_range (PangoGlyphString *glyphs, int start, @@ -261,16 +262,17 @@ pango_glyph_string_extents_range (PangoGlyphString *glyphs, /** * pango_glyph_string_extents: - * @glyphs: a #PangoGlyphString - * @font: a #PangoFont + * @glyphs: a `PangoGlyphString` + * @font: a `PangoFont` * @ink_rect: (out) (allow-none): rectangle used to store the extents of the glyph string * 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 string or %NULL to indicate that the result is not needed. * - * Compute the logical and ink extents of a glyph string. See the documentation - * for pango_font_get_glyph_extents() for details about the interpretation - * of the rectangles. + * Compute the logical and ink extents of a glyph string. + * + * See the documentation for [method@Pango.Font.get_glyph_extents] for details + * about the interpretation of the rectangles. * * Examples of logical (red) and ink (green) rects: * @@ -288,12 +290,14 @@ pango_glyph_string_extents (PangoGlyphString *glyphs, /** * pango_glyph_string_get_width: - * @glyphs: a #PangoGlyphString + * @glyphs: a `PangoGlyphString` + * + * Computes the logical width of the glyph string. * - * Computes the logical width of the glyph string as can also be computed - * using pango_glyph_string_extents(). However, since this only computes the - * width, it's much faster. This is in fact only a convenience function that - * computes the sum of geometry.width for each glyph in the @glyphs. + * This can also be computed using [method@Pango.GlyphString.extents]. + * However, since this only computes the width, it's much faster. This + * is in fact only a convenience function that computes the sum of + * @geometry.width for each glyph in the @glyphs. * * Return value: the logical width of the glyph string. * @@ -313,7 +317,7 @@ pango_glyph_string_get_width (PangoGlyphString *glyphs) /** * pango_glyph_string_get_logical_widths: - * @glyphs: a #PangoGlyphString + * @glyphs: a `PangoGlyphString` * @text: the text corresponding to the glyphs * @length: the length of @text, in bytes * @embedding_level: the embedding level of the string @@ -322,13 +326,14 @@ pango_glyph_string_get_width (PangoGlyphString *glyphs) * length) unless text has NUL bytes) to be filled in * with the resulting character widths. * - * Given a #PangoGlyphString resulting from pango_shape() and the corresponding - * text, determine the screen width corresponding to each character. When - * multiple characters compose a single cluster, the width of the entire - * cluster is divided equally among the characters. + * Given a `PangoGlyphString` and corresponding text, determine the width + * corresponding to each character. * - * See also pango_glyph_item_get_logical_widths(). - **/ + * When multiple characters compose a single cluster, the width of the + * entire cluster is divided equally among the characters. + * + * See also [method@Pango.GlyphItem.get_logical_widths]. + */ void pango_glyph_string_get_logical_widths (PangoGlyphString *glyphs, const char *text, @@ -358,18 +363,20 @@ pango_glyph_string_get_logical_widths (PangoGlyphString *glyphs, /** * pango_glyph_string_index_to_x: - * @glyphs: the glyphs return from pango_shape() + * @glyphs: the glyphs return from [func@shape] * @text: the text for the run * @length: the number of bytes (not characters) in @text. - * @analysis: the analysis information return from pango_itemize() + * @analysis: the analysis information return from [func@itemize] * @index_: the byte index within @text * @trailing: whether we should compute the result for the beginning (%FALSE) * or end (%TRUE) of the character. * @x_pos: (out): location to store result * - * Converts from character position to x position. (X position - * is measured from the left edge of the run). Character positions - * are computed by dividing up each cluster into equal portions. + * Converts from character position to x position. + * + * The X position is measured from the left edge of the run. + * Character positions are computed by dividing up each cluster + * into equal portions. */ void @@ -486,21 +493,22 @@ pango_glyph_string_index_to_x (PangoGlyphString *glyphs, /** * pango_glyph_string_x_to_index: - * @glyphs: the glyphs returned from pango_shape() + * @glyphs: the glyphs returned from [func@shape] * @text: the text for the run * @length: the number of bytes (not characters) in text. - * @analysis: the analysis information return from pango_itemize() + * @analysis: the analysis information return from [func@itemize] * @x_pos: the x offset (in Pango units) * @index_: (out): location to store calculated byte index within @text * @trailing: (out): location to store a boolean indicating * whether the user clicked on the leading or trailing * edge of the character. * - * Convert from x offset to character position. Character positions - * are computed by dividing up each cluster into equal portions. - * In scripts where positioning within a cluster is not allowed - * (such as Thai), the returned value may not be a valid cursor - * position; the caller must combine the result with the logical + * Convert from x offset to character position. + * + * Character positions are computed by dividing up each cluster into + * equal portions. In scripts where positioning within a cluster is + * not allowed (such as Thai), the returned value may not be a valid + * cursor position; the caller must combine the result with the logical * attributes for the text to compute the valid cursor position. */ void diff --git a/pango/modules.c b/pango/modules.c index 54f9db8f..b7ba105b 100644 --- a/pango/modules.c +++ b/pango/modules.c @@ -19,19 +19,6 @@ * Boston, MA 02111-1307, USA. */ -/** - * SECTION:modules - * @short_description:Support for loadable modules - * @title:Modules - * - * Functions and macros in this section were used to support - * loading dynamic modules that add engines to Pango at run time. - * - * That is no longer the case, and these APIs should not be - * used anymore. - * - * Deprecated: 1.38 - */ #include "config.h" #include "pango-modules.h" diff --git a/pango/pango-attributes.c b/pango/pango-attributes.c index 3ef76a70..225dc654 100644 --- a/pango/pango-attributes.c +++ b/pango/pango-attributes.c @@ -10,7 +10,7 @@ * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Library General Public License for more details. * * You should have received a copy of the GNU Library General Public @@ -19,17 +19,6 @@ * Boston, MA 02111-1307, USA. */ -/** - * SECTION:text-attributes - * @short_description:Font and other attributes for annotating text - * @title:Attributes - * - * Attributed text is used in a number of places in Pango. It - * is used as the input to the itemization process and also when - * creating a #PangoLayout. The data types and functions in - * this section are used to represent and manipulate sets - * of attributes applied to a portion of text. - */ #include "config.h" #include <string.h> @@ -38,17 +27,17 @@ #include "pango-impl-utils.h" static PangoAttribute *pango_attr_color_new (const PangoAttrClass *klass, - guint16 red, - guint16 green, - guint16 blue); + guint16 red, + guint16 green, + guint16 blue); static PangoAttribute *pango_attr_string_new (const PangoAttrClass *klass, - const char *str); + const char *str); static PangoAttribute *pango_attr_int_new (const PangoAttrClass *klass, - int value); + int value); static PangoAttribute *pango_attr_float_new (const PangoAttrClass *klass, - double value); + double value); static PangoAttribute *pango_attr_size_new_internal (int size, - gboolean absolute); + gboolean absolute); G_LOCK_DEFINE_STATIC (attr_type); @@ -58,11 +47,12 @@ static GHashTable *name_map = NULL; /* MT-safe */ * pango_attr_type_register: * @name: an identifier for the type * - * Allocate a new attribute type ID. The attribute type name can be accessed - * later by using pango_attr_type_get_name(). + * Allocate a new attribute type ID. + * + * The attribute type name can be accessed later by using [type_func@Pango.AttrType.get_name]. * * Return value: the new type ID. - **/ + */ PangoAttrType pango_attr_type_register (const gchar *name) { @@ -76,7 +66,7 @@ pango_attr_type_register (const gchar *name) if (name) { if (G_UNLIKELY (!name_map)) - name_map = g_hash_table_new (NULL, NULL); + name_map = g_hash_table_new (NULL, NULL); g_hash_table_insert (name_map, GUINT_TO_POINTER (type), (gpointer) g_intern_string (name)); } @@ -90,17 +80,19 @@ pango_attr_type_register (const gchar *name) * pango_attr_type_get_name: * @type: an attribute type ID to fetch the name for * - * Fetches the attribute type name passed in when registering the type using - * pango_attr_type_register(). + * Fetches the attribute type name. + * + * The attribute type name is the string passed in when registering the type + * using [type_func@attr_type_register]. * * The returned value is an interned string (see g_intern_string() for what * that means) that should not be modified or freed. * * Return value: (nullable): the type ID name (which may be %NULL), or - * %NULL if @type is a built-in Pango attribute type or invalid. + * %NULL if @type is a built-in Pango attribute type or invalid. * * Since: 1.22 - **/ + */ const char * pango_attr_type_get_name (PangoAttrType type) { @@ -118,20 +110,19 @@ pango_attr_type_get_name (PangoAttrType type) /** * pango_attribute_init: - * @attr: a #PangoAttribute - * @klass: a #PangoAttrClass + * @attr: a `PangoAttribute` + * @klass: a `PangoAttrClass` * - * Initializes @attr's klass to @klass, - * it's start_index to %PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING - * and end_index to %PANGO_ATTR_INDEX_TO_TEXT_END - * such that the attribute applies + * Initializes @attr's klass to @klass, it's start_index to + * %PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING and end_index to + * %PANGO_ATTR_INDEX_TO_TEXT_END such that the attribute applies * to the entire text by default. * * Since: 1.20 - **/ + */ void pango_attribute_init (PangoAttribute *attr, - const PangoAttrClass *klass) + const PangoAttrClass *klass) { g_return_if_fail (attr != NULL); g_return_if_fail (klass != NULL); @@ -143,13 +134,13 @@ pango_attribute_init (PangoAttribute *attr, /** * pango_attribute_copy: - * @attr: a #PangoAttribute + * @attr: a `PangoAttribute` * * Make a copy of an attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attribute_copy (const PangoAttribute *attr) { @@ -166,10 +157,10 @@ pango_attribute_copy (const PangoAttribute *attr) /** * pango_attribute_destroy: - * @attr: a #PangoAttribute. + * @attr: a `PangoAttribute`. * - * Destroy a #PangoAttribute and free all associated memory. - **/ + * Destroy a `PangoAttribute` and free all associated memory. + */ void pango_attribute_destroy (PangoAttribute *attr) { @@ -184,18 +175,18 @@ G_DEFINE_BOXED_TYPE (PangoAttribute, pango_attribute, /** * pango_attribute_equal: - * @attr1: a #PangoAttribute - * @attr2: another #PangoAttribute + * @attr1: a `PangoAttribute` + * @attr2: another `PangoAttribute` * * Compare two attributes for equality. This compares only the * actual value of the two attributes and not the ranges that the * attributes apply to. * * Return value: %TRUE if the two attributes have the same value. - **/ + */ gboolean pango_attribute_equal (const PangoAttribute *attr1, - const PangoAttribute *attr2) + const PangoAttribute *attr2) { g_return_val_if_fail (attr1 != NULL, FALSE); g_return_val_if_fail (attr2 != NULL, FALSE); @@ -223,14 +214,14 @@ pango_attr_string_destroy (PangoAttribute *attr) static gboolean pango_attr_string_equal (const PangoAttribute *attr1, - const PangoAttribute *attr2) + const PangoAttribute *attr2) { return strcmp (((PangoAttrString *)attr1)->value, ((PangoAttrString *)attr2)->value) == 0; } static PangoAttribute * pango_attr_string_new (const PangoAttrClass *klass, - const char *str) + const char *str) { PangoAttrString *result = g_slice_new (PangoAttrString); pango_attribute_init (&result->attr, klass); @@ -245,9 +236,9 @@ pango_attr_string_new (const PangoAttrClass *klass, * * Create a new font family attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute` + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attr_family_new (const char *family) { @@ -279,7 +270,7 @@ pango_attr_language_destroy (PangoAttribute *attr) static gboolean pango_attr_language_equal (const PangoAttribute *attr1, - const PangoAttribute *attr2) + const PangoAttribute *attr2) { return ((PangoAttrLanguage *)attr1)->value == ((PangoAttrLanguage *)attr2)->value; } @@ -290,9 +281,9 @@ pango_attr_language_equal (const PangoAttribute *attr1, * * Create a new language tag attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attr_language_new (PangoLanguage *language) { @@ -318,9 +309,9 @@ pango_attr_color_copy (const PangoAttribute *attr) const PangoAttrColor *color_attr = (PangoAttrColor *)attr; return pango_attr_color_new (attr->klass, - color_attr->color.red, - color_attr->color.green, - color_attr->color.blue); + color_attr->color.red, + color_attr->color.green, + color_attr->color.blue); } static void @@ -333,21 +324,21 @@ pango_attr_color_destroy (PangoAttribute *attr) static gboolean pango_attr_color_equal (const PangoAttribute *attr1, - const PangoAttribute *attr2) + const PangoAttribute *attr2) { const PangoAttrColor *color_attr1 = (const PangoAttrColor *)attr1; const PangoAttrColor *color_attr2 = (const PangoAttrColor *)attr2; return (color_attr1->color.red == color_attr2->color.red && - color_attr1->color.blue == color_attr2->color.blue && - color_attr1->color.green == color_attr2->color.green); + color_attr1->color.blue == color_attr2->color.blue && + color_attr1->color.green == color_attr2->color.green); } static PangoAttribute * pango_attr_color_new (const PangoAttrClass *klass, - guint16 red, - guint16 green, - guint16 blue) + guint16 red, + guint16 green, + guint16 blue) { PangoAttrColor *result = g_slice_new (PangoAttrColor); pango_attribute_init (&result->attr, klass); @@ -366,13 +357,13 @@ pango_attr_color_new (const PangoAttrClass *klass, * * Create a new foreground color attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attr_foreground_new (guint16 red, - guint16 green, - guint16 blue) + guint16 green, + guint16 blue) { static const PangoAttrClass klass = { PANGO_ATTR_FOREGROUND, @@ -392,13 +383,13 @@ pango_attr_foreground_new (guint16 red, * * Create a new background color attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attr_background_new (guint16 red, - guint16 green, - guint16 blue) + guint16 green, + guint16 blue) { static const PangoAttrClass klass = { PANGO_ATTR_BACKGROUND, @@ -428,7 +419,7 @@ pango_attr_int_destroy (PangoAttribute *attr) static gboolean pango_attr_int_equal (const PangoAttribute *attr1, - const PangoAttribute *attr2) + const PangoAttribute *attr2) { const PangoAttrInt *int_attr1 = (const PangoAttrInt *)attr1; const PangoAttrInt *int_attr2 = (const PangoAttrInt *)attr2; @@ -438,7 +429,7 @@ pango_attr_int_equal (const PangoAttribute *attr1, static PangoAttribute * pango_attr_int_new (const PangoAttrClass *klass, - int value) + int value) { PangoAttrInt *result = g_slice_new (PangoAttrInt); pango_attribute_init (&result->attr, klass); @@ -465,7 +456,7 @@ pango_attr_float_destroy (PangoAttribute *attr) static gboolean pango_attr_float_equal (const PangoAttribute *attr1, - const PangoAttribute *attr2) + const PangoAttribute *attr2) { const PangoAttrFloat *float_attr1 = (const PangoAttrFloat *)attr1; const PangoAttrFloat *float_attr2 = (const PangoAttrFloat *)attr2; @@ -475,7 +466,7 @@ pango_attr_float_equal (const PangoAttribute *attr1, static PangoAttribute* pango_attr_float_new (const PangoAttrClass *klass, - double value) + double value) { PangoAttrFloat *result = g_slice_new (PangoAttrFloat); pango_attribute_init (&result->attr, klass); @@ -505,7 +496,7 @@ pango_attr_size_destroy (PangoAttribute *attr) static gboolean pango_attr_size_equal (const PangoAttribute *attr1, - const PangoAttribute *attr2) + const PangoAttribute *attr2) { const PangoAttrSize *size_attr1 = (const PangoAttrSize *)attr1; const PangoAttrSize *size_attr2 = (const PangoAttrSize *)attr2; @@ -515,7 +506,7 @@ pango_attr_size_equal (const PangoAttribute *attr1, static PangoAttribute * pango_attr_size_new_internal (int size, - gboolean absolute) + gboolean absolute) { PangoAttrSize *result; @@ -546,9 +537,9 @@ pango_attr_size_new_internal (int size, * * Create a new font-size attribute in fractional points. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attr_size_new (int size) { @@ -561,11 +552,11 @@ pango_attr_size_new (int size) * * Create a new font-size attribute in device units. * - * Return value: the newly allocated #PangoAttribute, which should be - * freed with pango_attribute_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.8 - **/ + */ PangoAttribute * pango_attr_size_new_absolute (int size) { @@ -578,9 +569,9 @@ pango_attr_size_new_absolute (int size) * * Create a new font slant style attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attr_style_new (PangoStyle style) { @@ -600,9 +591,9 @@ pango_attr_style_new (PangoStyle style) * * Create a new font weight attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attr_weight_new (PangoWeight weight) { @@ -620,11 +611,11 @@ pango_attr_weight_new (PangoWeight weight) * pango_attr_variant_new: * @variant: the variant * - * Create a new font variant attribute (normal or small caps) + * Create a new font variant attribute (normal or small caps). * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attr_variant_new (PangoVariant variant) { @@ -642,11 +633,11 @@ pango_attr_variant_new (PangoVariant variant) * pango_attr_stretch_new: * @stretch: the stretch * - * Create a new font stretch attribute + * Create a new font stretch attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attr_stretch_new (PangoStretch stretch) { @@ -679,27 +670,28 @@ pango_attr_font_desc_destroy (PangoAttribute *attr) static gboolean pango_attr_font_desc_equal (const PangoAttribute *attr1, - const PangoAttribute *attr2) + const PangoAttribute *attr2) { const PangoAttrFontDesc *desc_attr1 = (const PangoAttrFontDesc *)attr1; const PangoAttrFontDesc *desc_attr2 = (const PangoAttrFontDesc *)attr2; return pango_font_description_get_set_fields (desc_attr1->desc) == pango_font_description_get_set_fields (desc_attr2->desc) && - pango_font_description_equal (desc_attr1->desc, desc_attr2->desc); + pango_font_description_equal (desc_attr1->desc, desc_attr2->desc); } /** * pango_attr_font_desc_new: * @desc: the font description * - * Create a new font description attribute. This attribute - * allows setting family, style, weight, variant, stretch, - * and size simultaneously. + * Create a new font description attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * This attribute allows setting family, style, weight, variant, + * stretch, and size simultaneously. + * + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attr_font_desc_new (const PangoFontDescription *desc) { @@ -724,9 +716,9 @@ pango_attr_font_desc_new (const PangoFontDescription *desc) * * Create a new underline-style attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attr_underline_new (PangoUnderline underline) { @@ -746,19 +738,20 @@ pango_attr_underline_new (PangoUnderline underline) * @green: the green value * @blue: the blue value * - * Create a new underline color attribute. This attribute - * modifies the color of underlines. If not set, underlines + * Create a new underline color attribute. + * + * This attribute modifies the color of underlines. If not set, underlines * will use the foreground color. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.8 - **/ + */ PangoAttribute * pango_attr_underline_color_new (guint16 red, - guint16 green, - guint16 blue) + guint16 green, + guint16 blue) { static const PangoAttrClass klass = { PANGO_ATTR_UNDERLINE_COLOR, @@ -776,9 +769,9 @@ pango_attr_underline_color_new (guint16 red, * * Create a new strike-through attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attr_strikethrough_new (gboolean strikethrough) { @@ -798,19 +791,20 @@ pango_attr_strikethrough_new (gboolean strikethrough) * @green: the green value * @blue: the blue value * - * Create a new strikethrough color attribute. This attribute - * modifies the color of strikethrough lines. If not set, strikethrough - * lines will use the foreground color. + * Create a new strikethrough color attribute. + * + * This attribute modifies the color of strikethrough lines. If not set, + * strikethrough lines will use the foreground color. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.8 - **/ + */ PangoAttribute * pango_attr_strikethrough_color_new (guint16 red, - guint16 green, - guint16 blue) + guint16 green, + guint16 blue) { static const PangoAttrClass klass = { PANGO_ATTR_STRIKETHROUGH_COLOR, @@ -825,13 +819,13 @@ pango_attr_strikethrough_color_new (guint16 red, /** * pango_attr_rise_new: * @rise: the amount that the text should be displaced vertically, - * in Pango units. Positive values displace the text upwards. + * in Pango units. Positive values displace the text upwards. * * Create a new baseline displacement attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attr_rise_new (int rise) { @@ -849,12 +843,14 @@ pango_attr_rise_new (int rise) * pango_attr_scale_new: * @scale_factor: factor to scale the font * - * Create a new font size scale attribute. The base font for the - * affected text will have its size multiplied by @scale_factor. + * Create a new font size scale attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * The base font for the affected text will have its size multiplied + * by @scale_factor. + * + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute* pango_attr_scale_new (double scale_factor) { @@ -871,7 +867,7 @@ pango_attr_scale_new (double scale_factor) /** * pango_attr_fallback_new: * @enable_fallback: %TRUE if we should fall back on other fonts - * for characters the active font is missing. + * for characters the active font is missing. * * Create a new font fallback attribute. * @@ -880,11 +876,11 @@ pango_attr_scale_new (double scale_factor) * other fonts on the system that might contain the characters in the * text. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.4 - **/ + */ PangoAttribute * pango_attr_fallback_new (gboolean enable_fallback) { @@ -905,11 +901,11 @@ pango_attr_fallback_new (gboolean enable_fallback) * * Create a new letter-spacing attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.6 - **/ + */ PangoAttribute * pango_attr_letter_spacing_new (int letter_spacing) { @@ -935,7 +931,7 @@ pango_attr_shape_copy (const PangoAttribute *attr) data = shape_attr->data; return pango_attr_shape_new_with_data (&shape_attr->ink_rect, &shape_attr->logical_rect, - data, shape_attr->copy_func, shape_attr->destroy_func); + data, shape_attr->copy_func, shape_attr->destroy_func); } static void @@ -951,48 +947,48 @@ pango_attr_shape_destroy (PangoAttribute *attr) static gboolean pango_attr_shape_equal (const PangoAttribute *attr1, - const PangoAttribute *attr2) + const PangoAttribute *attr2) { const PangoAttrShape *shape_attr1 = (const PangoAttrShape *)attr1; const PangoAttrShape *shape_attr2 = (const PangoAttrShape *)attr2; return (shape_attr1->logical_rect.x == shape_attr2->logical_rect.x && - shape_attr1->logical_rect.y == shape_attr2->logical_rect.y && - shape_attr1->logical_rect.width == shape_attr2->logical_rect.width && - shape_attr1->logical_rect.height == shape_attr2->logical_rect.height && - shape_attr1->ink_rect.x == shape_attr2->ink_rect.x && - shape_attr1->ink_rect.y == shape_attr2->ink_rect.y && - shape_attr1->ink_rect.width == shape_attr2->ink_rect.width && - shape_attr1->ink_rect.height == shape_attr2->ink_rect.height && - shape_attr1->data == shape_attr2->data); + shape_attr1->logical_rect.y == shape_attr2->logical_rect.y && + shape_attr1->logical_rect.width == shape_attr2->logical_rect.width && + shape_attr1->logical_rect.height == shape_attr2->logical_rect.height && + shape_attr1->ink_rect.x == shape_attr2->ink_rect.x && + shape_attr1->ink_rect.y == shape_attr2->ink_rect.y && + shape_attr1->ink_rect.width == shape_attr2->ink_rect.width && + shape_attr1->ink_rect.height == shape_attr2->ink_rect.height && + shape_attr1->data == shape_attr2->data); } /** * pango_attr_shape_new_with_data: - * @ink_rect: ink rectangle to assign to each character + * @ink_rect: ink rectangle to assign to each character * @logical_rect: logical rectangle to assign to each character - * @data: user data pointer + * @data: user data pointer * @copy_func: (allow-none): function to copy @data when the - * attribute is copied. If %NULL, @data is simply - * copied as a pointer. + * attribute is copied. If %NULL, @data is simply copied as a pointer. * @destroy_func: (allow-none): function to free @data when the - * attribute is freed, or %NULL + * attribute is freed, or %NULL + * + * Creates a new shape attribute. * * Like pango_attr_shape_new(), but a user data pointer is also - * provided; this pointer can be accessed when later - * rendering the glyph. + * provided; this pointer can be accessed when later rendering the glyph. * - * Return value: the newly allocated #PangoAttribute, which should be - * freed with pango_attribute_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.8 - **/ + */ PangoAttribute * pango_attr_shape_new_with_data (const PangoRectangle *ink_rect, - const PangoRectangle *logical_rect, - gpointer data, - PangoAttrDataCopyFunc copy_func, - GDestroyNotify destroy_func) + const PangoRectangle *logical_rect, + gpointer data, + PangoAttrDataCopyFunc copy_func, + GDestroyNotify destroy_func) { static const PangoAttrClass klass = { PANGO_ATTR_SHAPE, @@ -1019,26 +1015,27 @@ pango_attr_shape_new_with_data (const PangoRectangle *ink_rect, /** * pango_attr_shape_new: - * @ink_rect: ink rectangle to assign to each character + * @ink_rect: ink rectangle to assign to each character * @logical_rect: logical rectangle to assign to each character * - * Create a new shape attribute. A shape is used to impose a - * particular ink and logical rectangle on the result of shaping a - * particular glyph. This might be used, for instance, for - * embedding a picture or a widget inside a #PangoLayout. + * Create a new shape attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). - **/ + * A shape is used to impose a particular ink and logical rectangle + * on the result of shaping a particular glyph. This might be used, + * for instance, for embedding a picture or a widget inside a `PangoLayout`. + * + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. + */ PangoAttribute * pango_attr_shape_new (const PangoRectangle *ink_rect, - const PangoRectangle *logical_rect) + const PangoRectangle *logical_rect) { g_return_val_if_fail (ink_rect != NULL, NULL); g_return_val_if_fail (logical_rect != NULL, NULL); return pango_attr_shape_new_with_data (ink_rect, logical_rect, - NULL, NULL, NULL); + NULL, NULL, NULL); } /** @@ -1047,11 +1044,11 @@ pango_attr_shape_new (const PangoRectangle *ink_rect, * * Create a new gravity attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.16 - **/ + */ PangoAttribute * pango_attr_gravity_new (PangoGravity gravity) { @@ -1073,11 +1070,11 @@ pango_attr_gravity_new (PangoGravity gravity) * * Create a new gravity hint attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.16 - **/ + */ PangoAttribute * pango_attr_gravity_hint_new (PangoGravityHint hint) { @@ -1097,11 +1094,11 @@ pango_attr_gravity_hint_new (PangoGravityHint hint) * * Create a new font features tag attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.38 - **/ + */ PangoAttribute * pango_attr_font_features_new (const gchar *features) { @@ -1123,8 +1120,8 @@ pango_attr_font_features_new (const gchar *features) * * Create a new foreground alpha attribute. * - * Return value: (transfer full): the new allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.38 */ @@ -1147,8 +1144,8 @@ pango_attr_foreground_alpha_new (guint16 alpha) * * Create a new background alpha attribute. * - * Return value: (transfer full): the new allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.38 */ @@ -1174,8 +1171,8 @@ pango_attr_background_alpha_new (guint16 alpha) * If breaks are disabled, the range will be kept in a * single run, as far as possible. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy() + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.44 */ @@ -1201,8 +1198,8 @@ pango_attr_allow_breaks_new (gboolean allow_breaks) * Pango will insert hyphens when breaking lines in the middle * of a word. This attribute can be used to suppress the hyphen. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy() + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.44 */ @@ -1221,13 +1218,13 @@ pango_attr_insert_hyphens_new (gboolean insert_hyphens) /** * pango_attr_show_new: - * @flags: #PangoShowFlags to apply + * @flags: `PangoShowFlags` to apply * * Create a new attribute that influences how invisible * characters are rendered. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.44 **/ @@ -1250,11 +1247,11 @@ pango_attr_show_new (PangoShowFlags flags) * * Create a new overline-style attribute. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.46 - **/ + */ PangoAttribute * pango_attr_overline_new (PangoOverline overline) { @@ -1274,15 +1271,16 @@ pango_attr_overline_new (PangoOverline overline) * @green: the green value * @blue: the blue value * - * Create a new overline color attribute. This attribute - * modifies the color of overlines. If not set, overlines + * Create a new overline color attribute. + * + * This attribute modifies the color of overlines. If not set, overlines * will use the foreground color. * - * Return value: (transfer full): the newly allocated #PangoAttribute, - * which should be freed with pango_attribute_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttribute`, + * which should be freed with [method@Pango.Attribute.destroy]. * * Since: 1.46 - **/ + */ PangoAttribute * pango_attr_overline_color_new (guint16 red, guint16 green, @@ -1318,9 +1316,9 @@ _pango_attr_list_init (PangoAttrList *list) * * Create a new empty attribute list with a reference count of one. * - * Return value: (transfer full): the newly allocated #PangoAttrList, - * which should be freed with pango_attr_list_unref(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttrList`, + * which should be freed with [method@Pango.AttrList.unref]. + */ PangoAttrList * pango_attr_list_new (void) { @@ -1333,14 +1331,14 @@ pango_attr_list_new (void) /** * pango_attr_list_ref: - * @list: (nullable): a #PangoAttrList, may be %NULL + * @list: (nullable): a `PangoAttrList`, may be %NULL * * Increase the reference count of the given attribute list by one. * * Return value: The attribute list passed in * * Since: 1.10 - **/ + */ PangoAttrList * pango_attr_list_ref (PangoAttrList *list) { @@ -1372,12 +1370,12 @@ _pango_attr_list_destroy (PangoAttrList *list) /** * pango_attr_list_unref: - * @list: (nullable): a #PangoAttrList, may be %NULL + * @list: (nullable): a `PangoAttrList`, may be %NULL * * Decrease the reference count of the given attribute list by one. * If the result is zero, free the attribute list and the attributes * it contains. - **/ + */ void pango_attr_list_unref (PangoAttrList *list) { @@ -1395,15 +1393,14 @@ pango_attr_list_unref (PangoAttrList *list) /** * pango_attr_list_copy: - * @list: (nullable): a #PangoAttrList, may be %NULL + * @list: (nullable): a `PangoAttrList`, may be %NULL * * Copy @list and return an identical new list. * - * Return value: (nullable): the newly allocated #PangoAttrList, with a - * reference count of one, which should - * be freed with pango_attr_list_unref(). - * Returns %NULL if @list was %NULL. - **/ + * Return value: (nullable): the newly allocated `PangoAttrList`, + * with a reference count of one, which should be freed with + * [method@Pango.AttrList.unref]. Returns %NULL if @list was %NULL. + */ PangoAttrList * pango_attr_list_copy (PangoAttrList *list) { @@ -1423,8 +1420,8 @@ pango_attr_list_copy (PangoAttrList *list) static void pango_attr_list_insert_internal (PangoAttrList *list, - PangoAttribute *attr, - gboolean before) + PangoAttribute *attr, + gboolean before) { const guint start_index = attr->start_index; PangoAttribute *last_attr; @@ -1467,17 +1464,18 @@ pango_attr_list_insert_internal (PangoAttrList *list, /** * pango_attr_list_insert: - * @list: a #PangoAttrList + * @list: a `PangoAttrList` * @attr: (transfer full): the attribute to insert. Ownership of this - * value is assumed by the list. + * value is assumed by the list. * - * Insert the given attribute into the #PangoAttrList. It will - * be inserted after all other attributes with a matching - * @start_index. - **/ + * Insert the given attribute into the `PangoAttrList`. + * + * It will be inserted after all other attributes with a + * matching @start_index. + */ void pango_attr_list_insert (PangoAttrList *list, - PangoAttribute *attr) + PangoAttribute *attr) { g_return_if_fail (list != NULL); g_return_if_fail (attr != NULL); @@ -1487,17 +1485,18 @@ pango_attr_list_insert (PangoAttrList *list, /** * pango_attr_list_insert_before: - * @list: a #PangoAttrList + * @list: a `PangoAttrList` * @attr: (transfer full): the attribute to insert. Ownership of this - * value is assumed by the list. + * value is assumed by the list. * - * Insert the given attribute into the #PangoAttrList. It will - * be inserted before all other attributes with a matching - * @start_index. - **/ + * Insert the given attribute into the `PangoAttrList`. + * + * It will be inserted before all other attributes with a + * matching @start_index. + */ void pango_attr_list_insert_before (PangoAttrList *list, - PangoAttribute *attr) + PangoAttribute *attr) { g_return_if_fail (list != NULL); g_return_if_fail (attr != NULL); @@ -1507,20 +1506,21 @@ pango_attr_list_insert_before (PangoAttrList *list, /** * pango_attr_list_change: - * @list: a #PangoAttrList + * @list: a `PangoAttrList` * @attr: (transfer full): the attribute to insert. Ownership of this - * value is assumed by the list. + * value is assumed by the list. + * + * Insert the given attribute into the `PangoAttrList`. * - * Insert the given attribute into the #PangoAttrList. It will - * replace any attributes of the same type on that segment + * It will replace any attributes of the same type on that segment * and be merged with any adjoining attributes that are identical. * - * This function is slower than pango_attr_list_insert() for - * creating an attribute list in order (potentially much slower - * for large lists). However, pango_attr_list_insert() is not - * suitable for continually changing a set of attributes - * since it never removes or combines existing attributes. - **/ + * This function is slower than [method@Pango.AttrList.insert] for + * creating an attribute list in order (potentially much slower for + * large lists). However, [method@Pango.AttrList.insert] is not + * suitable for continually changing a set of attributes since it + * never removes or combines existing attributes. + */ void pango_attr_list_change (PangoAttrList *list, PangoAttribute *attr) @@ -1665,27 +1665,25 @@ pango_attr_list_change (PangoAttrList *list, /** * pango_attr_list_update: - * @list: a #PangoAttrList + * @list: a `PangoAttrList` * @pos: the position of the change * @remove: the number of removed bytes * @add: the number of added bytes * - * Update indices of attributes in @list for - * a change in the text they refer to. + * Update indices of attributes in @list for a change in the + * text they refer to. * - * The change that this function applies is - * removing @remove bytes at position @pos - * and inserting @add bytes instead. + * The change that this function applies is removing @remove + * bytes at position @pos and inserting @add bytes instead. * - * Attributes that fall entirely in the - * (@pos, @pos + @remove) range are removed. + * Attributes that fall entirely in the (@pos, @pos + @remove) + * range are removed. * - * Attributes that start or end inside the - * (@pos, @pos + @remove) range are shortened to - * reflect the removal. + * Attributes that start or end inside the (@pos, @pos + @remove) + * range are shortened to reflect the removal. * - * Attributes start and end positions are updated - * if they are behind @pos + @remove. + * Attributes start and end positions are updated if they are + * behind @pos + @remove. * * Since: 1.44 */ @@ -1743,32 +1741,34 @@ pango_attr_list_update (PangoAttrList *list, /** * pango_attr_list_splice: - * @list: a #PangoAttrList - * @other: another #PangoAttrList + * @list: a `PangoAttrList` + * @other: another `PangoAttrList` * @pos: the position in @list at which to insert @other * @len: the length of the spliced segment. (Note that this - * must be specified since the attributes in @other - * may only be present at some subsection of this range) + * must be specified since the attributes in @other may only + * be present at some subsection of this range) * - * This function opens up a hole in @list, fills it in with attributes from - * the left, and then merges @other on top of the hole. + * This function opens up a hole in @list, fills it in with attributes + * from the left, and then merges @other on top of the hole. * * This operation is equivalent to stretching every attribute * that applies at position @pos in @list by an amount @len, - * and then calling pango_attr_list_change() with a copy - * of each attribute in @other in sequence (offset in position by @pos). + * and then calling [method@Pango.AttrList.change] with a copy + * of each attribute in @other in sequence (offset in position + * by @pos). * * This operation proves useful for, for instance, inserting * a pre-edit string in the middle of an edit buffer. - **/ + */ void pango_attr_list_splice (PangoAttrList *list, - PangoAttrList *other, - gint pos, - gint len) + PangoAttrList *other, + gint pos, + gint len) { guint i, p; guint upos, ulen; + guint end; g_return_if_fail (list != NULL); g_return_if_fail (other != NULL); @@ -1783,6 +1783,8 @@ pango_attr_list_splice (PangoAttrList *list, */ #define CLAMP_ADD(a,b) (((a) + (b) < (a)) ? G_MAXUINT : (a) + (b)) + end = CLAMP_ADD (upos, ulen); + if (list->attributes) for (i = 0, p = list->attributes->len; i < p; i++) { @@ -1811,8 +1813,8 @@ pango_attr_list_splice (PangoAttrList *list, for (i = 0, p = other->attributes->len; i < p; i++) { PangoAttribute *attr = pango_attribute_copy (g_ptr_array_index (other->attributes, i)); - attr->start_index = CLAMP_ADD (attr->start_index, upos); - attr->end_index = CLAMP_ADD (attr->end_index, upos); + attr->start_index = MIN (CLAMP_ADD (attr->start_index, upos), end); + attr->end_index = MIN (CLAMP_ADD (attr->end_index, upos), end); /* Same as above, the attribute could be squashed to zero-length; here * pango_attr_list_change() will take care of deleting it. @@ -1824,13 +1826,13 @@ pango_attr_list_splice (PangoAttrList *list, /** * pango_attr_list_get_attributes: - * @list: a #PangoAttrList + * @list: a `PangoAttrList` * * Gets a list of all attributes in @list. * * Return value: (element-type Pango.Attribute) (transfer full): * a list of all attributes in @list. To free this value, call - * pango_attribute_destroy() on each value and g_slist_free() + * [mehod@Pango.Attribute.destroy] on each value and g_slist_free() * on the list. * * Since: 1.44 @@ -1858,8 +1860,8 @@ pango_attr_list_get_attributes (PangoAttrList *list) /** * pango_attr_list_equal: - * @list: a #PangoAttrList - * @other_list: the other #PangoAttrList + * @list: a `PangoAttrList` + * @other_list: the other `PangoAttrList` * * Checks whether @list and @other_list contain the same attributes and * whether those attributes apply to the same ranges. Beware that this @@ -1953,13 +1955,13 @@ _pango_attr_list_get_iterator (PangoAttrList *list, /** * pango_attr_list_get_iterator: - * @list: a #PangoAttrList + * @list: a `PangoAttrList` * * Create a iterator initialized to the beginning of the list. * @list must not be modified until this iterator is freed. * - * Return value: (transfer full): the newly allocated #PangoAttrIterator, which should - * be freed with pango_attr_iterator_destroy(). + * Return value: (transfer full): the newly allocated `PangoAttrIterator`, + * which should be freed with [method@Pango.AttrIterator.destroy]. **/ PangoAttrIterator * pango_attr_list_get_iterator (PangoAttrList *list) @@ -1982,14 +1984,14 @@ pango_attr_list_get_iterator (PangoAttrList *list) * * Get the range of the current segment. Note that the * stored return values are signed, not unsigned like - * the values in #PangoAttribute. To deal with this API + * the values in `PangoAttribute`. To deal with this API * oversight, stored return values that wouldn't fit into * a signed integer are clamped to %G_MAXINT. - **/ + */ void pango_attr_iterator_range (PangoAttrIterator *iterator, - gint *start, - gint *end) + gint *start, + gint *end) { g_return_if_fail (iterator != NULL); @@ -2001,12 +2003,13 @@ pango_attr_iterator_range (PangoAttrIterator *iterator, /** * pango_attr_iterator_next: - * @iterator: a #PangoAttrIterator + * @iterator: a `PangoAttrIterator` * * Advance the iterator until the next change of style. * - * Return value: %FALSE if the iterator is at the end of the list, otherwise %TRUE - **/ + * Return value: %FALSE if the iterator is at the end of the list, + * otherwise %TRUE + */ gboolean pango_attr_iterator_next (PangoAttrIterator *iterator) { @@ -2071,14 +2074,13 @@ pango_attr_iterator_next (PangoAttrIterator *iterator) /** * pango_attr_iterator_copy: - * @iterator: a #PangoAttrIterator. + * @iterator: a `PangoAttrIterator` * - * Copy a #PangoAttrIterator + * Copy a `PangoAttrIterator`. * - * Return value: (transfer full): the newly allocated - * #PangoAttrIterator, which should be freed with - * pango_attr_iterator_destroy(). - **/ + * Return value: (transfer full): the newly allocated `PangoAttrIterator`, + * which should be freed with [method@Pango.AttrIterator.destroy]. + */ PangoAttrIterator * pango_attr_iterator_copy (PangoAttrIterator *iterator) { @@ -2107,10 +2109,10 @@ _pango_attr_iterator_destroy (PangoAttrIterator *iterator) /** * pango_attr_iterator_destroy: - * @iterator: a #PangoAttrIterator. + * @iterator: a `PangoAttrIterator` * - * Destroy a #PangoAttrIterator and free all associated memory. - **/ + * Destroy a `PangoAttrIterator` and free all associated memory. + */ void pango_attr_iterator_destroy (PangoAttrIterator *iterator) { @@ -2122,21 +2124,21 @@ pango_attr_iterator_destroy (PangoAttrIterator *iterator) /** * pango_attr_iterator_get: - * @iterator: a #PangoAttrIterator - * @type: the type of attribute to find. + * @iterator: a `PangoAttrIterator` + * @type: the type of attribute to find * * Find the current attribute of a particular type at the iterator * location. When multiple attributes of the same type overlap, * the attribute whose range starts closest to the current location * is used. * - * Return value: (nullable) (transfer none): the current attribute of the given type, - * or %NULL if no attribute of that type applies to the - * current location. - **/ + * Return value: (nullable) (transfer none): the current attribute of + * the given type, or %NULL if no attribute of that type applies to + * the current location. + */ PangoAttribute * pango_attr_iterator_get (PangoAttrIterator *iterator, - PangoAttrType type) + PangoAttrType type) { int i; @@ -2158,29 +2160,28 @@ pango_attr_iterator_get (PangoAttrIterator *iterator, /** * pango_attr_iterator_get_font: - * @iterator: a #PangoAttrIterator - * @desc: a #PangoFontDescription to fill in with the current values. - * The family name in this structure will be set using - * pango_font_description_set_family_static() using values from - * an attribute in the #PangoAttrList associated with the iterator, - * so if you plan to keep it around, you must call: - * <literal>pango_font_description_set_family (desc, pango_font_description_get_family (desc))</literal>. - * @language: (allow-none): if non-%NULL, location to store language tag for item, or %NULL - * if none is found. - * @extra_attrs: (allow-none) (element-type Pango.Attribute) (transfer full): if non-%NULL, - * location in which to store a list of non-font - * attributes at the the current position; only the highest priority - * value of each attribute will be added to this list. In order - * to free this value, you must call pango_attribute_destroy() on - * each member. + * @iterator: a `PangoAttrIterator` + * @desc: a `PangoFontDescription` to fill in with the current values. + * The family name in this structure will be set using + * [method@Pango.FontDescription.set_family_static] using values from + * an attribute in the `PangoAttrList` associated with the iterator, + * so if you plan to keep it around, you must call: + * pango_font_description_set_family (desc, pango_font_description_get_family (desc)). + * @language: (allow-none): if non-%NULL, location to store language tag + * for item, or %NULL if none is found. + * @extra_attrs: (allow-none) (element-type Pango.Attribute) (transfer full): + * if non-%NULL, location in which to store a list of non-font attributes + * at the the current position; only the highest priority value of each + * attribute will be added to this list. In order to free this value, you + * must call [method@Pango.Attribute.destroy] on each member. * * Get the font and other attributes at the current iterator position. - **/ + */ void pango_attr_iterator_get_font (PangoAttrIterator *iterator, - PangoFontDescription *desc, - PangoLanguage **language, - GSList **extra_attrs) + PangoFontDescription *desc, + PangoLanguage **language, + GSList **extra_attrs) { PangoFontMask mask = 0; gboolean have_language = FALSE; @@ -2205,91 +2206,91 @@ pango_attr_iterator_get_font (PangoAttrIterator *iterator, const PangoAttribute *attr = g_ptr_array_index (iterator->attribute_stack, i); switch ((int) attr->klass->type) - { - case PANGO_ATTR_FONT_DESC: - { - PangoFontMask new_mask = pango_font_description_get_set_fields (((PangoAttrFontDesc *)attr)->desc) & ~mask; - mask |= new_mask; - pango_font_description_unset_fields (desc, new_mask); - pango_font_description_merge_static (desc, ((PangoAttrFontDesc *)attr)->desc, FALSE); - - break; - } - case PANGO_ATTR_FAMILY: - if (!(mask & PANGO_FONT_MASK_FAMILY)) - { - mask |= PANGO_FONT_MASK_FAMILY; - pango_font_description_set_family (desc, ((PangoAttrString *)attr)->value); - } - break; - case PANGO_ATTR_STYLE: - if (!(mask & PANGO_FONT_MASK_STYLE)) - { - mask |= PANGO_FONT_MASK_STYLE; - pango_font_description_set_style (desc, ((PangoAttrInt *)attr)->value); - } - break; - case PANGO_ATTR_VARIANT: - if (!(mask & PANGO_FONT_MASK_VARIANT)) - { - mask |= PANGO_FONT_MASK_VARIANT; - pango_font_description_set_variant (desc, ((PangoAttrInt *)attr)->value); - } - break; - case PANGO_ATTR_WEIGHT: - if (!(mask & PANGO_FONT_MASK_WEIGHT)) - { - mask |= PANGO_FONT_MASK_WEIGHT; - pango_font_description_set_weight (desc, ((PangoAttrInt *)attr)->value); - } - break; - case PANGO_ATTR_STRETCH: - if (!(mask & PANGO_FONT_MASK_STRETCH)) - { - mask |= PANGO_FONT_MASK_STRETCH; - pango_font_description_set_stretch (desc, ((PangoAttrInt *)attr)->value); - } - break; - case PANGO_ATTR_SIZE: - if (!(mask & PANGO_FONT_MASK_SIZE)) - { - mask |= PANGO_FONT_MASK_SIZE; - pango_font_description_set_size (desc, ((PangoAttrSize *)attr)->size); - } - break; - case PANGO_ATTR_ABSOLUTE_SIZE: - if (!(mask & PANGO_FONT_MASK_SIZE)) - { - mask |= PANGO_FONT_MASK_SIZE; - pango_font_description_set_absolute_size (desc, ((PangoAttrSize *)attr)->size); - } - break; - case PANGO_ATTR_SCALE: - if (!have_scale) - { - have_scale = TRUE; - scale = ((PangoAttrFloat *)attr)->value; - } - break; - case PANGO_ATTR_LANGUAGE: - if (language) - { - if (!have_language) - { - have_language = TRUE; - *language = ((PangoAttrLanguage *)attr)->value; - } - } - break; - default: - if (extra_attrs) - { - gboolean found = FALSE; - - /* Hack: special-case FONT_FEATURES. We don't want them to - * override each other, so we never merge them. This should - * be fixed when we implement attr-merging. */ - if (attr->klass->type != PANGO_ATTR_FONT_FEATURES) + { + case PANGO_ATTR_FONT_DESC: + { + PangoFontMask new_mask = pango_font_description_get_set_fields (((PangoAttrFontDesc *)attr)->desc) & ~mask; + mask |= new_mask; + pango_font_description_unset_fields (desc, new_mask); + pango_font_description_merge_static (desc, ((PangoAttrFontDesc *)attr)->desc, FALSE); + + break; + } + case PANGO_ATTR_FAMILY: + if (!(mask & PANGO_FONT_MASK_FAMILY)) + { + mask |= PANGO_FONT_MASK_FAMILY; + pango_font_description_set_family (desc, ((PangoAttrString *)attr)->value); + } + break; + case PANGO_ATTR_STYLE: + if (!(mask & PANGO_FONT_MASK_STYLE)) + { + mask |= PANGO_FONT_MASK_STYLE; + pango_font_description_set_style (desc, ((PangoAttrInt *)attr)->value); + } + break; + case PANGO_ATTR_VARIANT: + if (!(mask & PANGO_FONT_MASK_VARIANT)) + { + mask |= PANGO_FONT_MASK_VARIANT; + pango_font_description_set_variant (desc, ((PangoAttrInt *)attr)->value); + } + break; + case PANGO_ATTR_WEIGHT: + if (!(mask & PANGO_FONT_MASK_WEIGHT)) + { + mask |= PANGO_FONT_MASK_WEIGHT; + pango_font_description_set_weight (desc, ((PangoAttrInt *)attr)->value); + } + break; + case PANGO_ATTR_STRETCH: + if (!(mask & PANGO_FONT_MASK_STRETCH)) + { + mask |= PANGO_FONT_MASK_STRETCH; + pango_font_description_set_stretch (desc, ((PangoAttrInt *)attr)->value); + } + break; + case PANGO_ATTR_SIZE: + if (!(mask & PANGO_FONT_MASK_SIZE)) + { + mask |= PANGO_FONT_MASK_SIZE; + pango_font_description_set_size (desc, ((PangoAttrSize *)attr)->size); + } + break; + case PANGO_ATTR_ABSOLUTE_SIZE: + if (!(mask & PANGO_FONT_MASK_SIZE)) + { + mask |= PANGO_FONT_MASK_SIZE; + pango_font_description_set_absolute_size (desc, ((PangoAttrSize *)attr)->size); + } + break; + case PANGO_ATTR_SCALE: + if (!have_scale) + { + have_scale = TRUE; + scale = ((PangoAttrFloat *)attr)->value; + } + break; + case PANGO_ATTR_LANGUAGE: + if (language) + { + if (!have_language) + { + have_language = TRUE; + *language = ((PangoAttrLanguage *)attr)->value; + } + } + break; + default: + if (extra_attrs) + { + gboolean found = FALSE; + + /* Hack: special-case FONT_FEATURES. We don't want them to + * override each other, so we never merge them. This should + * be fixed when we implement attr-merging. */ + if (attr->klass->type != PANGO_ATTR_FONT_FEATURES) { GSList *tmp_list = *extra_attrs; while (tmp_list) @@ -2305,10 +2306,10 @@ pango_attr_iterator_get_font (PangoAttrIterator *iterator, } } - if (!found) - *extra_attrs = g_slist_prepend (*extra_attrs, pango_attribute_copy (attr)); - } - } + if (!found) + *extra_attrs = g_slist_prepend (*extra_attrs, pango_attribute_copy (attr)); + } + } } if (have_scale) @@ -2322,24 +2323,23 @@ pango_attr_iterator_get_font (PangoAttrIterator *iterator, /** * pango_attr_list_filter: - * @list: a #PangoAttrList + * @list: a `PangoAttrList` * @func: (scope call) (closure data): callback function; returns %TRUE * if an attribute should be filtered out. * @data: (closure): Data to be passed to @func * - * Given a #PangoAttrList and callback function, removes any elements - * of @list for which @func returns %TRUE and inserts them into - * a new list. + * Given a `PangoAttrList` and callback function, removes any elements + * of @list for which @func returns %TRUE and inserts them into a new list. * - * Return value: (transfer full) (nullable): the new #PangoAttrList or + * Return value: (transfer full) (nullable): the new `PangoAttrList` or * %NULL if no attributes of the given types were found. * * Since: 1.2 - **/ + */ PangoAttrList * pango_attr_list_filter (PangoAttrList *list, - PangoAttrFilterFunc func, - gpointer data) + PangoAttrFilterFunc func, + gpointer data) { PangoAttrList *new = NULL; @@ -2375,18 +2375,18 @@ pango_attr_list_filter (PangoAttrList *list, /** * pango_attr_iterator_get_attrs: - * @iterator: a #PangoAttrIterator + * @iterator: a `PangoAttrIterator` * * Gets a list of all attributes at the current position of the * iterator. * - * Return value: (element-type Pango.Attribute) (transfer full): a list of - * all attributes for the current range. - * To free this value, call pango_attribute_destroy() on - * each value and g_slist_free() on the list. + * Return value: (element-type Pango.Attribute) (transfer full): + * a list of all attributes for the current range. To free this value, + * call [method@Pango.Attribute.destroy] on each value and g_slist_free() + * on the list. * * Since: 1.2 - **/ + */ GSList * pango_attr_iterator_get_attrs (PangoAttrIterator *iterator) { @@ -2404,17 +2404,17 @@ pango_attr_iterator_get_attrs (PangoAttrIterator *iterator) gboolean found = FALSE; for (tmp_list2 = attrs; tmp_list2; tmp_list2 = tmp_list2->next) - { - PangoAttribute *old_attr = tmp_list2->data; + { + PangoAttribute *old_attr = tmp_list2->data; if (attr->klass->type == old_attr->klass->type) { found = TRUE; break; } - } + } if (!found) - attrs = g_slist_prepend (attrs, pango_attribute_copy (attr)); + attrs = g_slist_prepend (attrs, pango_attribute_copy (attr)); } return attrs; diff --git a/pango/pango-attributes.h b/pango/pango-attributes.h index aecd1199..e20b6413 100644 --- a/pango/pango-attributes.h +++ b/pango/pango-attributes.h @@ -37,7 +37,7 @@ typedef struct _PangoColor PangoColor; * @green: value of green component * @blue: value of blue component * - * The #PangoColor structure is used to + * The `PangoColor` structure is used to * represent a color in an uncalibrated RGB color-space. */ struct _PangoColor @@ -50,7 +50,7 @@ struct _PangoColor /** * PANGO_TYPE_COLOR: * - * The #GObject type for #PangoColor. + * The `GObject` type for `PangoColor`. */ #define PANGO_TYPE_COLOR pango_color_get_type () PANGO_AVAILABLE_IN_ALL @@ -93,33 +93,36 @@ typedef struct _PangoAttrFontFeatures PangoAttrFontFeatures; /** * PANGO_TYPE_ATTR_LIST: * - * The #GObject type for #PangoAttrList. + * The `GObject` type for `PangoAttrList`. */ #define PANGO_TYPE_ATTR_LIST pango_attr_list_get_type () + /** * PangoAttrIterator: * - * The #PangoAttrIterator structure is used to represent an - * iterator through a #PangoAttrList. A new iterator is created - * with pango_attr_list_get_iterator(). Once the iterator - * is created, it can be advanced through the style changes - * in the text using pango_attr_iterator_next(). At each - * style change, the range of the current style segment and the - * attributes currently in effect can be queried. + * A `PangoAttrIterator` is used to iterate through a `PangoAttrList`. + * + * A new iterator is created with [method@Pango.AttrList.get_iterator]. + * Once the iterator is created, it can be advanced through the style + * changes in the text using [method@Pango.AttrIterator.next]. At each + * style change, the range of the current style segment and the attributes + * currently in effect can be queried. */ + /** * PangoAttrList: * - * The #PangoAttrList structure represents a list of attributes - * that apply to a section of text. The attributes are, in general, - * allowed to overlap in an arbitrary fashion, however, if the - * attributes are manipulated only through pango_attr_list_change(), - * the overlap between properties will meet stricter criteria. + * A `PangoAttrList` represents a list of attributes that apply to a section + * of text. + * + * The attributes in a `PangoAttrList` are, in general, allowed to overlap in + * an arbitrary fashion. However, if the attributes are manipulated only through + * [method@Pango.AttrList.change], the overlap between properties will meet + * stricter criteria. * - * Since the #PangoAttrList structure is stored as a linear list, - * it is not suitable for storing attributes for large amounts - * of text. In general, you should not use a single #PangoAttrList - * for more than one paragraph of text. + * Since the `PangoAttrList` structure is stored as a linear list, it is not + * suitable for storing attributes for large amounts of text. In general, you + * should not use a single `PangoAttrList` for more than one paragraph of text. */ typedef struct _PangoAttrList PangoAttrList; typedef struct _PangoAttrIterator PangoAttrIterator; @@ -127,43 +130,43 @@ typedef struct _PangoAttrIterator PangoAttrIterator; /** * PangoAttrType: * @PANGO_ATTR_INVALID: does not happen - * @PANGO_ATTR_LANGUAGE: language (#PangoAttrLanguage) - * @PANGO_ATTR_FAMILY: font family name list (#PangoAttrString) - * @PANGO_ATTR_STYLE: font slant style (#PangoAttrInt) - * @PANGO_ATTR_WEIGHT: font weight (#PangoAttrInt) - * @PANGO_ATTR_VARIANT: font variant (normal or small caps) (#PangoAttrInt) - * @PANGO_ATTR_STRETCH: font stretch (#PangoAttrInt) - * @PANGO_ATTR_SIZE: font size in points scaled by %PANGO_SCALE (#PangoAttrInt) - * @PANGO_ATTR_FONT_DESC: font description (#PangoAttrFontDesc) - * @PANGO_ATTR_FOREGROUND: foreground color (#PangoAttrColor) - * @PANGO_ATTR_BACKGROUND: background color (#PangoAttrColor) - * @PANGO_ATTR_UNDERLINE: whether the text has an underline (#PangoAttrInt) - * @PANGO_ATTR_STRIKETHROUGH: whether the text is struck-through (#PangoAttrInt) - * @PANGO_ATTR_RISE: baseline displacement (#PangoAttrInt) - * @PANGO_ATTR_SHAPE: shape (#PangoAttrShape) - * @PANGO_ATTR_SCALE: font size scale factor (#PangoAttrFloat) - * @PANGO_ATTR_FALLBACK: whether fallback is enabled (#PangoAttrInt) - * @PANGO_ATTR_LETTER_SPACING: letter spacing (#PangoAttrInt) - * @PANGO_ATTR_UNDERLINE_COLOR: underline color (#PangoAttrColor) - * @PANGO_ATTR_STRIKETHROUGH_COLOR: strikethrough color (#PangoAttrColor) - * @PANGO_ATTR_ABSOLUTE_SIZE: font size in pixels scaled by %PANGO_SCALE (#PangoAttrInt) - * @PANGO_ATTR_GRAVITY: base text gravity (#PangoAttrInt) - * @PANGO_ATTR_GRAVITY_HINT: gravity hint (#PangoAttrInt) - * @PANGO_ATTR_FONT_FEATURES: OpenType font features (#PangoAttrString). Since 1.38 - * @PANGO_ATTR_FOREGROUND_ALPHA: foreground alpha (#PangoAttrInt). Since 1.38 - * @PANGO_ATTR_BACKGROUND_ALPHA: background alpha (#PangoAttrInt). Since 1.38 - * @PANGO_ATTR_ALLOW_BREAKS: whether breaks are allowed (#PangoAttrInt). Since 1.44 - * @PANGO_ATTR_SHOW: how to render invisible characters (#PangoAttrInt). Since 1.44 - * @PANGO_ATTR_INSERT_HYPHENS: whether to insert hyphens at intra-word line breaks (#PangoAttrInt). Since 1.44 - * @PANGO_ATTR_OVERLINE: whether the text has an overline (#PangoAttrInt). Since 1.46 - * @PANGO_ATTR_OVERLINE_COLOR: overline color (#PangoAttrColor). Since 1.46 - * - * The #PangoAttrType - * distinguishes between different types of attributes. Along with the - * predefined values, it is possible to allocate additional values - * for custom attributes using pango_attr_type_register(). The predefined - * values are given below. The type of structure used to store the - * attribute is listed in parentheses after the description. + * @PANGO_ATTR_LANGUAGE: language ([struct@Pango.AttrLanguage]) + * @PANGO_ATTR_FAMILY: font family name list ([struct@Pango.AttrString]) + * @PANGO_ATTR_STYLE: font slant style ([struct@Pango.AttrInt]) + * @PANGO_ATTR_WEIGHT: font weight ([struct@Pango.AttrInt]) + * @PANGO_ATTR_VARIANT: font variant (normal or small caps) ([struct@Pango.AttrInt]) + * @PANGO_ATTR_STRETCH: font stretch ([struct@Pango.AttrInt]) + * @PANGO_ATTR_SIZE: font size in points scaled by %PANGO_SCALE ([struct@Pango.AttrInt]) + * @PANGO_ATTR_FONT_DESC: font description ([struct@Pango.AttrFontDesc]) + * @PANGO_ATTR_FOREGROUND: foreground color ([struct@Pango.AttrColor]) + * @PANGO_ATTR_BACKGROUND: background color ([struct@Pango.AttrColor]) + * @PANGO_ATTR_UNDERLINE: whether the text has an underline ([struct@Pango.AttrInt]) + * @PANGO_ATTR_STRIKETHROUGH: whether the text is struck-through ([struct@Pango.AttrInt]) + * @PANGO_ATTR_RISE: baseline displacement ([struct@Pango.AttrInt]) + * @PANGO_ATTR_SHAPE: shape ([struct@Pango.AttrShape]) + * @PANGO_ATTR_SCALE: font size scale factor ([struct@Pango.AttrFloat]) + * @PANGO_ATTR_FALLBACK: whether fallback is enabled ([struct@Pango.AttrInt]) + * @PANGO_ATTR_LETTER_SPACING: letter spacing ([struct@PangoAttrInt]) + * @PANGO_ATTR_UNDERLINE_COLOR: underline color ([struct@Pango.AttrColor]) + * @PANGO_ATTR_STRIKETHROUGH_COLOR: strikethrough color ([struct@Pango.AttrColor]) + * @PANGO_ATTR_ABSOLUTE_SIZE: font size in pixels scaled by %PANGO_SCALE ([struct@Pango.AttrInt]) + * @PANGO_ATTR_GRAVITY: base text gravity ([struct@Pango.AttrInt]) + * @PANGO_ATTR_GRAVITY_HINT: gravity hint ([struct@Pango.AttrInt]) + * @PANGO_ATTR_FONT_FEATURES: OpenType font features ([struct@Pango.AttrString]). Since 1.38 + * @PANGO_ATTR_FOREGROUND_ALPHA: foreground alpha ([struct@Pango.AttrInt]). Since 1.38 + * @PANGO_ATTR_BACKGROUND_ALPHA: background alpha ([struct@Pango.AttrInt]). Since 1.38 + * @PANGO_ATTR_ALLOW_BREAKS: whether breaks are allowed ([struct@Pango.AttrInt]). Since 1.44 + * @PANGO_ATTR_SHOW: how to render invisible characters ([struct@Pango.AttrInt]). Since 1.44 + * @PANGO_ATTR_INSERT_HYPHENS: whether to insert hyphens at intra-word line breaks ([struct@Pango.AttrInt]). Since 1.44 + * @PANGO_ATTR_OVERLINE: whether the text has an overline ([struct@Pango.AttrInt]). Since 1.46 + * @PANGO_ATTR_OVERLINE_COLOR: overline color ([struct@Pango.AttrColor]). Since 1.46 + * + * The `PangoAttrType` distinguishes between different types of attributes. + * + * Along with the predefined values, it is possible to allocate additional + * values for custom attributes using [type_func@attr_type_register]. The predefined + * values are given below. The type of structure used to store the attribute is + * listed in parentheses after the description. */ typedef enum { @@ -226,9 +229,8 @@ typedef enum * drawn continuously across multiple runs. This type * of underlining is available since Pango 1.46. * - * The #PangoUnderline enumeration is used to specify - * whether text should be underlined, and if so, the type - * of underlining. + * The `PangoUnderline` enumeration is used to specify whether text + * should be underlined, and if so, the type of underlining. */ typedef enum { PANGO_UNDERLINE_NONE, @@ -248,9 +250,8 @@ typedef enum { * @PANGO_OVERLINE_SINGLE: Draw a single line above the ink * extents of the text being underlined. * - * The #PangoOverline enumeration is used to specify - * whether text should be overlined, and if so, the type - * of line. + * The `PangoOverline` enumeration is used to specify whether text + * should be overlined, and if so, the type of line. * * Since: 1.46 */ @@ -262,8 +263,8 @@ typedef enum { /** * PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING: * - * This value can be used to set the start_index member of a #PangoAttribute - * such that the attribute covers from the beginning of the text. + * Value for @start_index in `PangoAttribute` that indicates + * the beginning of the text. * * Since: 1.24 */ @@ -272,8 +273,8 @@ typedef enum { /** * PANGO_ATTR_INDEX_TO_TEXT_END: (value 4294967295) * - * This value can be used to set the end_index member of a #PangoAttribute - * such that the attribute covers to the end of the text. + * Value for @end_index in `PangoAttribute` that indicates + * the end of the text. * * Since: 1.24 */ @@ -286,12 +287,14 @@ typedef enum { * @end_index: end index of the range (in bytes). The character at this index * is not included in the range. * - * The #PangoAttribute structure represents the common portions of all - * attributes. Particular types of attributes include this structure - * as their initial portion. The common portion of the attribute holds - * the range to which the value in the type-specific part of the attribute - * applies and should be initialized using pango_attribute_init(). - * By default an attribute will have an all-inclusive range of [0,%G_MAXUINT]. + * The `PangoAttribute` structure represents the common portions of all + * attributes. + * + * Particular types of attributes include this structure as their initial + * portion. The common portion of the attribute holds the range to which + * the value in the type-specific part of the attribute applies and should + * be initialized using [method@Pango.Attribute.init]. By default, an attribute + * will have an all-inclusive range of [0,%G_MAXUINT]. */ struct _PangoAttribute { @@ -308,8 +311,8 @@ struct _PangoAttribute * Type of a function filtering a list of attributes. * * Return value: %TRUE if the attribute should be selected for - * filtering, %FALSE otherwise. - **/ + * filtering, %FALSE otherwise. + */ typedef gboolean (*PangoAttrFilterFunc) (PangoAttribute *attribute, gpointer user_data); @@ -326,14 +329,18 @@ typedef gpointer (*PangoAttrDataCopyFunc) (gconstpointer user_data); /** * PangoAttrClass: * @type: the type ID for this attribute - * @copy: function to duplicate an attribute of this type (see pango_attribute_copy()) - * @destroy: function to free an attribute of this type (see pango_attribute_destroy()) - * @equal: function to check two attributes of this type for equality (see pango_attribute_equal()) - * - * The #PangoAttrClass structure stores the type and operations for - * a particular type of attribute. The functions in this structure should - * not be called directly. Instead, one should use the wrapper functions - * provided for #PangoAttribute. + * @copy: function to duplicate an attribute of this type + * (see [method@Pango.Attribute.copy]) + * @destroy: function to free an attribute of this type + * (see [method@Pango.Attribute.destroy]) + * @equal: function to check two attributes of this type for equality + * (see [method@Pango.Attribute.equal]) + * + * The `PangoAttrClass` structure stores the type and operations for + * a particular type of attribute. + * + * The functions in this structure should not be called directly. Instead, + * one should use the wrapper functions provided for `PangoAttribute`. */ struct _PangoAttrClass { @@ -349,7 +356,7 @@ struct _PangoAttrClass * @attr: the common portion of the attribute * @value: the string which is the value of the attribute * - * The #PangoAttrString structure is used to represent attributes with + * The `PangoAttrString` structure is used to represent attributes with * a string value. */ struct _PangoAttrString @@ -360,9 +367,9 @@ struct _PangoAttrString /** * PangoAttrLanguage: * @attr: the common portion of the attribute - * @value: the #PangoLanguage which is the value of the attribute + * @value: the `PangoLanguage` which is the value of the attribute * - * The #PangoAttrLanguage structure is used to represent attributes that + * The `PangoAttrLanguage` structure is used to represent attributes that * are languages. */ struct _PangoAttrLanguage @@ -375,7 +382,7 @@ struct _PangoAttrLanguage * @attr: the common portion of the attribute * @value: the value of the attribute * - * The #PangoAttrInt structure is used to represent attributes with + * The `PangoAttrInt` structure is used to represent attributes with * an integer or enumeration value. */ struct _PangoAttrInt @@ -388,7 +395,7 @@ struct _PangoAttrInt * @attr: the common portion of the attribute * @value: the value of the attribute * - * The #PangoAttrFloat structure is used to represent attributes with + * The `PangoAttrFloat` structure is used to represent attributes with * a float or double value. */ struct _PangoAttrFloat @@ -399,9 +406,9 @@ struct _PangoAttrFloat /** * PangoAttrColor: * @attr: the common portion of the attribute - * @color: the #PangoColor which is the value of the attribute + * @color: the `PangoColor` which is the value of the attribute * - * The #PangoAttrColor structure is used to represent attributes that + * The `PangoAttrColor` structure is used to represent attributes that * are colors. */ struct _PangoAttrColor @@ -414,13 +421,13 @@ struct _PangoAttrColor * PangoAttrSize: * @attr: the common portion of the attribute * @size: size of font, in units of 1/%PANGO_SCALE of a point (for - * %PANGO_ATTR_SIZE) or of a device uni (for %PANGO_ATTR_ABSOLUTE_SIZE) + * %PANGO_ATTR_SIZE) or of a device unit (for %PANGO_ATTR_ABSOLUTE_SIZE) * @absolute: whether the font size is in device units or points. - * This field is only present for compatibility with Pango-1.8.0 - * (%PANGO_ATTR_ABSOLUTE_SIZE was added in 1.8.1); and always will - * be %FALSE for %PANGO_ATTR_SIZE and %TRUE for %PANGO_ATTR_ABSOLUTE_SIZE. + * This field is only present for compatibility with Pango-1.8.0 + * (%PANGO_ATTR_ABSOLUTE_SIZE was added in 1.8.1); and always will + * be %FALSE for %PANGO_ATTR_SIZE and %TRUE for %PANGO_ATTR_ABSOLUTE_SIZE. * - * The #PangoAttrSize structure is used to represent attributes which + * The `PangoAttrSize` structure is used to represent attributes which * set font size. */ struct _PangoAttrSize @@ -435,11 +442,11 @@ struct _PangoAttrSize * @attr: the common portion of the attribute * @ink_rect: the ink rectangle to restrict to * @logical_rect: the logical rectangle to restrict to - * @data: user data set (see pango_attr_shape_new_with_data()) + * @data: user data set (see [type_func@Pango.AttrShape.new_with_data]) * @copy_func: copy function for the user data * @destroy_func: destroy function for the user data * - * The #PangoAttrShape structure is used to represent attributes which + * The `PangoAttrShape` structure is used to represent attributes which * impose shape restrictions. */ struct _PangoAttrShape @@ -458,7 +465,7 @@ struct _PangoAttrShape * @attr: the common portion of the attribute * @desc: the font description which is the value of this attribute * - * The #PangoAttrFontDesc structure is used to store an attribute that + * The `PangoAttrFontDesc` structure is used to store an attribute that * sets all aspects of the font description at once. */ struct _PangoAttrFontDesc @@ -472,7 +479,7 @@ struct _PangoAttrFontDesc * @attr: the common portion of the attribute * @features: the featues, as a string in CSS syntax * - * The #PangoAttrFontFeatures structure is used to represent OpenType + * The `PangoAttrFontFeatures` structure is used to represent OpenType * font features as an attribute. * * Since: 1.38 diff --git a/pango/pango-bidi-type.c b/pango/pango-bidi-type.c index d4d84e03..b86affba 100644 --- a/pango/pango-bidi-type.c +++ b/pango/pango-bidi-type.c @@ -19,24 +19,6 @@ * Boston, MA 02111-1307, USA. */ -/** - * SECTION:bidi - * @short_description:Types and functions for bidirectional text - * @title:Bidirectional Text - * @see_also: - * pango_context_get_base_dir(), - * pango_context_set_base_dir(), - * pango_itemize_with_base_dir() - * - * Pango supports bidirectional text (like Arabic and Hebrew) automatically. - * Some applications however, need some help to correctly handle bidirectional text. - * - * The #PangoDirection type can be used with pango_context_set_base_dir() to - * instruct Pango about direction of text, though in most cases Pango detects - * that correctly and automatically. The rest of the facilities in this section - * are used internally by Pango already, and are provided to help applications - * that need more direct control over bidirectional setting of text. - */ #include "config.h" #include <string.h> @@ -56,11 +38,11 @@ * pango_bidi_type_for_unichar: * @ch: a Unicode character * - * Determines the normative bidirectional character type of a - * character, as specified in the Unicode Character Database. + * Determines the bidirectional type of a character. * - * A simplified version of this function is available as - * pango_unichar_direction(). + * The bidirectional type is specified in the Unicode Character Database. + * + * A simplified version of this function is available as [func@unichar_direction]. * * Return value: the bidirectional character type, as used in the * Unicode bidirectional algorithm. @@ -114,8 +96,10 @@ pango_bidi_type_for_unichar (gunichar ch) * if @text is nul-terminated and the length should be calculated. * @pbase_dir: input base direction, and output resolved direction. * - * This will return the bidirectional embedding levels of the input paragraph - * as defined by the Unicode Bidirectional Algorithm available at: + * Return the bidirectional embedding levels of the input paragraph. + * + * The bidirectional embedding levels are defined by the Unicode Bidirectional + * Algorithm available at: * * http://www.unicode.org/reports/tr9/ * @@ -123,7 +107,7 @@ pango_bidi_type_for_unichar (gunichar ch) * characters in the text will determine the final resolved direction. * * Return value: a newly allocated array of embedding levels, one item per - * character (not byte), that should be freed using g_free. + * character (not byte), that should be freed using g_free(). * * Since: 1.4 */ @@ -282,14 +266,15 @@ resolved: * pango_unichar_direction: * @ch: a Unicode character * - * Determines the inherent direction of a character; either - * %PANGO_DIRECTION_LTR, %PANGO_DIRECTION_RTL, or - * %PANGO_DIRECTION_NEUTRAL. + * Determines the inherent direction of a character. + * + * The inherent direction is either %PANGO_DIRECTION_LTR, %PANGO_DIRECTION_RTL, + * or %PANGO_DIRECTION_NEUTRAL. * * This function is useful to categorize characters into left-to-right - * letters, right-to-left letters, and everything else. If full - * Unicode bidirectional type of a character is needed, - * pango_bidi_type_for_unichar() can be used instead. + * letters, right-to-left letters, and everything else. If full Unicode + * bidirectional type of a character is needed, [type_func@Pango.BidiType.for_unichar] + * can be used instead. * * Return value: the direction of the character. */ @@ -316,9 +301,9 @@ pango_unichar_direction (gunichar ch) * @ch: a Unicode character * @mirrored_ch: location to store the mirrored character * - * If @ch has the Unicode mirrored property and there is another Unicode - * character that typically has a glyph that is the mirror image of @ch's - * glyph, puts that character in the address pointed to by @mirrored_ch. + * Returns the mirrored character of a Unicode character. + * + * Mirror characters are determined by the Unicode mirrored property. * * Use g_unichar_get_mirror_char() instead; the docs for that function * provide full details. @@ -327,8 +312,8 @@ pango_unichar_direction (gunichar ch) * filled in, %FALSE otherwise **/ gboolean -pango_get_mirror_char (gunichar ch, - gunichar *mirrored_ch) +pango_get_mirror_char (gunichar ch, + gunichar *mirrored_ch) { return g_unichar_get_mirror_char (ch, mirrored_ch); } diff --git a/pango/pango-bidi-type.h b/pango/pango-bidi-type.h index aa1896c1..ebfaa574 100644 --- a/pango/pango-bidi-type.h +++ b/pango/pango-bidi-type.h @@ -52,7 +52,7 @@ G_BEGIN_DECLS * @PANGO_BIDI_TYPE_WS: Whitespace * @PANGO_BIDI_TYPE_ON: Other Neutrals * - * The #PangoBidiType type represents the bidirectional character + * `PangoBidiType` represents the bidirectional character * type of a Unicode character as specified by the * <ulink url="http://www.unicode.org/reports/tr9/">Unicode bidirectional algorithm</ulink>. * diff --git a/pango/pango-break.h b/pango/pango-break.h index 9209ee15..ae7d953a 100644 --- a/pango/pango-break.h +++ b/pango/pango-break.h @@ -37,51 +37,44 @@ G_BEGIN_DECLS * @is_char_break: if set, can break here when doing character wrapping * @is_white: is whitespace character * @is_cursor_position: if set, cursor can appear in front of character. - * i.e. this is a grapheme boundary, or the first character - * in the text. - * This flag implements Unicode's - * <ulink url="http://www.unicode.org/reports/tr29/">Grapheme - * Cluster Boundaries</ulink> semantics. + * i.e. this is a grapheme boundary, or the first character in the text. + * This flag implements Unicode's + * [Grapheme Cluster Boundaries](http://www.unicode.org/reports/tr29/) + * semantics. * @is_word_start: is first character in a word * @is_word_end: is first non-word char after a word - * Note that in degenerate cases, you could have both @is_word_start - * and @is_word_end set for some character. + * Note that in degenerate cases, you could have both @is_word_start + * and @is_word_end set for some character. * @is_sentence_boundary: is a sentence boundary. - * There are two ways to divide sentences. The first assigns all - * inter-sentence whitespace/control/format chars to some sentence, - * so all chars are in some sentence; @is_sentence_boundary denotes - * the boundaries there. The second way doesn't assign - * between-sentence spaces, etc. to any sentence, so + * There are two ways to divide sentences. The first assigns all + * inter-sentence whitespace/control/format chars to some sentence, + * so all chars are in some sentence; @is_sentence_boundary denotes + * the boundaries there. The second way doesn't assign + * between-sentence spaces, etc. to any sentence, so * @is_sentence_start/@is_sentence_end mark the boundaries of those sentences. * @is_sentence_start: is first character in a sentence * @is_sentence_end: is first char after a sentence. - * Note that in degenerate cases, you could have both @is_sentence_start - * and @is_sentence_end set for some character. (e.g. no space after a - * period, so the next sentence starts right away) + * Note that in degenerate cases, you could have both @is_sentence_start + * and @is_sentence_end set for some character. (e.g. no space after a + * period, so the next sentence starts right away) * @backspace_deletes_character: if set, backspace deletes one character - * rather than the entire grapheme cluster. This - * field is only meaningful on grapheme - * boundaries (where @is_cursor_position is - * set). In some languages, the full grapheme - * (e.g. letter + diacritics) is considered a - * unit, while in others, each decomposed - * character in the grapheme is a unit. In the - * default implementation of pango_break(), this - * bit is set on all grapheme boundaries except - * those following Latin, Cyrillic or Greek base characters. + * rather than the entire grapheme cluster. This field is only meaningful + * on grapheme boundaries (where @is_cursor_position is set). In some languages, + * the full grapheme (e.g. letter + diacritics) is considered a unit, while in + * others, each decomposed character in the grapheme is a unit. In the default + * implementation of [func@break], this bit is set on all grapheme boundaries + * except those following Latin, Cyrillic or Greek base characters. * @is_expandable_space: is a whitespace character that can possibly be - * expanded for justification purposes. (Since: 1.18) + * expanded for justification purposes. (Since: 1.18) * @is_word_boundary: is a word boundary, as defined by UAX#29. - * More specifically, means that this is not a position in the middle - * of a word. For example, both sides of a punctuation mark are - * considered word boundaries. This flag is particularly useful when - * selecting text word-by-word. - * This flag implements Unicode's - * <ulink url="http://www.unicode.org/reports/tr29/">Word - * Boundaries</ulink> semantics. (Since: 1.22) + * More specifically, means that this is not a position in the middle of a word. + * For example, both sides of a punctuation mark are considered word boundaries. + * This flag is particularly useful when selecting text word-by-word. This flag + * implements Unicode's [Word Boundaries](http://www.unicode.org/reports/tr29/) + * semantics. (Since: 1.22) * - * The #PangoLogAttr structure stores information - * about the attributes of a single character. + * The `PangoLogAttr` structure stores information about the attributes of a + * single character. */ struct _PangoLogAttr { diff --git a/pango/pango-color.c b/pango/pango-color.c index a530719f..f616e1f0 100644 --- a/pango/pango-color.c +++ b/pango/pango-color.c @@ -36,14 +36,15 @@ G_DEFINE_BOXED_TYPE (PangoColor, pango_color, * pango_color_copy: * @src: (nullable): color to copy, may be %NULL * - * Creates a copy of @src, which should be freed with - * pango_color_free(). Primarily used by language bindings, - * not that useful otherwise (since colors can just be copied - * by assignment in C). + * Creates a copy of @src. * - * Return value: (nullable): the newly allocated #PangoColor, which - * should be freed with pango_color_free(), or %NULL if - * @src was %NULL. + * The copy should be freed with pango_color_free(). Primarily + * used by language bindings, not that useful otherwise (since + * colors can just be copied by assignment in C). + * + * Return value: (nullable): the newly allocated `PangoColor`, which + * should be freed with [method@Pango.Color.free], or %NULL if + * @src was %NULL. **/ PangoColor* pango_color_copy (const PangoColor *src) @@ -79,10 +80,11 @@ pango_color_free (PangoColor *color) * pango_color_to_string: * @color: a #PangoColor * - * Returns a textual specification of @color in the hexadecimal form - * <literal>#rrrrggggbbbb</literal>, where <literal>r</literal>, - * <literal>g</literal> and <literal>b</literal> are hex digits representing - * the red, green, and blue components respectively. + * Returns a textual specification of @color. + * + * The string is in the hexadecimal form `#rrrrggggbbbb`, where + * `r`, `g` and `b` are hex digits representing the red, green, + * and blue components respectively. * * Return value: a newly-allocated text string that must be freed with g_free(). * @@ -209,28 +211,27 @@ hex (const char *spec, /** * pango_color_parse_with_alpha: - * @color: (nullable): a #PangoColor structure in which to store the + * @color: (nullable): a `PangoColor` structure in which to store the * result, or %NULL * @alpha: (out) (optional): return location for alpha, or %NULL * @spec: a string specifying the new color * - * Fill in the fields of a color from a string specification. The - * string can either one of a large set of standard names. (Taken - * from the CSS <ulink url="http://dev.w3.org/csswg/css-color/#named-colors">specification</ulink>), or it can be a hexadecimal - * value in the - * form '#rgb' '#rrggbb' '#rrrgggbbb' or '#rrrrggggbbbb' where - * 'r', 'g' and 'b' are hex digits of the red, green, and blue - * components of the color, respectively. (White in the four - * forms is '#fff' '#ffffff' '#fffffffff' and '#ffffffffffff') + * Fill in the fields of a color from a string specification. * - * Additionally, parse strings of the form - * '#rgba', '#rrggbbaa', '#rrrrggggbbbbaaaa', - * if @alpha is not %NULL, and set @alpha to the value specified - * by the hex digits for 'a'. If no alpha component is found + * The string can + * either one of a large set of standard names. (Taken from the CSS Color + * [specification](https://www.w3.org/TR/css-color-4/#named-colors), + * or it can be a hexadecimal value in the form `#rgb`, `#rrggbb`, `#rrrgggbbb` + * or `#rrrrggggbbbb` where `r`, `g` and `b` are hex digits of the red, green, + * and blue components of the color, respectively. (White in the four + * forms is `#fff`, `#ffffff`, `#fffffffff` and `#ffffffffffff`.) + * + * Additionally, parse strings of the form `#rgba`, `#rrggbbaa`, + * `#rrrrggggbbbbaaaa`, if @alpha is not %NULL, and set @alpha to the value + * specified by the hex digits for `a`. If no alpha component is found * in @spec, @alpha is set to 0xffff (for a solid color). * - * Return value: %TRUE if parsing of the specifier succeeded, - * otherwise false. + * Return value: %TRUE if parsing of the specifier succeeded, otherwise false. * * Since: 1.46 */ @@ -319,25 +320,25 @@ pango_color_parse_with_alpha (PangoColor *color, /** * pango_color_parse: - * @color: (nullable): a #PangoColor structure in which to store the + * @color: (nullable): a `PangoColor` structure in which to store the * result, or %NULL * @spec: a string specifying the new color * - * Fill in the fields of a color from a string specification. The - * string can either one of a large set of standard names. (Taken - * from the CSS <ulink url="http://dev.w3.org/csswg/css-color/#named-colors">specification</ulink>), or it can be a hexadecimal - * value in the - * form '#rgb' '#rrggbb' '#rrrgggbbb' or '#rrrrggggbbbb' where - * 'r', 'g' and 'b' are hex digits of the red, green, and blue - * components of the color, respectively. (White in the four - * forms is '#fff' '#ffffff' '#fffffffff' and '#ffffffffffff') + * Fill in the fields of a color from a string specification. + * + * The string can either + * one of a large set of standard names. (Taken from the CSS Color + * [specification](https://www.w3.org/TR/css-color-4/#named-colors), or it can be + * a value in the form `#rgb`, `#rrggbb`, `#rrrgggbbb` or `#rrrrggggbbbb`, where + * `r`, `g` and `b` are hex digits of the red, green, and blue components of the + * color, respectively. (White in the four forms is `#fff`, `#ffffff`, `#fffffffff` + * and `#ffffffffffff`.) * - * Return value: %TRUE if parsing of the specifier succeeded, - * otherwise false. + * Return value: %TRUE if parsing of the specifier succeeded, otherwise false. **/ gboolean pango_color_parse (PangoColor *color, - const char *spec) + const char *spec) { return pango_color_parse_with_alpha (color, NULL, spec); } diff --git a/pango/pango-context.c b/pango/pango-context.c index ec1014fa..1db11a1c 100644 --- a/pango/pango-context.c +++ b/pango/pango-context.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,18 +19,6 @@ * Boston, MA 02111-1307, USA. */ -/** - * SECTION:main - * @title:Rendering - * @short_description:Functions to run the rendering pipeline - * - * The Pango rendering pipeline takes a string of - * Unicode characters and converts it into glyphs. - * The functions described in this section accomplish - * various steps of this process. - * - *  - */ #include "config.h" #include <string.h> #include <stdlib.h> @@ -45,21 +33,16 @@ #include "pango-emoji-private.h" /** - * SECTION:context - * @title:Contexts - * @short_description: Global context object - * - * The #PangoContext structure stores global information - * influencing Pango's operation, such as the fontmap used - * to look up fonts, and default values such as the default - * language, default gravity, or default font. - */ - -/** * PangoContext: * - * The #PangoContext structure stores global information - * used to control the itemization process. + * A `PangoContext` stores global information used to control the + * itemization process. + * + * The information stored by `PangoContext includes the fontmap used + * to look up fonts, and default values such as the default language, + * default gravity, or default font. + * + * To obtain a `PangoContext`, use [method@Pango.FontMap.create_context]. */ struct _PangoContext { @@ -144,21 +127,21 @@ pango_context_finalize (GObject *object) /** * pango_context_new: * - * Creates a new #PangoContext initialized to default values. + * Creates a new `PangoContext` initialized to default values. * * This function is not particularly useful as it should always - * be followed by a pango_context_set_font_map() call, and the - * function pango_font_map_create_context() does these two steps + * be followed by a [method@Pango.Context.set_font_map] call, and the + * function [method@Pango.FontMap.create_context] does these two steps * together and hence users are recommended to use that. * * If you are using Pango as part of a higher-level system, - * that system may have it's own way of create a #PangoContext. - * For instance, the GTK+ toolkit has, among others, - * gtk_widget_get_pango_context(). Use those instead. + * that system may have it's own way of create a `PangoContext`. + * For instance, the GTK toolkit has, among others, + * `gtk_widget_get_pango_context()`. Use those instead. * - * Return value: the newly allocated #PangoContext, which should - * be freed with g_object_unref(). - **/ + * Return value: the newly allocated `PangoContext`, which should + * be freed with g_object_unref(). + */ PangoContext * pango_context_new (void) { @@ -180,22 +163,24 @@ update_resolved_gravity (PangoContext *context) /** * pango_context_set_matrix: - * @context: a #PangoContext - * @matrix: (allow-none): a #PangoMatrix, or %NULL to unset any existing + * @context: a `PangoContext` + * @matrix: (allow-none): a `PangoMatrix`, or %NULL to unset any existing * matrix. (No matrix set is the same as setting the identity matrix.) * * Sets the transformation matrix that will be applied when rendering - * with this context. Note that reported metrics are in the user space - * coordinates before the application of the matrix, not device-space - * coordinates after the application of the matrix. So, they don't scale - * with the matrix, though they may change slightly for different - * matrices, depending on how the text is fit to the pixel grid. + * with this context. + * + * Note that reported metrics are in the user space coordinates before + * the application of the matrix, not device-space coordinates after the + * application of the matrix. So, they don't scale with the matrix, though + * they may change slightly for different matrices, depending on how the + * text is fit to the pixel grid. * * Since: 1.6 - **/ + */ void -pango_context_set_matrix (PangoContext *context, - const PangoMatrix *matrix) +pango_context_set_matrix (PangoContext *context, + const PangoMatrix *matrix) { g_return_if_fail (PANGO_IS_CONTEXT (context)); @@ -214,17 +199,19 @@ pango_context_set_matrix (PangoContext *context, /** * pango_context_get_matrix: - * @context: a #PangoContext + * @context: a `PangoContext` * * Gets the transformation matrix that will be applied when - * rendering with this context. See pango_context_set_matrix(). + * rendering with this context. + * + * See [method@Pango.Context.set_matrix]. * * Return value: (nullable): the matrix, or %NULL if no matrix has - * been set (which is the same as the identity matrix). The returned - * matrix is owned by Pango and must not be modified or freed. + * been set (which is the same as the identity matrix). The returned + * matrix is owned by Pango and must not be modified or freed. * * Since: 1.6 - **/ + */ const PangoMatrix * pango_context_get_matrix (PangoContext *context) { @@ -235,16 +222,19 @@ pango_context_get_matrix (PangoContext *context) /** * pango_context_set_font_map: - * @context: a #PangoContext - * @font_map: the #PangoFontMap to set. + * @context: a `PangoContext` + * @font_map: the `PangoFontMap` to set. * - * Sets the font map to be searched when fonts are looked-up in this context. - * This is only for internal use by Pango backends, a #PangoContext obtained - * via one of the recommended methods should already have a suitable font map. - **/ + * Sets the font map to be searched when fonts are looked-up + * in this context. + * + * This is only for internal use by Pango backends, a `PangoContext` + * obtained via one of the recommended methods should already have a + * suitable font map. + */ void pango_context_set_font_map (PangoContext *context, - PangoFontMap *font_map) + PangoFontMap *font_map) { g_return_if_fail (PANGO_IS_CONTEXT (context)); g_return_if_fail (!font_map || PANGO_IS_FONT_MAP (font_map)); @@ -266,15 +256,15 @@ pango_context_set_font_map (PangoContext *context, /** * pango_context_get_font_map: - * @context: a #PangoContext + * @context: a `PangoContext` * - * Gets the #PangoFontMap used to look up fonts for this context. + * Gets the `PangoFontMap` used to look up fonts for this context. * - * Return value: (transfer none): the font map for the #PangoContext. - * This value is owned by Pango and should not be unreferenced. + * Return value: (transfer none): the font map for the `PangoContext`. + * This value is owned by Pango and should not be unreferenced. * * Since: 1.6 - **/ + */ PangoFontMap * pango_context_get_font_map (PangoContext *context) { @@ -285,18 +275,18 @@ pango_context_get_font_map (PangoContext *context) /** * pango_context_list_families: - * @context: a #PangoContext - * @families: (out) (array length=n_families) (transfer container): location to store a pointer to - * an array of #PangoFontFamily *. This array should be freed - * with g_free(). + * @context: a `PangoContext` + * @families: (out) (array length=n_families) (transfer container): location + * to store a pointer to an array of `PangoFontFamily`. This array should + * be freed with g_free(). * @n_families: (out): location to store the number of elements in @descs * * List all families for a context. - **/ + */ void -pango_context_list_families (PangoContext *context, - PangoFontFamily ***families, - int *n_families) +pango_context_list_families (PangoContext *context, + PangoFontFamily ***families, + int *n_families) { g_return_if_fail (context != NULL); g_return_if_fail (families == NULL || n_families != NULL); @@ -308,7 +298,7 @@ pango_context_list_families (PangoContext *context, { *n_families = 0; if (families) - *families = NULL; + *families = NULL; return; } @@ -318,18 +308,18 @@ pango_context_list_families (PangoContext *context, /** * pango_context_load_font: - * @context: a #PangoContext - * @desc: a #PangoFontDescription describing the font to load + * @context: a `PangoContext` + * @desc: a `PangoFontDescription` describing the font to load * * Loads the font in one of the fontmaps in the context * that is the closest match for @desc. * - * Returns: (transfer full) (nullable): the newly allocated #PangoFont - * that was loaded, or %NULL if no font matched. - **/ + * Returns: (transfer full) (nullable): the newly allocated `PangoFont` + * that was loaded, or %NULL if no font matched. + */ PangoFont * pango_context_load_font (PangoContext *context, - const PangoFontDescription *desc) + const PangoFontDescription *desc) { g_return_val_if_fail (context != NULL, NULL); g_return_val_if_fail (context->font_map != NULL, NULL); @@ -339,20 +329,20 @@ pango_context_load_font (PangoContext *context, /** * pango_context_load_fontset: - * @context: a #PangoContext - * @desc: a #PangoFontDescription describing the fonts to load - * @language: a #PangoLanguage the fonts will be used for + * @context: a `PangoContext` + * @desc: a `PangoFontDescription` describing the fonts to load + * @language: a `PangoLanguage` the fonts will be used for * * Load a set of fonts in the context that can be used to render * a font matching @desc. * * Returns: (transfer full) (nullable): the newly allocated - * #PangoFontset loaded, or %NULL if no font matched. - **/ + * `PangoFontset` loaded, or %NULL if no font matched. + */ PangoFontset * pango_context_load_fontset (PangoContext *context, - const PangoFontDescription *desc, - PangoLanguage *language) + const PangoFontDescription *desc, + PangoLanguage *language) { g_return_val_if_fail (context != NULL, NULL); @@ -361,14 +351,14 @@ pango_context_load_fontset (PangoContext *context, /** * pango_context_set_font_description: - * @context: a #PangoContext + * @context: a `PangoContext` * @desc: the new pango font description * * Set the default font description for the context - **/ + */ void pango_context_set_font_description (PangoContext *context, - const PangoFontDescription *desc) + const PangoFontDescription *desc) { g_return_if_fail (context != NULL); g_return_if_fail (desc != NULL); @@ -385,13 +375,13 @@ pango_context_set_font_description (PangoContext *context, /** * pango_context_get_font_description: - * @context: a #PangoContext + * @context: a `PangoContext` * * Retrieve the default font description for the context. * * Return value: (transfer none): a pointer to the context's default font - * description. This value must not be modified or freed. - **/ + * description. This value must not be modified or freed. + */ PangoFontDescription * pango_context_get_font_description (PangoContext *context) { @@ -402,16 +392,17 @@ pango_context_get_font_description (PangoContext *context) /** * pango_context_set_language: - * @context: a #PangoContext + * @context: a `PangoContext` * @language: the new language tag. * - * Sets the global language tag for the context. The default language - * for the locale of the running process can be found using - * pango_language_get_default(). - **/ + * Sets the global language tag for the context. + * + * The default language for the locale of the running process + * can be found using [type_func@Pango.Language.get_default]. + */ void -pango_context_set_language (PangoContext *context, - PangoLanguage *language) +pango_context_set_language (PangoContext *context, + PangoLanguage *language) { g_return_if_fail (context != NULL); @@ -427,12 +418,12 @@ pango_context_set_language (PangoContext *context, /** * pango_context_get_language: - * @context: a #PangoContext + * @context: a `PangoContext` * * Retrieves the global language tag for the context. * * Return value: the global language tag. - **/ + */ PangoLanguage * pango_context_get_language (PangoContext *context) { @@ -443,7 +434,7 @@ pango_context_get_language (PangoContext *context) /** * pango_context_set_base_dir: - * @context: a #PangoContext + * @context: a `PangoContext` * @direction: the new base direction * * Sets the base direction for the context. @@ -451,13 +442,13 @@ pango_context_get_language (PangoContext *context) * The base direction is used in applying the Unicode bidirectional * algorithm; if the @direction is %PANGO_DIRECTION_LTR or * %PANGO_DIRECTION_RTL, then the value will be used as the paragraph - * direction in the Unicode bidirectional algorithm. A value of + * direction in the Unicode bidirectional algorithm. A value of * %PANGO_DIRECTION_WEAK_LTR or %PANGO_DIRECTION_WEAK_RTL is used only * for paragraphs that do not contain any strong characters themselves. - **/ + */ void -pango_context_set_base_dir (PangoContext *context, - PangoDirection direction) +pango_context_set_base_dir (PangoContext *context, + PangoDirection direction) { g_return_if_fail (context != NULL); @@ -469,13 +460,14 @@ pango_context_set_base_dir (PangoContext *context, /** * pango_context_get_base_dir: - * @context: a #PangoContext + * @context: a `PangoContext` + * + * Retrieves the base direction for the context. * - * Retrieves the base direction for the context. See - * pango_context_set_base_dir(). + * See [method@Pango.Context.set_base_dir]. * * Return value: the base direction for the context. - **/ + */ PangoDirection pango_context_get_base_dir (PangoContext *context) { @@ -486,7 +478,7 @@ pango_context_get_base_dir (PangoContext *context) /** * pango_context_set_base_gravity: - * @context: a #PangoContext + * @context: a `PangoContext` * @gravity: the new base gravity * * Sets the base gravity for the context. @@ -494,10 +486,10 @@ pango_context_get_base_dir (PangoContext *context) * The base gravity is used in laying vertical text out. * * Since: 1.16 - **/ + */ void -pango_context_set_base_gravity (PangoContext *context, - PangoGravity gravity) +pango_context_set_base_gravity (PangoContext *context, + PangoGravity gravity) { g_return_if_fail (context != NULL); @@ -511,15 +503,16 @@ pango_context_set_base_gravity (PangoContext *context, /** * pango_context_get_base_gravity: - * @context: a #PangoContext + * @context: a `PangoContext` + * + * Retrieves the base gravity for the context. * - * Retrieves the base gravity for the context. See - * pango_context_set_base_gravity(). + * See [method@Pango.Context.set_base_gravity]. * * Return value: the base gravity for the context. * * Since: 1.16 - **/ + */ PangoGravity pango_context_get_base_gravity (PangoContext *context) { @@ -530,17 +523,19 @@ pango_context_get_base_gravity (PangoContext *context) /** * pango_context_get_gravity: - * @context: a #PangoContext + * @context: a `PangoContext` + * + * Retrieves the gravity for the context. * - * Retrieves the gravity for the context. This is similar to - * pango_context_get_base_gravity(), except for when the base gravity - * is %PANGO_GRAVITY_AUTO for which pango_gravity_get_for_matrix() is used - * to return the gravity from the current context matrix. + * This is similar to [method@Pango.Context.get_base_gravity], + * except for when the base gravity is %PANGO_GRAVITY_AUTO for + * which [type_func@Pango.Gravity.get_for_matrix] is used to return the + * gravity from the current context matrix. * * Return value: the resolved gravity for the context. * * Since: 1.16 - **/ + */ PangoGravity pango_context_get_gravity (PangoContext *context) { @@ -551,20 +546,21 @@ pango_context_get_gravity (PangoContext *context) /** * pango_context_set_gravity_hint: - * @context: a #PangoContext + * @context: a `PangoContext` * @hint: the new gravity hint * * Sets the gravity hint for the context. * - * The gravity hint is used in laying vertical text out, and is only relevant - * if gravity of the context as returned by pango_context_get_gravity() - * is set %PANGO_GRAVITY_EAST or %PANGO_GRAVITY_WEST. + * The gravity hint is used in laying vertical text out, and + * is only relevant if gravity of the context as returned by + * [method@Pango.Context.get_gravity] is set to %PANGO_GRAVITY_EAST + * or %PANGO_GRAVITY_WEST. * * Since: 1.16 - **/ + */ void -pango_context_set_gravity_hint (PangoContext *context, - PangoGravityHint hint) +pango_context_set_gravity_hint (PangoContext *context, + PangoGravityHint hint) { g_return_if_fail (context != NULL); @@ -576,15 +572,16 @@ pango_context_set_gravity_hint (PangoContext *context, /** * pango_context_get_gravity_hint: - * @context: a #PangoContext + * @context: a `PangoContext` + * + * Retrieves the gravity hint for the context. * - * Retrieves the gravity hint for the context. See - * pango_context_set_gravity_hint() for details. + * See [method@Pango.Context.set_gravity_hint] for details. * * Return value: the gravity hint for the context. * * Since: 1.16 - **/ + */ PangoGravityHint pango_context_get_gravity_hint (PangoContext *context) { @@ -597,7 +594,7 @@ pango_context_get_gravity_hint (PangoContext *context) static gboolean advance_attr_iterator_to (PangoAttrIterator *iterator, - int start_index) + int start_index) { int start_range, end_range; @@ -606,13 +603,13 @@ advance_attr_iterator_to (PangoAttrIterator *iterator, while (start_index >= end_range) { if (!pango_attr_iterator_next (iterator)) - return FALSE; + return FALSE; pango_attr_iterator_range (iterator, &start_range, &end_range); } if (start_range > start_index) g_warning ("In pango_itemize(), the cached iterator passed in " - "had already moved beyond the start_index"); + "had already moved beyond the start_index"); return TRUE; } @@ -659,7 +656,7 @@ retry: { cache = g_slice_new (FontCache); cache->hash = g_hash_table_new_full (g_direct_hash, NULL, - NULL, (GDestroyNotify)font_element_destroy); + NULL, (GDestroyNotify)font_element_destroy); if (!g_object_replace_qdata (G_OBJECT (fontset), cache_quark, NULL, cache, (GDestroyNotify)font_cache_destroy, NULL)) @@ -674,8 +671,8 @@ retry: static gboolean font_cache_get (FontCache *cache, - gunichar wc, - PangoFont **font) + gunichar wc, + PangoFont **font) { FontElement *element; @@ -692,8 +689,8 @@ font_cache_get (FontCache *cache, static void font_cache_insert (FontCache *cache, - gunichar wc, - PangoFont *font) + gunichar wc, + PangoFont *font) { FontElement *element = g_slice_new (FontElement); element->font = font ? g_object_ref (font) : NULL; @@ -719,11 +716,11 @@ typedef struct _PangoWidthIter PangoWidthIter; struct _PangoWidthIter { - const gchar *text_start; - const gchar *text_end; - const gchar *start; - const gchar *end; - gboolean upright; + const gchar *text_start; + const gchar *text_end; + const gchar *start; + const gchar *end; + gboolean upright; }; typedef struct _ItemizeState ItemizeState; @@ -784,7 +781,7 @@ update_embedding_end (ItemizeState *state) { state->embedding = state->embedding_levels[state->embedding_end_offset]; while (state->embedding_end < state->end && - state->embedding_levels[state->embedding_end_offset] == state->embedding) + state->embedding_levels[state->embedding_end_offset] == state->embedding) { state->embedding_end_offset++; state->embedding_end = g_utf8_next_char (state->embedding_end); @@ -795,7 +792,7 @@ update_embedding_end (ItemizeState *state) static PangoAttribute * find_attribute (GSList *attr_list, - PangoAttrType type) + PangoAttrType type) { GSList *node; @@ -830,7 +827,7 @@ update_attr_iterator (ItemizeState *state) pango_font_description_free (state->font_desc); state->font_desc = pango_font_description_copy_static (state->context->font_desc); pango_attr_iterator_get_font (state->attr_iter, state->font_desc, - &state->lang, &state->extra_attrs); + &state->lang, &state->extra_attrs); if (pango_font_description_get_set_fields (state->font_desc) & PANGO_FONT_MASK_GRAVITY) state->font_desc_gravity = pango_font_description_get_gravity (state->font_desc); else @@ -971,7 +968,9 @@ width_iter_next(PangoWidthIter* iter) } static void -width_iter_init (PangoWidthIter* iter, const char* text, int length) +width_iter_init (PangoWidthIter *iter, + const char *text, + int length) { iter->text_start = text; iter->text_end = text + length; @@ -986,15 +985,15 @@ width_iter_fini (PangoWidthIter* iter) } static void -itemize_state_init (ItemizeState *state, - PangoContext *context, - const char *text, - PangoDirection base_dir, - int start_index, - int length, - PangoAttrList *attrs, - PangoAttrIterator *cached_iter, - const PangoFontDescription *desc) +itemize_state_init (ItemizeState *state, + PangoContext *context, + const char *text, + PangoDirection base_dir, + int start_index, + int length, + PangoAttrList *attrs, + PangoAttrIterator *cached_iter, + const PangoFontDescription *desc) { state->context = context; @@ -1059,7 +1058,7 @@ itemize_state_init (ItemizeState *state, */ _pango_script_iter_init (&state->script_iter, text + start_index, length); pango_script_iter_get_range (&state->script_iter, NULL, - &state->script_end, &state->script); + &state->script_end, &state->script); width_iter_init (&state->width_iter, text + start_index, length); _pango_emoji_iter_init (&state->emoji_iter, text + start_index, length); @@ -1110,7 +1109,7 @@ itemize_state_next (ItemizeState *state) { pango_script_iter_next (&state->script_iter); pango_script_iter_get_range (&state->script_iter, NULL, - &state->script_end, &state->script); + &state->script_end, &state->script); state->changed |= SCRIPT_CHANGED; } if (state->run_end == state->emoji_iter.end) @@ -1146,7 +1145,7 @@ copy_attr_slist (GSList *attr_slist) static void itemize_state_fill_font (ItemizeState *state, - PangoFont *font) + PangoFont *font) { GList *l; @@ -1156,33 +1155,33 @@ itemize_state_fill_font (ItemizeState *state, if (item->analysis.font) break; if (font) - item->analysis.font = g_object_ref (font); + item->analysis.font = g_object_ref (font); } } static void itemize_state_add_character (ItemizeState *state, - PangoFont *font, - gboolean force_break, - const char *pos) + PangoFont *font, + gboolean force_break, + const char *pos) { if (state->item) { if (!state->item->analysis.font && font) - { - itemize_state_fill_font (state, font); - } + { + itemize_state_fill_font (state, font); + } else if (state->item->analysis.font && !font) - { - font = state->item->analysis.font; - } + { + font = state->item->analysis.font; + } if (!force_break && - state->item->analysis.font == font) - { - state->item->num_chars++; - return; - } + state->item->analysis.font == font) + { + state->item->num_chars++; + return; + } state->item->length = (pos - state->text) - state->item->offset; } @@ -1200,15 +1199,15 @@ itemize_state_add_character (ItemizeState *state, state->item->analysis.gravity = state->resolved_gravity; /* The level vs. gravity dance: - * - If gravity is SOUTH, leave level untouched. - * - If gravity is NORTH, step level one up, to - * not get mirrored upside-down text. - * - If gravity is EAST, step up to an even level, as - * it's a clockwise-rotated layout, so the rotated - * top is unrotated left. - * - If gravity is WEST, step up to an odd level, as - * it's a counter-clockwise-rotated layout, so the rotated - * top is unrotated right. + * - If gravity is SOUTH, leave level untouched. + * - If gravity is NORTH, step level one up, to + * not get mirrored upside-down text. + * - If gravity is EAST, step up to an even level, as + * it's a clockwise-rotated layout, so the rotated + * top is unrotated left. + * - If gravity is WEST, step up to an odd level, as + * it's a counter-clockwise-rotated layout, so the rotated + * top is unrotated right. * * A similar dance is performed in pango-layout.c: * line_set_resolved_dir(). Keep in synch. @@ -1217,17 +1216,17 @@ itemize_state_add_character (ItemizeState *state, { case PANGO_GRAVITY_SOUTH: default: - break; + break; case PANGO_GRAVITY_NORTH: - state->item->analysis.level++; - break; + state->item->analysis.level++; + break; case PANGO_GRAVITY_EAST: - state->item->analysis.level += 1; - state->item->analysis.level &= ~1; - break; + state->item->analysis.level += 1; + state->item->analysis.level &= ~1; + break; case PANGO_GRAVITY_WEST: - state->item->analysis.level |= 1; - break; + state->item->analysis.level |= 1; + break; } state->item->analysis.flags = state->centered_baseline ? PANGO_ANALYSIS_FLAG_CENTERED_BASELINE : 0; @@ -1256,8 +1255,8 @@ typedef struct { static gboolean get_font_foreach (PangoFontset *fontset, - PangoFont *font, - gpointer data) + PangoFont *font, + gpointer data) { GetFontInfo *info = data; @@ -1284,8 +1283,8 @@ get_base_font (ItemizeState *state) { if (!state->base_font) state->base_font = pango_font_map_load_font (state->context->font_map, - state->context, - state->font_desc); + state->context, + state->font_desc); return state->base_font; } @@ -1321,7 +1320,7 @@ get_font (ItemizeState *state, static PangoLanguage * compute_derived_language (PangoLanguage *lang, - PangoScript script) + PangoScript script) { PangoLanguage *derived_lang; @@ -1342,7 +1341,7 @@ compute_derived_language (PangoLanguage *lang, * safe here, though Keith Packard claims it is. */ if (!derived_lang) - derived_lang = pango_language_from_string ("xx"); + derived_lang = pango_language_from_string ("xx"); } return derived_lang; @@ -1357,28 +1356,28 @@ itemize_state_update_for_new_run (ItemizeState *state) { /* Font-desc gravity overrides everything */ if (state->font_desc_gravity != PANGO_GRAVITY_AUTO) - { - state->resolved_gravity = state->font_desc_gravity; - } + { + state->resolved_gravity = state->font_desc_gravity; + } else - { - PangoGravity gravity = state->gravity; - PangoGravityHint gravity_hint = state->gravity_hint; + { + PangoGravity gravity = state->gravity; + PangoGravityHint gravity_hint = state->gravity_hint; - if (G_LIKELY (gravity == PANGO_GRAVITY_AUTO)) - gravity = state->context->resolved_gravity; + if (G_LIKELY (gravity == PANGO_GRAVITY_AUTO)) + gravity = state->context->resolved_gravity; - state->resolved_gravity = pango_gravity_get_for_script_and_width (state->script, - state->width_iter.upright, - gravity, - gravity_hint); - } + state->resolved_gravity = pango_gravity_get_for_script_and_width (state->script, + state->width_iter.upright, + gravity, + gravity_hint); + } if (state->font_desc_gravity != state->resolved_gravity) - { - pango_font_description_set_gravity (state->font_desc, state->resolved_gravity); - state->changed |= FONT_CHANGED; - } + { + pango_font_description_set_gravity (state->font_desc, state->resolved_gravity); + state->changed |= FONT_CHANGED; + } } if (state->changed & (SCRIPT_CHANGED | LANG_CHANGED)) @@ -1386,7 +1385,7 @@ itemize_state_update_for_new_run (ItemizeState *state) PangoLanguage *old_derived_lang = state->derived_lang; state->derived_lang = compute_derived_language (state->lang, state->script); if (old_derived_lang != state->derived_lang) - state->changed |= DERIVED_LANG_CHANGED; + state->changed |= DERIVED_LANG_CHANGED; } if (state->changed & (EMOJI_CHANGED)) @@ -1411,9 +1410,9 @@ itemize_state_update_for_new_run (ItemizeState *state) pango_font_description_set_family_static (state->emoji_font_desc, "emoji"); } state->current_fonts = pango_font_map_load_fontset (state->context->font_map, - state->context, - is_emoji ? state->emoji_font_desc : state->font_desc, - state->derived_lang); + state->context, + is_emoji ? state->emoji_font_desc : state->font_desc, + state->derived_lang); state->cache = get_font_cache (state->current_fonts); } @@ -1470,16 +1469,16 @@ itemize_state_process_run (ItemizeState *state) (wc >= 0xfe00u && wc <= 0xfe0fu) || (wc >= 0xe0100u && wc <= 0xe01efu))) { - font = NULL; + font = NULL; } else { - get_font (state, wc, &font); - } + get_font (state, wc, &font); + } itemize_state_add_character (state, font, - is_forced_break || last_was_forced_break, - p); + is_forced_break || last_was_forced_break, + p); last_was_forced_break = is_forced_break; } @@ -1534,35 +1533,36 @@ itemize_state_finish (ItemizeState *state) /** * pango_itemize_with_base_dir: - * @context: a structure holding information that affects - * the itemization process. - * @base_dir: base direction to use for bidirectional processing - * @text: the text to itemize. + * @context: a structure holding information that affects + * the itemization process. + * @base_dir: base direction to use for bidirectional processing + * @text: the text to itemize. * @start_index: first byte in @text to process - * @length: the number of bytes (not characters) to process - * after @start_index. This must be >= 0. - * @attrs: the set of attributes that apply to @text. + * @length: the number of bytes (not characters) to process + * after @start_index. This must be >= 0. + * @attrs: the set of attributes that apply to @text. * @cached_iter: (allow-none): Cached attribute iterator, or %NULL * - * Like pango_itemize(), but the base direction to use when - * computing bidirectional levels (see pango_context_set_base_dir ()), - * is specified explicitly rather than gotten from the #PangoContext. + * Like `pango_itemize()`, but with an explicitly specified base direction. * - * Return value: (transfer full) (element-type Pango.Item): a #GList of - * #PangoItem structures. The items should be freed using - * pango_item_free() probably in combination with - * g_list_foreach(), and the list itself using g_list_free(). + * The base direction is used when computing bidirectional levels. + * (see [method@Pango.Context.set_base_dir]). [func@itemize] gets the + * base direction from the `PangoContext`. + * + * Return value: (transfer full) (element-type Pango.Item): a `GList` of + * [struct@Pango.Item] structures. The items should be freed using + * [method@Pango.Item.free] probably in combination with g_list_free_full(). * * Since: 1.4 */ GList * pango_itemize_with_base_dir (PangoContext *context, - PangoDirection base_dir, - const char *text, - int start_index, - int length, - PangoAttrList *attrs, - PangoAttrIterator *cached_iter) + PangoDirection base_dir, + const char *text, + int start_index, + int length, + PangoAttrList *attrs, + PangoAttrIterator *cached_iter) { ItemizeState state; @@ -1575,7 +1575,7 @@ pango_itemize_with_base_dir (PangoContext *context, return NULL; itemize_state_init (&state, context, text, base_dir, start_index, length, - attrs, cached_iter, NULL); + attrs, cached_iter, NULL); do itemize_state_process_run (&state); @@ -1588,10 +1588,10 @@ pango_itemize_with_base_dir (PangoContext *context, static GList * itemize_with_font (PangoContext *context, - const char *text, - int start_index, - int length, - const PangoFontDescription *desc) + const char *text, + int start_index, + int length, + const PangoFontDescription *desc) { ItemizeState state; @@ -1599,7 +1599,7 @@ itemize_with_font (PangoContext *context, return NULL; itemize_state_init (&state, context, text, context->base_dir, start_index, length, - NULL, NULL, desc); + NULL, NULL, desc); do itemize_state_process_run (&state); @@ -1612,39 +1612,39 @@ itemize_with_font (PangoContext *context, /** * pango_itemize: - * @context: a structure holding information that affects - the itemization process. - * @text: the text to itemize. Must be valid UTF-8 + * @context: a structure holding information that affects + * the itemization process. + * @text: the text to itemize. Must be valid UTF-8 * @start_index: first byte in @text to process - * @length: the number of bytes (not characters) to process - * after @start_index. - * This must be >= 0. - * @attrs: the set of attributes that apply to @text. + * @length: the number of bytes (not characters) to process + * after @start_index. This must be >= 0. + * @attrs: the set of attributes that apply to @text. * @cached_iter: (allow-none): Cached attribute iterator, or %NULL * - * Breaks a piece of text into segments with consistent - * directional level and shaping engine. Each byte of @text will - * be contained in exactly one of the items in the returned list; - * the generated list of items will be in logical order (the start - * offsets of the items are ascending). - * - * @cached_iter should be an iterator over @attrs currently positioned at a - * range before or containing @start_index; @cached_iter will be advanced to - * the range covering the position just after @start_index + @length. - * (i.e. if itemizing in a loop, just keep passing in the same @cached_iter). - * - * Return value: (transfer full) (element-type Pango.Item): a #GList of #PangoItem - * structures. The items should be freed using pango_item_free() - * probably in combination with g_list_foreach(), and the list itself - * using g_list_free(). + * Breaks a piece of text into segments with consistent directional + * level and font. + * + * Each byte of @text will be contained in exactly one of the items in the + * returned list; the generated list of items will be in logical order (the + * start offsets of the items are ascending). + * + * @cached_iter should be an iterator over @attrs currently positioned + * at a range before or containing @start_index; @cached_iter will be + * advanced to the range covering the position just after + * @start_index + @length. (i.e. if itemizing in a loop, just keep passing + * in the same @cached_iter). + * + * Return value: (transfer full) (element-type Pango.Item): a `GList` of + * [struct@Pango.Item] structures. The items should be freed using + * [method@Pango.Item.free] probably in combination with g_list_free_full(). */ GList * pango_itemize (PangoContext *context, - const char *text, - int start_index, - int length, - PangoAttrList *attrs, - PangoAttrIterator *cached_iter) + const char *text, + int start_index, + int length, + PangoAttrList *attrs, + PangoAttrIterator *cached_iter) { g_return_val_if_fail (context != NULL, NULL); g_return_val_if_fail (start_index >= 0, NULL); @@ -1652,13 +1652,13 @@ pango_itemize (PangoContext *context, g_return_val_if_fail (length == 0 || text != NULL, NULL); return pango_itemize_with_base_dir (context, context->base_dir, - text, start_index, length, attrs, cached_iter); + text, start_index, length, attrs, cached_iter); } static gboolean get_first_metrics_foreach (PangoFontset *fontset, - PangoFont *font, - gpointer data) + PangoFont *font, + gpointer data) { PangoFontMetrics *fontset_metrics = data; PangoLanguage *language = PANGO_FONTSET_GET_CLASS (fontset)->get_language (fontset); @@ -1675,7 +1675,7 @@ get_first_metrics_foreach (PangoFontset *fontset, pango_font_metrics_unref (font_metrics); - return TRUE; /* Stops iteration */ + return TRUE; /* Stops iteration */ } static PangoFontMetrics * @@ -1691,10 +1691,10 @@ get_base_metrics (PangoFontset *fontset) static void update_metrics_from_items (PangoFontMetrics *metrics, - PangoLanguage *language, - const char *text, - unsigned int text_len, - GList *items) + PangoLanguage *language, + const char *text, + unsigned int text_len, + GList *items) { GHashTable *fonts_seen = g_hash_table_new (NULL, NULL); @@ -1713,20 +1713,20 @@ update_metrics_from_items (PangoFontMetrics *metrics, PangoFont *font = item->analysis.font; if (font != NULL && g_hash_table_lookup (fonts_seen, font) == NULL) - { - PangoFontMetrics *raw_metrics = pango_font_get_metrics (font, language); - g_hash_table_insert (fonts_seen, font, font); - - /* metrics will already be initialized from the first font in the fontset */ - metrics->ascent = MAX (metrics->ascent, raw_metrics->ascent); - metrics->descent = MAX (metrics->descent, raw_metrics->descent); - metrics->height = MAX (metrics->height, raw_metrics->height); - pango_font_metrics_unref (raw_metrics); - } + { + PangoFontMetrics *raw_metrics = pango_font_get_metrics (font, language); + g_hash_table_insert (fonts_seen, font, font); + + /* metrics will already be initialized from the first font in the fontset */ + metrics->ascent = MAX (metrics->ascent, raw_metrics->ascent); + metrics->descent = MAX (metrics->descent, raw_metrics->descent); + metrics->height = MAX (metrics->height, raw_metrics->height); + pango_font_metrics_unref (raw_metrics); + } pango_shape_full (text + item->offset, item->length, - text, text_len, - &item->analysis, glyphs); + text, text_len, + &item->analysis, glyphs); metrics->approximate_char_width += pango_glyph_string_get_width (glyphs); } @@ -1740,35 +1740,34 @@ update_metrics_from_items (PangoFontMetrics *metrics, /** * pango_context_get_metrics: - * @context: a #PangoContext - * @desc: (allow-none): a #PangoFontDescription structure. %NULL means that the - * font description from the context will be used. + * @context: a `PangoContext` + * @desc: (allow-none): a `PangoFontDescription` structure. %NULL means that the + * font description from the context will be used. * @language: (allow-none): language tag used to determine which script to get - * the metrics for. %NULL means that the language tag from the context - * will be used. If no language tag is set on the context, metrics - * for the default language (as determined by pango_language_get_default()) - * will be returned. - * - * Get overall metric information for a particular font - * description. 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. - * - * The #PangoFontDescription is interpreted in the same way as - * by pango_itemize(), and the family name may be a comma separated - * list of figures. If characters from multiple of these families - * would be used to render the string, then the returned fonts would - * be a composite of the metrics for the fonts loaded for the - * individual families. - * - * Return value: a #PangoFontMetrics object. The caller must call pango_font_metrics_unref() - * when finished using the object. - **/ + * the metrics for. %NULL means that the language tag from the context + * will be used. If no language tag is set on the context, metrics + * for the default language (as determined by [type_func@Pango.Language.get_default] + * will be returned. + * + * Get overall metric information for a particular font description. + * + * 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. + * + * The `PangoFontDescription` is interpreted in the same way as by [func@itemize], + * and the family name may be a comma separated list of names. If characters + * from multiple of these families would be used to render the string, then + * the returned fonts would be a composite of the metrics for the fonts loaded + * for the individual families. + * + * Return value: a `PangoFontMetrics` object. The caller must call + * [method@Pango.FontMetrics.unref] when finished using the object. + */ PangoFontMetrics * -pango_context_get_metrics (PangoContext *context, - const PangoFontDescription *desc, - PangoLanguage *language) +pango_context_get_metrics (PangoContext *context, + const PangoFontDescription *desc, + PangoLanguage *language) { PangoFontset *current_fonts = NULL; PangoFontMetrics *metrics; @@ -1802,7 +1801,7 @@ pango_context_get_metrics (PangoContext *context, } static void -context_changed (PangoContext *context) +context_changed (PangoContext *context) { context->serial++; if (context->serial == 0) @@ -1811,9 +1810,9 @@ context_changed (PangoContext *context) /** * pango_context_changed: - * @context: a #PangoContext + * @context: a `PangoContext` * - * Forces a change in the context, which will cause any #PangoLayout + * Forces a change in the context, which will cause any `PangoLayout` * using this context to re-layout. * * This function is only useful when implementing a new backend @@ -1824,7 +1823,7 @@ context_changed (PangoContext *context) * Since: 1.32.4 **/ void -pango_context_changed (PangoContext *context) +pango_context_changed (PangoContext *context) { context_changed (context); } @@ -1845,23 +1844,25 @@ check_fontmap_changed (PangoContext *context) /** * pango_context_get_serial: - * @context: a #PangoContext + * @context: a `PangoContext` + * + * Returns the current serial number of @context. * - * Returns the current serial number of @context. The serial number is - * initialized to an small number larger than zero when a new context - * is created and is increased whenever the context is changed using any - * of the setter functions, or the #PangoFontMap it uses to find fonts has - * changed. The serial may wrap, but will never have the value 0. Since it - * can wrap, never compare it with "less than", always use "not equals". + * The serial number is initialized to an small number larger than zero + * when a new context is created and is increased whenever the context + * is changed using any of the setter functions, or the `PangoFontMap` it + * uses to find fonts has changed. The serial may wrap, but will never + * have the value 0. Since it can wrap, never compare it with "less than", + * always use "not equals". * - * This can be used to automatically detect changes to a #PangoContext, and - * is only useful when implementing objects that need update when their - * #PangoContext changes, like #PangoLayout. + * This can be used to automatically detect changes to a `PangoContext`, + * and is only useful when implementing objects that need update when their + * `PangoContext` changes, like `PangoLayout`. * * Return value: The current serial number of @context. * * Since: 1.32.4 - **/ + */ guint pango_context_get_serial (PangoContext *context) { @@ -1871,7 +1872,7 @@ pango_context_get_serial (PangoContext *context) /** * pango_context_set_round_glyph_positions: - * @context: a #PangoContext + * @context: a `PangoContext` * @round_positions: whether to round glyph positions * * Sets whether font rendering with this context should @@ -1899,7 +1900,7 @@ pango_context_set_round_glyph_positions (PangoContext *context, /** * pango_context_get_round_glyph_positions: - * @context: a #PangoContext + * @context: a `PangoContext` * * Returns whether font rendering with this context should * round glyph positions and widths. diff --git a/pango/pango-coverage.c b/pango/pango-coverage.c index 5358e4e7..ebd258b2 100644 --- a/pango/pango-coverage.c +++ b/pango/pango-coverage.c @@ -19,16 +19,6 @@ * Boston, MA 02111-1307, USA. */ -/** - * SECTION:coverage-maps - * @short_description:Unicode character range coverage storage - * @title:Coverage Maps - * - * It is often necessary in Pango to determine if a particular font can - * represent a particular character, and also how well it can represent - * that character. The #PangoCoverage is a data structure that is used - * to represent that information. - */ #include "config.h" #include <string.h> @@ -117,9 +107,9 @@ pango_coverage_class_init (PangoCoverageClass *class) /** * pango_coverage_new: * - * Create a new #PangoCoverage + * Create a new `PangoCoverage` * - * Return value: the newly allocated #PangoCoverage, + * Return value: the newly allocated `PangoCoverage`, * initialized to %PANGO_COVERAGE_NONE * with a reference count of one, which * should be freed with pango_coverage_unref(). @@ -132,12 +122,11 @@ pango_coverage_new (void) /** * pango_coverage_copy: - * @coverage: a #PangoCoverage + * @coverage: a `PangoCoverage` * - * Copy an existing #PangoCoverage. (This function may now be unnecessary - * since we refcount the structure. File a bug if you use it.) + * Copy an existing `PangoCoverage`. * - * Return value: (transfer full): the newly allocated #PangoCoverage, + * Return value: (transfer full): the newly allocated `PangoCoverage`, * with a reference count of one, which should be freed * with pango_coverage_unref(). **/ @@ -149,9 +138,9 @@ pango_coverage_copy (PangoCoverage *coverage) /** * pango_coverage_ref: - * @coverage: (not nullable): a #PangoCoverage + * @coverage: (not nullable): a `PangoCoverage` * - * Increase the reference count on the #PangoCoverage by one + * Increase the reference count on the `PangoCoverage` by one. * * Return value: (transfer full): @coverage **/ @@ -163,9 +152,10 @@ pango_coverage_ref (PangoCoverage *coverage) /** * pango_coverage_unref: - * @coverage: (transfer full) (not nullable): a #PangoCoverage + * @coverage: (transfer full) (not nullable): a `PangoCoverage` + * + * Decrease the reference count on the `PangoCoverage` by one. * - * Decrease the reference count on the #PangoCoverage by one. * If the result is zero, free the coverage and all associated memory. **/ void @@ -176,10 +166,10 @@ pango_coverage_unref (PangoCoverage *coverage) /** * pango_coverage_get: - * @coverage: a #PangoCoverage + * @coverage: a `PangoCoverage` * @index_: the index to check * - * Determine whether a particular index is covered by @coverage + * Determine whether a particular index is covered by @coverage. * * Return value: the coverage level of @coverage for character @index_. **/ @@ -192,7 +182,7 @@ pango_coverage_get (PangoCoverage *coverage, /** * pango_coverage_set: - * @coverage: a #PangoCoverage + * @coverage: a `PangoCoverage` * @index_: the index to modify * @level: the new level for @index_ * @@ -208,8 +198,8 @@ pango_coverage_set (PangoCoverage *coverage, /** * pango_coverage_max: - * @coverage: a #PangoCoverage - * @other: another #PangoCoverage + * @coverage: a `PangoCoverage` + * @other: another `PangoCoverage` * * Set the coverage for each index in @coverage to be the max (better) * value of the current coverage for the index and the coverage for @@ -225,12 +215,12 @@ pango_coverage_max (PangoCoverage *coverage, /** * pango_coverage_to_bytes: - * @coverage: a #PangoCoverage + * @coverage: a `PangoCoverage` * @bytes: (out) (array length=n_bytes) (element-type guint8): * location to store result (must be freed with g_free()) * @n_bytes: (out): location to store size of result * - * Convert a #PangoCoverage structure into a flat binary format + * Convert a `PangoCoverage` structure into a flat binary format. * * Deprecated: 1.44: This returns %NULL **/ @@ -246,14 +236,14 @@ pango_coverage_to_bytes (PangoCoverage *coverage, /** * pango_coverage_from_bytes: * @bytes: (array length=n_bytes) (element-type guint8): binary data - * representing a #PangoCoverage + * representing a `PangoCoverage` * @n_bytes: the size of @bytes in bytes * * Convert data generated from pango_coverage_to_bytes() back - * to a #PangoCoverage + * to a `PangoCoverage`. * * Return value: (transfer full) (nullable): a newly allocated - * #PangoCoverage, or %NULL if the data was invalid. + * `PangoCoverage`, or %NULL if the data was invalid. * * Deprecated: 1.44: This returns %NULL **/ diff --git a/pango/pango-coverage.h b/pango/pango-coverage.h index 7467dbda..67fc6306 100644 --- a/pango/pango-coverage.h +++ b/pango/pango-coverage.h @@ -32,8 +32,13 @@ G_BEGIN_DECLS /** * PangoCoverage: * - * The #PangoCoverage structure represents a map from Unicode characters - * to #PangoCoverageLevel. It is an opaque structure with no public fields. + * A #PangoCoverage structure is a map from Unicode characters + * to #PangoCoverageLevel values. + * + * It is often necessary in Pango to determine if a particular font can + * represent a particular character, and also how well it can represent + * that character. The #PangoCoverage is a data structure that is used to + * represent that information. It is an opaque structure with no public fields. */ typedef struct _PangoCoverage PangoCoverage; @@ -49,8 +54,8 @@ typedef struct _PangoCoverage PangoCoverage; * the current script. * @PANGO_COVERAGE_EXACT: The character is represented as the correct graphical form. * - * Used to indicate how well a font can represent a particular Unicode - * character point for a particular script. + * `PangoCoverageLevel` is used to indicate how well a font can represent + * a particular Unicode character for a particular script. * * Since 1.44, only %PANGO_COVERAGE_NONE and %PANGO_COVERAGE_EXACT * will be returned. diff --git a/pango/pango-direction.h b/pango/pango-direction.h index 6cbd5aa7..7da14175 100644 --- a/pango/pango-direction.h +++ b/pango/pango-direction.h @@ -38,26 +38,25 @@ G_BEGIN_DECLS * @PANGO_DIRECTION_WEAK_RTL: A weak right-to-left direction * @PANGO_DIRECTION_NEUTRAL: No direction specified * - * The #PangoDirection type represents a direction in the - * Unicode bidirectional algorithm; not every value in this - * enumeration makes sense for every usage of #PangoDirection; - * for example, the return value of pango_unichar_direction() - * and pango_find_base_dir() cannot be %PANGO_DIRECTION_WEAK_LTR - * or %PANGO_DIRECTION_WEAK_RTL, since every character is either - * neutral or has a strong direction; on the other hand - * %PANGO_DIRECTION_NEUTRAL doesn't make sense to pass - * to pango_itemize_with_base_dir(). + * `PangoDirection` represents a direction in the Unicode bidirectional + * algorithm. * - * The %PANGO_DIRECTION_TTB_LTR, %PANGO_DIRECTION_TTB_RTL - * values come from an earlier interpretation of this - * enumeration as the writing direction of a block of - * text and are no longer used; See #PangoGravity for how + * Not every value in this enumeration makes sense for every usage of + * `PangoDirection`; for example, the return value of [func@unichar_direction] + * and [func@find_base_dir] cannot be %PANGO_DIRECTION_WEAK_LTR or + * %PANGO_DIRECTION_WEAK_RTL, since every character is either neutral + * or has a strong direction; on the other hand %PANGO_DIRECTION_NEUTRAL + * doesn't make sense to pass to [func@itemize_with_base_dir]. + * + * The %PANGO_DIRECTION_TTB_LTR, %PANGO_DIRECTION_TTB_RTL values come from + * an earlier interpretation of this enumeration as the writing direction + * of a block of text and are no longer used; See `PangoGravity` for how * vertical text is handled in Pango. * - * If you are interested in text direction, you should - * really use fribidi directly. PangoDirection is only - * retained because it is used in some public apis. - **/ + * If you are interested in text direction, you should really use fribidi + * directly. `PangoDirection` is only retained because it is used in some + * public apis. + */ typedef enum { PANGO_DIRECTION_LTR, PANGO_DIRECTION_RTL, diff --git a/pango/pango-engine.c b/pango/pango-engine.c index 34d09641..e52bcd99 100644 --- a/pango/pango-engine.c +++ b/pango/pango-engine.c @@ -19,44 +19,6 @@ * Boston, MA 02111-1307, USA. */ -/** - * SECTION:engines - * @short_description:Language-specific and rendering-system-specific processing - * @title:Engines - * - * Pango used to have a module architecture in which the language-specific - * and render-system-specific components are provided by loadable - * modules. - * - * This is no longer the case, and all the APIs related - * to modules and engines should not be used anymore. - * - * Deprecated: 1.38 - */ -/** - * SECTION:pango-engine-lang - * @short_description:Rendering-system independent script engines - * @title:PangoEngineLang - * @stability:Unstable - * - * The <firstterm>language engines</firstterm> are rendering-system independent - * engines that determine line, word, and character breaks for character strings. - * These engines are used in pango_break(). - * - * Deprecated: 1.38 - */ -/** - * SECTION:pango-engine-shape - * @short_description:Rendering-system dependent script engines - * @title:PangoEngineShape - * @stability:Unstable - * - * The <firstterm>shape engines</firstterm> are rendering-system dependent - * engines that convert character strings into glyph strings. - * These engines are used in pango_shape(). - * - * Deprecated: 1.38 - */ #include "config.h" #include "pango-engine.h" diff --git a/pango/pango-engine.h b/pango/pango-engine.h index 25cfd6ba..16b39c3f 100644 --- a/pango/pango-engine.h +++ b/pango/pango-engine.h @@ -30,6 +30,11 @@ G_BEGIN_DECLS +/* All of this is deprecated and entirely useless for bindings. + * Leave it out of the gir file. + */ +#ifndef __GI_SCANNER__ + #ifndef PANGO_DISABLE_DEPRECATED /** @@ -196,7 +201,7 @@ struct _PangoEngineShape * appropriately using pango_glyph_string_set_size()). All fields * of the @log_clusters and @glyphs array must be filled in, with * the exception that Pango will automatically generate - * <literal>glyphs->glyphs[i].attr.is_cluster_start</literal> + * `glyphs->glyphs[i].attr.is_cluster_start` * using the @log_clusters array. Each input character must occur in one * of the output logical clusters; * if no rendering is desired for a character, this may involve @@ -287,11 +292,6 @@ struct _PangoEngineInfo gint n_scripts; }; -/* We should to ignore these unprefixed symbols when going through - * this header with the introspection scanner - */ -#ifndef __GI_SCANNER__ - /** * script_engine_list: (skip) * @engines: location to store a pointer to an array of engines. @@ -368,8 +368,8 @@ prefix ## _register_type (GTypeModule *module) \ /** * PANGO_ENGINE_LANG_DEFINE_TYPE: - * @name: Name of the the type to register (for example:, <literal>ArabicEngineFc</literal> - * @prefix: Prefix for symbols that will be defined (for example:, <literal>arabic_engine_fc</literal> + * @name: Name of the the type to register (for example:, ArabicEngineFc) + * @prefix: Prefix for symbols that will be defined (for example:, arabic_engine_fc) * @class_init: (nullable): Class initialization function for the new type, or %NULL * @instance_init: (nullable): Instance initialization function for the new type, or %NULL * @@ -378,18 +378,17 @@ prefix ## _register_type (GTypeModule *module) \ * are defined. * * <programlisting> - * static GType <replaceable>prefix</replaceable>_type; - * static void <replaceable>prefix</replaceable>_register_type (GTypeModule module); - * </programlisting> + * static GType *prefix*_type; + * static void *prefix*_register_type (GTypeModule module); * - * The <function><replaceable>prefix</replaceable>_register_type()</function> + * The *prefix*_register_type() * function should be called in your script_engine_init() function for * each type that your module implements, and then your script_engine_create() * function can create instances of the object as follows: * - * <informalexample><programlisting> - * PangoEngine *engine = g_object_new (<replaceable>prefix</replaceable>_type, NULL); - * </programlisting></informalexample> + * ``` + * PangoEngine *engine = g_object_new (prefix_type, NULL); + * ``` * * Deprecated: 1.38 **/ @@ -400,8 +399,8 @@ prefix ## _register_type (GTypeModule *module) \ /** * PANGO_ENGINE_SHAPE_DEFINE_TYPE: - * @name: Name of the the type to register (for example:, <literal>ArabicEngineFc</literal> - * @prefix: Prefix for symbols that will be defined (for example:, <literal>arabic_engine_fc</literal> + * @name: Name of the the type to register (for example:, ArabicEngineFc) + * @prefix: Prefix for symbols that will be defined (for example:, arabic_engine_fc) * @class_init: (nullable): Class initialization function for the new type, or %NULL * @instance_init: (nullable): Instance initialization function for the new type, or %NULL * @@ -410,18 +409,18 @@ prefix ## _register_type (GTypeModule *module) \ * are defined. * * <programlisting> - * static GType <replaceable>prefix</replaceable>_type; - * static void <replaceable>prefix</replaceable>_register_type (GTypeModule module); + * static GType *prefix*_type; + * static void *prefix*_register_type (GTypeModule module); * </programlisting> * - * The <function><replaceable>prefix</replaceable>_register_type()</function> + * The *prefix*_register_type() * function should be called in your script_engine_init() function for * each type that your module implements, and then your script_engine_create() * function can create instances of the object as follows: * - * <informalexample><programlisting> - * PangoEngine *engine = g_object_new (<replaceable>prefix</replaceable>_type, NULL); - * </programlisting></informalexample> + * ``` + * PangoEngine *engine = g_object_new (prefix_type, NULL); + * ``` * * Deprecated: 1.38 **/ diff --git a/pango/pango-font.h b/pango/pango-font.h index ba1ea3ae..13f8a222 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,20 +33,25 @@ G_BEGIN_DECLS /** * PangoFontDescription: * - * 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. + * A `PangoFontDescription` describes a font in an implementation-independent + * manner. + * + * `PangoFontDescription` structures are used both to list what fonts are + * available on the system and also for specifying the characteristics of + * a font to load. */ typedef struct _PangoFontDescription PangoFontDescription; + /** * PangoFontMetrics: * - * 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 - * of their meaning. + * A `PangoFontMetrics` structure holds the overall metric information + * for a font. + * + * The information in a `PangoFontMetrics` structure may be 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 of their meaning. */ typedef struct _PangoFontMetrics PangoFontMetrics; @@ -92,8 +97,10 @@ typedef enum { * @PANGO_WEIGHT_HEAVY: the heavy weight (= 900) * @PANGO_WEIGHT_ULTRAHEAVY: the ultraheavy weight (= 1000; Since: 1.24) * - * An enumeration specifying the weight (boldness) of a font. This is a numerical - * value ranging from 100 to 1000, but there are some predefined values: + * An enumeration specifying the weight (boldness) of a font. + * + * This is a numerical value ranging from 100 to 1000, but there + * are some predefined values. */ typedef enum { PANGO_WEIGHT_THIN = 100, @@ -148,8 +155,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 the set fields in a + * `PangoFontDescription`. */ typedef enum { PANGO_FONT_MASK_FAMILY = 1 << 0, @@ -210,11 +217,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 +231,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 +295,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 +322,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 +370,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,9 +386,11 @@ typedef struct _PangoFontFamilyClass PangoFontFamilyClass; /** * PangoFontFamily: * - * 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. + * A `PangoFontFamily` is used to represent a family of related + * font faces. + * + * The font faces in a family share a common design, but differ in + * slant, weight, width or other aspects. */ struct _PangoFontFamily { @@ -445,8 +427,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 +445,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,8 +459,8 @@ typedef struct _PangoFontFaceClass PangoFontFaceClass; /** * PangoFontFace: * - * The #PangoFontFace structure is used to represent a group of fonts with - * the same family, slant, weight, width, but varying sizes. + * A `PangoFontFace` is used to represent a group of fonts with + * the same family, slant, weight, and width, but varying sizes. */ struct _PangoFontFace { @@ -534,8 +499,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 +512,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 +525,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 <structfield>klass</structfield> 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. + * A `PangoFont` is used to represent a font in a + * rendering-system-independent manner. */ struct _PangoFont { @@ -631,19 +569,21 @@ 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); +#ifndef __GI_SCANNER__ PANGO_DEPRECATED_IN_1_44 PangoEngineShape * pango_font_find_shaper (PangoFont *font, - PangoLanguage *language, - guint32 ch); + PangoLanguage *language, + guint32 ch); +#endif 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,50 +604,54 @@ 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 - * example in shaper modules, to use as the glyph for various zero-width - * Unicode characters (those passing pango_is_zero_width()). + * A `PangoGlyph` value that indicates a zero-width empty glpyh. + * + * This is useful for example in shaper modules, to use as the glyph for + * various 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 - * per invalid input UTF-8 byte and such a glyph is rendered as a crossed - * box. + * A `PangoGlyph` value for invalid input. + * + * `PangoLayout` produces one such glyph per invalid input UTF-8 byte and such + * a glyph is rendered as a crossed box. * * Note that this value is defined such that it has the %PANGO_GLYPH_UNKNOWN_FLAG - * on. + * set. * * Since: 1.20 */ /** * 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. + * Flag used in `PangoGlyph` to turn a `gunichar` value of a valid Unicode + * character into an unknown-character glyph for that `gunichar`. + * + * Such unknown-character glyphs may be rendered as a 'hex box'. */ /** * 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) #define PANGO_GLYPH_UNKNOWN_FLAG ((PangoGlyph)0x10000000) #define PANGO_GET_UNKNOWN_GLYPH(wc) ((PangoGlyph)(wc)|PANGO_GLYPH_UNKNOWN_FLAG) +#ifndef __GI_SCANNER__ #ifndef PANGO_DISABLE_DEPRECATED #define PANGO_UNKNOWN_GLYPH_WIDTH 10 #define PANGO_UNKNOWN_GLYPH_HEIGHT 14 #endif +#endif G_END_DECLS diff --git a/pango/pango-fontmap.c b/pango/pango-fontmap.c index d4cdefa6..bc18a7da 100644 --- a/pango/pango-fontmap.c +++ b/pango/pango-fontmap.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 @@ -29,9 +29,9 @@ #include <stdlib.h> static PangoFontset *pango_font_map_real_load_fontset (PangoFontMap *fontmap, - PangoContext *context, - const PangoFontDescription *desc, - PangoLanguage *language); + PangoContext *context, + const PangoFontDescription *desc, + PangoLanguage *language); static PangoFontFamily *pango_font_map_real_get_family (PangoFontMap *fontmap, @@ -64,21 +64,23 @@ pango_font_map_init (PangoFontMap *fontmap G_GNUC_UNUSED) /** * pango_font_map_create_context: - * @fontmap: a #PangoFontMap + * @fontmap: a `PangoFontMap` * - * Creates a #PangoContext connected to @fontmap. This is equivalent - * to pango_context_new() followed by pango_context_set_font_map(). + * Creates a `PangoContext` connected to @fontmap. + * + * This is equivalent to [ctor@Pango.Context.new] followed by + * [method@Pango.Context.set_font_map]. * * If you are using Pango as part of a higher-level system, - * that system may have it's own way of create a #PangoContext. - * For instance, the GTK+ toolkit has, among others, + * that system may have it's own way of create a `PangoContext`. + * For instance, the GTK toolkit has, among others, * gtk_widget_get_pango_context(). Use those instead. * - * Return value: (transfer full): the newly allocated #PangoContext, - * which should be freed with g_object_unref(). + * Return value: (transfer full): the newly allocated `PangoContext`, + * which should be freed with g_object_unref(). * * Since: 1.22 - **/ + */ PangoContext * pango_font_map_create_context (PangoFontMap *fontmap) { @@ -94,19 +96,19 @@ pango_font_map_create_context (PangoFontMap *fontmap) /** * pango_font_map_load_font: - * @fontmap: a #PangoFontMap - * @context: the #PangoContext the font will be used with - * @desc: a #PangoFontDescription describing the font to load + * @fontmap: a `PangoFontMap` + * @context: the `PangoContext` the font will be used with + * @desc: a `PangoFontDescription` describing the font to load * * Load the font in the fontmap that is the closest match for @desc. * - * Returns: (transfer full) (nullable): the newly allocated #PangoFont - * loaded, or %NULL if no font matched. - **/ + * Returns: (transfer full) (nullable): the newly allocated `PangoFont` + * loaded, or %NULL if no font matched. + */ PangoFont * pango_font_map_load_font (PangoFontMap *fontmap, - PangoContext *context, - const PangoFontDescription *desc) + PangoContext *context, + const PangoFontDescription *desc) { g_return_val_if_fail (fontmap != NULL, NULL); @@ -115,45 +117,45 @@ pango_font_map_load_font (PangoFontMap *fontmap, /** * pango_font_map_list_families: - * @fontmap: a #PangoFontMap - * @families: (out) (array length=n_families) (transfer container): location to store a pointer to an array of #PangoFontFamily *. + * @fontmap: a `PangoFontMap` + * @families: (out) (array length=n_families) (transfer container): location to store a pointer to an array of `PangoFontFamily` *. * This array should be freed with g_free(). * @n_families: (out): location to store the number of elements in @families * * List all families for a fontmap. - **/ + */ void pango_font_map_list_families (PangoFontMap *fontmap, - PangoFontFamily ***families, - int *n_families) + PangoFontFamily ***families, + int *n_families) { PangoFontMapPrivate *priv = pango_font_map_get_instance_private (fontmap); g_return_if_fail (fontmap != NULL); PANGO_FONT_MAP_GET_CLASS (fontmap)->list_families (fontmap, families, n_families); - + /* keep this value for GListModel::changed */ priv->n_families = *n_families; } /** * pango_font_map_load_fontset: - * @fontmap: a #PangoFontMap - * @context: the #PangoContext the font will be used with - * @desc: a #PangoFontDescription describing the font to load - * @language: a #PangoLanguage the fonts will be used for + * @fontmap: a `PangoFontMap` + * @context: the `PangoContext` the font will be used with + * @desc: a `PangoFontDescription` describing the font to load + * @language: a `PangoLanguage` the fonts will be used for * * Load a set of fonts in the fontmap that can be used to render * a font matching @desc. * * Returns: (transfer full) (nullable): the newly allocated - * #PangoFontset loaded, or %NULL if no font matched. - **/ + * `PangoFontset` loaded, or %NULL if no font matched. + */ PangoFontset * -pango_font_map_load_fontset (PangoFontMap *fontmap, - PangoContext *context, - const PangoFontDescription *desc, - PangoLanguage *language) +pango_font_map_load_fontset (PangoFontMap *fontmap, + PangoContext *context, + const PangoFontDescription *desc, + PangoLanguage *language) { g_return_val_if_fail (fontmap != NULL, NULL); @@ -162,10 +164,10 @@ pango_font_map_load_fontset (PangoFontMap *fontmap, static void pango_font_map_fontset_add_fonts (PangoFontMap *fontmap, - PangoContext *context, - PangoFontsetSimple *fonts, - PangoFontDescription *desc, - const char *family) + PangoContext *context, + PangoFontsetSimple *fonts, + PangoFontDescription *desc, + const char *family) { PangoFont *font; @@ -177,9 +179,9 @@ pango_font_map_fontset_add_fonts (PangoFontMap *fontmap, static PangoFontset * pango_font_map_real_load_fontset (PangoFontMap *fontmap, - PangoContext *context, - const PangoFontDescription *desc, - PangoLanguage *language) + PangoContext *context, + const PangoFontDescription *desc, + PangoLanguage *language) { PangoFontDescription *tmp_desc = pango_font_description_copy_static (desc); const char *family; @@ -196,10 +198,10 @@ pango_font_map_real_load_fontset (PangoFontMap *fontmap, for (i = 0; families[i]; i++) pango_font_map_fontset_add_fonts (fontmap, - context, - fonts, - tmp_desc, - families[i]); + context, + fonts, + tmp_desc, + families[i]); g_strfreev (families); @@ -211,32 +213,32 @@ pango_font_map_real_load_fontset (PangoFontMap *fontmap, char *ctmp1, *ctmp2; pango_font_description_set_family_static (tmp_desc, - pango_font_description_get_family (desc)); + pango_font_description_get_family (desc)); ctmp1 = pango_font_description_to_string (desc); pango_font_description_set_family_static (tmp_desc, "Sans"); G_LOCK (warned_fonts); if (!warned_fonts || !g_hash_table_lookup (warned_fonts, ctmp1)) - { - if (!warned_fonts) - warned_fonts = g_hash_table_new (g_str_hash, g_str_equal); + { + if (!warned_fonts) + warned_fonts = g_hash_table_new (g_str_hash, g_str_equal); - g_hash_table_insert (warned_fonts, g_strdup (ctmp1), GINT_TO_POINTER (1)); + g_hash_table_insert (warned_fonts, g_strdup (ctmp1), GINT_TO_POINTER (1)); - ctmp2 = pango_font_description_to_string (tmp_desc); - g_warning ("couldn't load font \"%s\", falling back to \"%s\", " - "expect ugly output.", ctmp1, ctmp2); - g_free (ctmp2); - } + ctmp2 = pango_font_description_to_string (tmp_desc); + g_warning ("couldn't load font \"%s\", falling back to \"%s\", " + "expect ugly output.", ctmp1, ctmp2); + g_free (ctmp2); + } G_UNLOCK (warned_fonts); g_free (ctmp1); pango_font_map_fontset_add_fonts (fontmap, - context, - fonts, - tmp_desc, - "Sans"); + context, + fonts, + tmp_desc, + "Sans"); } /* We couldn't try with Sans and the specified style. Try Sans Normal @@ -254,23 +256,23 @@ pango_font_map_real_load_fontset (PangoFontMap *fontmap, G_LOCK (warned_fonts); if (!warned_fonts || !g_hash_table_lookup (warned_fonts, ctmp1)) - { - g_hash_table_insert (warned_fonts, g_strdup (ctmp1), GINT_TO_POINTER (1)); + { + g_hash_table_insert (warned_fonts, g_strdup (ctmp1), GINT_TO_POINTER (1)); - ctmp2 = pango_font_description_to_string (tmp_desc); + ctmp2 = pango_font_description_to_string (tmp_desc); - g_warning ("couldn't load font \"%s\", falling back to \"%s\", " - "expect ugly output.", ctmp1, ctmp2); - g_free (ctmp2); - } + g_warning ("couldn't load font \"%s\", falling back to \"%s\", " + "expect ugly output.", ctmp1, ctmp2); + g_free (ctmp2); + } G_UNLOCK (warned_fonts); g_free (ctmp1); pango_font_map_fontset_add_fonts (fontmap, - context, - fonts, - tmp_desc, - "Sans"); + context, + fonts, + tmp_desc, + "Sans"); } pango_font_description_free (tmp_desc); @@ -286,19 +288,17 @@ pango_font_map_real_load_fontset (PangoFontMap *fontmap, /** * pango_font_map_get_shape_engine_type: - * @fontmap: a #PangoFontMap + * @fontmap: a `PangoFontMap` * * Returns the render ID for shape engines for this fontmap. - * See the <structfield>render_type</structfield> field of - * #PangoEngineInfo. + * See the `render_type` field of #PangoEngineInfo. * - * Return value: the ID string for shape engines for - * this fontmap. Owned by Pango, should not be modified - * or freed. + * Return value: the ID string for shape engines for this fontmap. + * Owned by Pango, should not be modified or freed. * * Since: 1.4 * Deprecated: 1.38 - **/ + */ const char * pango_font_map_get_shape_engine_type (PangoFontMap *fontmap) { @@ -309,24 +309,25 @@ pango_font_map_get_shape_engine_type (PangoFontMap *fontmap) /** * pango_font_map_get_serial: - * @fontmap: a #PangoFontMap + * @fontmap: a `PangoFontMap` * - * Returns the current serial number of @fontmap. The serial number is - * initialized to an small number larger than zero when a new fontmap - * is created and is increased whenever the fontmap is changed. It may - * wrap, but will never have the value 0. Since it can wrap, never compare - * it with "less than", always use "not equals". + * Returns the current serial number of @fontmap. + * + * The serial number is initialized to an small number larger than zero + * when a new fontmap is created and is increased whenever the fontmap + * is changed. It may wrap, but will never have the value 0. Since it can + * wrap, never compare it with "less than", always use "not equals". * * The fontmap can only be changed using backend-specific API, like changing * fontmap resolution. * - * This can be used to automatically detect changes to a #PangoFontMap, like - * in #PangoContext. + * This can be used to automatically detect changes to a `PangoFontMap`, + * like in `PangoContext`. * * Return value: The current serial number of @fontmap. * * Since: 1.32.4 - **/ + */ guint pango_font_map_get_serial (PangoFontMap *fontmap) { @@ -347,23 +348,23 @@ pango_font_map_real_changed (PangoFontMap *fontmap) removed = priv->n_families; added = g_list_model_get_n_items (G_LIST_MODEL (fontmap)); - g_list_model_items_changed (G_LIST_MODEL (fontmap), 0, removed, added); + g_list_model_items_changed (G_LIST_MODEL (fontmap), 0, removed, added); } /** * pango_font_map_changed: - * @fontmap: a #PangoFontMap + * @fontmap: a `PangoFontMap` * - * Forces a change in the context, which will cause any #PangoContext + * Forces a change in the context, which will cause any `PangoContext` * using this fontmap to change. * * This function is only useful when implementing a new backend * for Pango, something applications won't do. Backends should - * call this function if they have attached extra data to the context - * and such data is changed. + * call this function if they have attached extra data to the + * context and such data is changed. * * Since: 1.34 - **/ + */ void pango_font_map_changed (PangoFontMap *fontmap) { @@ -402,12 +403,12 @@ pango_font_map_real_get_family (PangoFontMap *fontmap, /** * pango_font_map_get_family: - * @fontmap: a #PangoFontMap + * @fontmap: a `PangoFontMap` * @name: a family name * * Gets a font family by name. * - * Returns: (transfer none): the #PangoFontFamily + * Returns: (transfer none): the `PangoFontFamily` * * Since: 1.46 */ diff --git a/pango/pango-fontmap.h b/pango/pango-fontmap.h index f30780ee..64b04da3 100644 --- a/pango/pango-fontmap.h +++ b/pango/pango-fontmap.h @@ -57,17 +57,11 @@ typedef struct _PangoContext PangoContext; /** * PangoFontMap: * - * The #PangoFontMap represents the set of fonts available for a - * particular rendering system. This is a virtual object with - * implementations being specific to particular rendering systems. To - * create an implementation of a #PangoFontMap, the rendering-system - * specific code should allocate a larger structure that contains a nested - * #PangoFontMap, fill in the <structfield>klass</structfield> member of the nested #PangoFontMap with a - * pointer to a appropriate #PangoFontMapClass, then call - * pango_font_map_init() on the structure. + * A `PangoFontMap` represents the set of fonts available for a + * particular rendering system. * - * The #PangoFontMap structure contains one member which the implementation - * fills in. + * This is a virtual object with implementations being specific to + * particular rendering systems. */ struct _PangoFontMap { diff --git a/pango/pango-fontset.c b/pango/pango-fontset.c index 6a3ef4c6..6f3bdcbf 100644 --- a/pango/pango-fontset.c +++ b/pango/pango-fontset.c @@ -49,14 +49,14 @@ pango_fontset_class_init (PangoFontsetClass *class) /** * pango_fontset_get_font: - * @fontset: a #PangoFontset + * @fontset: a `PangoFontset` * @wc: a Unicode character * - * Returns the font in the fontset that contains the best glyph for the - * Unicode character @wc. + * Returns the font in the fontset that contains the best glyph for a + * Unicode character. * - * Return value: (transfer full): a #PangoFont. The caller must call - * g_object_unref when finished with the font. + * Return value: (transfer full): a `PangoFont`. The caller must call + * g_object_unref() when finished with the font. **/ PangoFont * pango_fontset_get_font (PangoFontset *fontset, @@ -87,12 +87,14 @@ pango_fontset_get_metrics (PangoFontset *fontset) /** * pango_fontset_foreach: - * @fontset: a #PangoFontset + * @fontset: a `PangoFontset` * @func: (closure data) (scope call): Callback function * @data: (closure): data to pass to the callback function * * Iterates through all the fonts in a fontset, calling @func for - * each one. If @func returns %TRUE, that stops the iteration. + * each one. + * + * If @func returns %TRUE, that stops the iteration. * * Since: 1.4 **/ @@ -232,11 +234,11 @@ struct _PangoFontsetSimpleClass /** * pango_fontset_simple_new: - * @language: a #PangoLanguage tag + * @language: a `PangoLanguage` tag * - * Creates a new #PangoFontsetSimple for the given language. + * Creates a new `PangoFontsetSimple` for the given language. * - * Return value: the newly allocated #PangoFontsetSimple, which should + * Return value: the newly allocated `PangoFontsetSimple`, which should * be freed with g_object_unref(). **/ PangoFontsetSimple * @@ -301,8 +303,8 @@ pango_fontset_simple_finalize (GObject *object) /** * pango_fontset_simple_append: - * @fontset: a #PangoFontsetSimple. - * @font: a #PangoFont. + * @fontset: a `PangoFontsetSimple`. + * @font: a `PangoFont`. * * Adds a font to the fontset. **/ @@ -316,7 +318,7 @@ pango_fontset_simple_append (PangoFontsetSimple *fontset, /** * pango_fontset_simple_size: - * @fontset: a #PangoFontsetSimple. + * @fontset: a `PangoFontsetSimple`. * * Returns the number of fonts in the fontset. * diff --git a/pango/pango-fontset.h b/pango/pango-fontset.h index ce7d4107..2b2018dd 100644 --- a/pango/pango-fontset.h +++ b/pango/pango-fontset.h @@ -54,12 +54,12 @@ typedef struct _PangoFontsetClass PangoFontsetClass; /** * PangoFontsetForeachFunc: - * @fontset: a #PangoFontset + * @fontset: a `PangoFontset` * @font: a font from @fontset * @user_data: callback data * - * A callback function used by pango_fontset_foreach() when enumerating - * the fonts in a fontset. + * Callback used by pango_fontset_foreach() when enumerating + * fonts in a fontset. * * Returns: if %TRUE, stop iteration and return immediately. * @@ -72,12 +72,12 @@ typedef gboolean (*PangoFontsetForeachFunc) (PangoFontset *fontset, /** * PangoFontset: * - * A #PangoFontset represents a set of #PangoFont to use - * when rendering text. It is the result of resolving a - * #PangoFontDescription against a particular #PangoContext. - * It has operations for finding the component font for - * a particular Unicode character, and for finding a composite - * set of metrics for the entire fontset. + * A `PangoFontset` represents a set of `PangoFont` to use when rendering text. + * + * A `PAngoFontset` is the result of resolving a `PangoFontDescription` + * against a particular `PangoContext`. It has operations for finding the + * component font for a particular Unicode character, and for finding a + * composite set of metrics for the entire fontset. */ struct _PangoFontset { @@ -130,10 +130,11 @@ struct _PangoFontsetClass /** * PangoFontsetSimple: * - * #PangoFontsetSimple is a implementation of the abstract - * #PangoFontset base class in terms of an array of fonts, - * which the creator provides when constructing the - * #PangoFontsetSimple. + * `PangoFontsetSimple` is a implementation of the abstract + * `PangoFontset` base class as an array of fonts. + * + * When creating a `PangoFontsetSimple`, you have to provide + * the array of fonts that make up the fontset. */ #define PANGO_TYPE_FONTSET_SIMPLE (pango_fontset_simple_get_type ()) #define PANGO_FONTSET_SIMPLE(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONTSET_SIMPLE, PangoFontsetSimple)) diff --git a/pango/pango-glyph-item.c b/pango/pango-glyph-item.c index 326ae37f..8cca8627 100644 --- a/pango/pango-glyph-item.c +++ b/pango/pango-glyph-item.c @@ -30,13 +30,15 @@ /** * pango_glyph_item_split: - * @orig: a #PangoItem + * @orig: a `PangoItem` * @text: text to which positions in @orig apply * @split_index: byte index of position to split item, relative to the start of the item * * Modifies @orig to cover only the text after @split_index, and * returns a new item that covers the text before @split_index that - * used to be in @orig. You can think of @split_index as the length of + * used to be in @orig. + * + * You can think of @split_index as the length of * the returned item. @split_index may not be 0, and it may not be * greater than or equal to the length of @orig (that is, there must * be at least one byte assigned to each item, you can't create a @@ -132,11 +134,11 @@ pango_glyph_item_split (PangoGlyphItem *orig, /** * pango_glyph_item_copy: - * @orig: (nullable): a #PangoGlyphItem, may be %NULL + * @orig: (nullable): a `PangoGlyphItem`, may be %NULL * - * Make a deep copy of an existing #PangoGlyphItem structure. + * Make a deep copy of an existing `PangoGlyphItem` structure. * - * Return value: (nullable): the newly allocated #PangoGlyphItem, which should + * Return value: (nullable): the newly allocated `PangoGlyphItem`, which should * be freed with pango_glyph_item_free(), or %NULL * if @orig was %NULL. * @@ -160,9 +162,9 @@ pango_glyph_item_copy (PangoGlyphItem *orig) /** * pango_glyph_item_free: - * @glyph_item: (nullable): a #PangoGlyphItem, may be %NULL + * @glyph_item: (nullable): a `PangoGlyphItem`, may be %NULL * - * Frees a #PangoGlyphItem and resources to which it points. + * Frees a `PangoGlyphItem` and resources to which it points. * * Since: 1.6 **/ @@ -187,13 +189,13 @@ G_DEFINE_BOXED_TYPE (PangoGlyphItem, pango_glyph_item, /** * pango_glyph_item_iter_copy: - * @orig: (nullable): a #PangoGlyphItemIter, may be %NULL + * @orig: (nullable): a `PangoGlyphItem`Iter, may be %NULL * - * Make a shallow copy of an existing #PangoGlyphItemIter structure. + * Make a shallow copy of an existing `PangoGlyphItemIter` structure. * - * Return value: (nullable): the newly allocated #PangoGlyphItemIter, which should - * be freed with pango_glyph_item_iter_free(), or %NULL - * if @orig was %NULL. + * Return value: (nullable): the newly allocated `PangoGlyphItemIter`, + * which should be freed with pango_glyph_item_iter_free(), or %NULL + * if @orig was %NULL. * * Since: 1.22 **/ @@ -214,9 +216,9 @@ pango_glyph_item_iter_copy (PangoGlyphItemIter *orig) /** * pango_glyph_item_iter_free: - * @iter: (nullable): a #PangoGlyphItemIter, may be %NULL + * @iter: (nullable): a `PangoGlyphItemIter`, may be %NULL * - * Frees a #PangoGlyphItemIter created by pango_glyph_item_iter_copy(). + * Frees a `PangoGlyphItem`Iter. * * Since: 1.22 **/ @@ -235,13 +237,14 @@ G_DEFINE_BOXED_TYPE (PangoGlyphItemIter, pango_glyph_item_iter, /** * pango_glyph_item_iter_next_cluster: - * @iter: a #PangoGlyphItemIter + * @iter: a `PangoGlyphItemIter` * * Advances the iterator to the next cluster in the glyph item. - * See #PangoGlyphItemIter for details of cluster orders. * - * Return value: %TRUE if the iterator was advanced, %FALSE if we were already on the - * last cluster. + * See `PangoGlyphItemIter` for details of cluster orders. + * + * Return value: %TRUE if the iterator was advanced, + * %FALSE if we were already on the last cluster. * * Since: 1.22 **/ @@ -325,13 +328,13 @@ pango_glyph_item_iter_next_cluster (PangoGlyphItemIter *iter) /** * pango_glyph_item_iter_prev_cluster: - * @iter: a #PangoGlyphItemIter + * @iter: a `PangoGlyphItemIter` * * Moves the iterator to the preceding cluster in the glyph item. - * See #PangoGlyphItemIter for details of cluster orders. + * See `PangoGlyphItemIter` for details of cluster orders. * - * Return value: %TRUE if the iterator was moved, %FALSE if we were already on the - * first cluster. + * Return value: %TRUE if the iterator was moved, + * %FALSE if we were already on the first cluster. * * Since: 1.22 **/ @@ -418,13 +421,14 @@ pango_glyph_item_iter_prev_cluster (PangoGlyphItemIter *iter) /** * pango_glyph_item_iter_init_start: - * @iter: a #PangoGlyphItemIter + * @iter: a `PangoGlyphItemIter` * @glyph_item: the glyph item to iterate over * @text: text corresponding to the glyph item * - * Initializes a #PangoGlyphItemIter structure to point to the + * Initializes a `PangoGlyphItemIter` structure to point to the * first cluster in a glyph item. - * See #PangoGlyphItemIter for details of cluster orders. + * + * See `PangoGlyphItemIter` for details of cluster orders. * * Return value: %FALSE if there are no clusters in the glyph item * @@ -456,13 +460,14 @@ pango_glyph_item_iter_init_start (PangoGlyphItemIter *iter, /** * pango_glyph_item_iter_init_end: - * @iter: a #PangoGlyphItemIter + * @iter: a `PangoGlyphItemIter` * @glyph_item: the glyph item to iterate over * @text: text corresponding to the glyph item * - * Initializes a #PangoGlyphItemIter structure to point to the + * Initializes a `PangoGlyphItemIter` structure to point to the * last cluster in a glyph item. - * See #PangoGlyphItemIter for details of cluster orders. + * + * See `PangoGlyphItemIter` for details of cluster orders. * * Return value: %FALSE if there are no clusters in the glyph item * @@ -554,12 +559,14 @@ split_before_cluster_start (ApplyAttrsState *state) * pango_glyph_item_apply_attrs: * @glyph_item: a shaped item * @text: text that @list applies to - * @list: a #PangoAttrList + * @list: a `PangoAttrList` * - * Splits a shaped item (PangoGlyphItem) into multiple items based - * on an attribute list. The idea is that if you have attributes + * Splits a shaped item (`PangoGlyphItem`) into multiple items based + * on an attribute list. + * + * The idea is that if you have attributes * that don't affect shaping, such as color or underline, to avoid - * affecting shaping, you filter them out (pango_attr_list_filter()), + * affecting shaping, you filter them out ([method@Pango.AttrList.filter]), * apply the shaping process and then reapply them to the result using * this function. * @@ -567,7 +574,7 @@ split_before_cluster_start (ApplyAttrsState *state) * to that cluster; for instance, if half of a cluster is underlined * and the other-half strikethrough, then the cluster will end * up with both underline and strikethrough attributes. In these - * cases, it may happen that item->extra_attrs for some of the + * cases, it may happen that @item->extra_attrs for some of the * result items can have multiple attributes of the same type. * * This function takes ownership of @glyph_item; it will be reused @@ -575,7 +582,7 @@ split_before_cluster_start (ApplyAttrsState *state) * * Return value: (transfer full) (element-type Pango.GlyphItem): a * list of glyph items resulting from splitting @glyph_item. Free - * the elements using pango_glyph_item_free(), the list using + * the elements using [method@Pango.GlyphItem.free], the list using * g_slist_free(). * * Since: 1.2 @@ -711,7 +718,7 @@ pango_glyph_item_apply_attrs (PangoGlyphItem *glyph_item, /** * pango_glyph_item_letter_space: - * @glyph_item: a #PangoGlyphItem + * @glyph_item: a `PangoGlyphItem` * @text: text that @glyph_item corresponds to * (glyph_item->item->offset is an offset from the * start of @text) @@ -726,7 +733,7 @@ pango_glyph_item_apply_attrs (PangoGlyphItem *glyph_item, * give the effect of typographic letter spacing. * * Since: 1.6 - **/ + */ void pango_glyph_item_letter_space (PangoGlyphItem *glyph_item, const char *text, @@ -784,7 +791,7 @@ pango_glyph_item_letter_space (PangoGlyphItem *glyph_item, /** * pango_glyph_item_get_logical_widths: - * @glyph_item: a #PangoGlyphItem + * @glyph_item: a `PangoGlyphItem` * @text: text that @glyph_item corresponds to * (glyph_item->item->offset is an offset from the * start of @text) @@ -793,12 +800,13 @@ pango_glyph_item_letter_space (PangoGlyphItem *glyph_item, * glyph_item->item->num_chars) to be filled in with * the resulting character widths. * - * Given a #PangoGlyphItem and the corresponding - * text, determine the screen width corresponding to each character. When - * multiple characters compose a single cluster, the width of the entire + * Given a `PangoGlyphItem` and the corresponding text, determine the width + * corresponding to each character. + * + * When multiple characters compose a single cluster, the width of the entire * cluster is divided equally among the characters. * - * See also pango_glyph_string_get_logical_widths(). + * See also [method@Pango.GlyphString.get_logical_widths]. * * Since: 1.26 **/ diff --git a/pango/pango-glyph-item.h b/pango/pango-glyph-item.h index daf2b15f..8a1dbff4 100644 --- a/pango/pango-glyph-item.h +++ b/pango/pango-glyph-item.h @@ -31,14 +31,15 @@ G_BEGIN_DECLS /** * PangoGlyphItem: - * @item: corresponding #PangoItem. - * @glyphs: corresponding #PangoGlyphString. - * - * A #PangoGlyphItem is a pair of a #PangoItem and the glyphs - * resulting from shaping the text corresponding to an item. - * As an example of the usage of #PangoGlyphItem, the results - * of shaping text with #PangoLayout is a list of #PangoLayoutLine, - * each of which contains a list of #PangoGlyphItem. + * @item: corresponding `PangoItem` + * @glyphs: corresponding `PangoGlyphString` + * + * A `PangoGlyphItem` is a pair of a `PangoItem` and the glyphs + * resulting from shaping the items text. + * + * As an example of the usage of `PangoGlyphItem`, the results + * of shaping text with `PangoLayout` is a list of `PangoLayoutLine`, + * each of which contains a list of `PangoGlyphItem`. */ typedef struct _PangoGlyphItem PangoGlyphItem; @@ -84,43 +85,46 @@ void pango_glyph_item_get_logical_widths (PangoGlyphItem *glyph_item, /** * PangoGlyphItemIter: * - * A #PangoGlyphItemIter is an iterator over the clusters in a - * #PangoGlyphItem. The <firstterm>forward direction</firstterm> of the - * iterator is the logical direction of text. That is, with increasing - * @start_index and @start_char values. If @glyph_item is right-to-left - * (that is, if <literal>@glyph_item->item->analysis.level</literal> is odd), + * A `PangoGlyphItemIter` is an iterator over the clusters in a + * `PangoGlyphItem`. + * + * The *forward direction* of the iterator is the logical direction of text. + * That is, with increasing @start_index and @start_char values. If @glyph_item + * is right-to-left (that is, if `glyph_item->item->analysis.level` is odd), * then @start_glyph decreases as the iterator moves forward. Moreover, * in right-to-left cases, @start_glyph is greater than @end_glyph. * - * An iterator should be initialized using either of - * pango_glyph_item_iter_init_start() and + * An iterator should be initialized using either + * pango_glyph_item_iter_init_start() or * pango_glyph_item_iter_init_end(), for forward and backward iteration * respectively, and walked over using any desired mixture of * pango_glyph_item_iter_next_cluster() and - * pango_glyph_item_iter_prev_cluster(). A common idiom for doing a - * forward iteration over the clusters is: - * <programlisting> + * pango_glyph_item_iter_prev_cluster(). + * + * A common idiom for doing a forward iteration over the clusters is: + * + * ``` * PangoGlyphItemIter cluster_iter; * gboolean have_cluster; * - * for (have_cluster = pango_glyph_item_iter_init_start (&cluster_iter, + * for (have_cluster = pango_glyph_item_iter_init_start (&cluster_iter, * glyph_item, text); * have_cluster; - * have_cluster = pango_glyph_item_iter_next_cluster (&cluster_iter)) + * have_cluster = pango_glyph_item_iter_next_cluster (&cluster_iter)) * { * ... * } - * </programlisting> + * ``` * * Note that @text is the start of the text for layout, which is then - * indexed by <literal>@glyph_item->item->offset</literal> to get to the - * text of @glyph_item. The @start_index and @end_index values can directly - * index into @text. The @start_glyph, @end_glyph, @start_char, and @end_char - * values however are zero-based for the @glyph_item. For each cluster, the - * item pointed at by the start variables is included in the cluster while - * the one pointed at by end variables is not. - * - * None of the members of a #PangoGlyphItemIter should be modified manually. + * indexed by `glyph_item->item->offset` to get to the text of @glyph_item. + * The @start_index and @end_index values can directly index into @text. The + * @start_glyph, @end_glyph, @start_char, and @end_char values however are + * zero-based for the @glyph_item. For each cluster, the item pointed at by + * the start variables is included in the cluster while the one pointed at by + * end variables is not. + * + * None of the members of a `PangoGlyphItemIter` should be modified manually. * * Since: 1.22 */ diff --git a/pango/pango-glyph.h b/pango/pango-glyph.h index 628eac96..7c1bf7b5 100644 --- a/pango/pango-glyph.h +++ b/pango/pango-glyph.h @@ -36,8 +36,10 @@ typedef struct _PangoGlyphString PangoGlyphString; /** * PangoGlyphUnit: * - * The #PangoGlyphUnit type is used to store dimensions within - * Pango. Dimensions are stored in 1/%PANGO_SCALE of a device unit. + * The `PangoGlyphUnit` type is used to store dimensions within + * Pango. + * + * Dimensions are stored in 1/%PANGO_SCALE of a device unit. * (A device unit might be a pixel for screen display, or * a point on a printer.) %PANGO_SCALE is currently 1024, and * may change in the future (unlikely though), but you should not @@ -54,7 +56,7 @@ typedef gint32 PangoGlyphUnit; * @x_offset: horizontal offset from nominal character position. * @y_offset: vertical offset from nominal character position. * - * The #PangoGlyphGeometry structure contains width and positioning + * The `PangoGlyphGeometry` structure contains width and positioning * information for a single glyph. */ struct _PangoGlyphGeometry @@ -68,15 +70,17 @@ struct _PangoGlyphGeometry */ /** * PangoGlyphVisAttr: - * @is_cluster_start: set for the first logical glyph in each cluster. (Clusters - * are stored in visual order, within the cluster, glyphs - * are always ordered in logical order, since visual - * order is meaningless; that is, in Arabic text, accent glyphs - * follow the glyphs for the base character.) + * @is_cluster_start: set for the first logical glyph in each cluster. + * (Clusters are stored in visual order, within the cluster, glyphs + * are always ordered in logical order, since visual order is meaningless; + * that is, in Arabic text, accent glyphs follow the glyphs for the + * base character.) + * + * A `PangoGlyphVisAttr` structure communicates information between + * the shaping and rendering phases. * - * The PangoGlyphVisAttr is used to communicate information between - * the shaping phase and the rendering phase. More attributes may be - * added in the future. + * Currently, it contains only cluster start information. yMore attributes + * may be added in the future. */ struct _PangoGlyphVisAttr { @@ -91,9 +95,8 @@ struct _PangoGlyphVisAttr * @geometry: the positional information about the glyph. * @attr: the visual attributes of the glyph. * - * The #PangoGlyphInfo structure represents a single glyph together with + * A `PangoGlyphInfo` structure represents a single glyph with * positioning information and visual attributes. - * It contains the following fields. */ struct _PangoGlyphInfo { @@ -102,9 +105,6 @@ struct _PangoGlyphInfo PangoGlyphVisAttr attr; }; -/* A string of glyphs with positional information and visual attributes - - * ready for drawing - */ /** * PangoGlyphString: * @num_glyphs: number of the glyphs in this glyph string. @@ -113,10 +113,11 @@ struct _PangoGlyphInfo * @log_clusters: logical cluster info, indexed by the byte index * within the text corresponding to the glyph string. * - * The #PangoGlyphString structure is used to store strings - * of glyphs with geometry and visual attribute information. - * The storage for the glyph information is owned - * by the structure which simplifies memory management. + * A `PangoGlyphString` is used to store strings of glyphs with geometry + * and visual attribute information. + * + * The storage for the glyph information is owned by the structure + * which simplifies memory management. */ struct _PangoGlyphString { gint num_glyphs; @@ -211,7 +212,8 @@ void pango_shape_full (const char *item_text, * positioning of glyphs. * * Flags influencing the shaping process. - * These can be passed to pango_shape_with_flags(). + * + * `PangoShapeFlags` can be passed to pango_shape_with_flags(). */ typedef enum { PANGO_SHAPE_NONE = 0, diff --git a/pango/pango-gravity.c b/pango/pango-gravity.c index 8565db16..a21749b6 100644 --- a/pango/pango-gravity.c +++ b/pango/pango-gravity.c @@ -19,64 +19,6 @@ * Boston, MA 02111-1307, USA. */ -/** - * SECTION:vertical - * @short_description:Laying text out in vertical directions - * @title:Vertical Text - * @see_also: pango_context_get_base_gravity(), - * pango_context_set_base_gravity(), - * pango_context_get_gravity(), - * pango_context_get_gravity_hint(), - * pango_context_set_gravity_hint(), - * pango_font_description_set_gravity(), - * pango_font_description_get_gravity(), - * pango_attr_gravity_new(), - * pango_attr_gravity_hint_new() - * - * Since 1.16, Pango is able to correctly lay vertical text out. In fact, it can - * set layouts of mixed vertical and non-vertical text. This section describes - * the types used for setting vertical text parameters. - * - * The way this is implemented is through the concept of - * <firstterm>gravity</firstterm>. Gravity of normal Latin text is south. A - * gravity value of east means that glyphs will be rotated ninety degrees - * counterclockwise. So, to render vertical text one needs to set the gravity - * and rotate the layout using the matrix machinery already in place. This has - * the huge advantage that most algorithms working on a #PangoLayout do not need - * any change as the assumption that lines run in the X direction and stack in - * the Y direction holds even for vertical text layouts. - * - * Applications should only need to set base gravity on #PangoContext in use, and - * let Pango decide the gravity assigned to each run of text. This automatically - * handles text with mixed scripts. A very common use is to set the context base - * gravity to auto using pango_context_set_base_gravity() - * and rotate the layout normally. Pango will make sure that - * Asian languages take the right form, while other scripts are rotated normally. - * - * The correct way to set gravity on a layout is to set it on the context - * associated with it using pango_context_set_base_gravity(). The context - * of a layout can be accessed using pango_layout_get_context(). The currently - * set base gravity of the context can be accessed using - * pango_context_get_base_gravity() and the <firstterm>resolved</firstterm> - * gravity of it using pango_context_get_gravity(). The resolved gravity is - * the same as the base gravity for the most part, except that if the base - * gravity is set to %PANGO_GRAVITY_AUTO, the resolved gravity will depend - * on the current matrix set on context, and is derived using - * pango_gravity_get_for_matrix(). - * - * The next thing an application may want to set on the context is the - * <firstterm>gravity hint</firstterm>. A #PangoGravityHint instructs how - * different scripts should react to the set base gravity. - * - * Font descriptions have a gravity property too, that can be set using - * pango_font_description_set_gravity() and accessed using - * pango_font_description_get_gravity(). However, those are rarely useful - * from application code and are mainly used by #PangoLayout internally. - * - * Last but not least, one can create #PangoAttribute<!---->s for gravity - * and gravity hint using pango_attr_gravity_new() and - * pango_attr_gravity_hint_new(). - */ #include "config.h" #include "pango-gravity.h" @@ -85,13 +27,12 @@ /** * pango_gravity_to_rotation: - * @gravity: gravity to query + * @gravity: gravity to query, should not be %PANGO_GRAVITY_AUTO * * Converts a #PangoGravity value to its natural rotation in radians. - * @gravity should not be %PANGO_GRAVITY_AUTO. * - * Note that pango_matrix_rotate() takes angle in degrees, not radians. - * So, to call pango_matrix_rotate() with the output of this function + * Note that [method@Pango.Matrix.rotate] takes angle in degrees, not radians. + * So, to call [method@Pango.Matrix,rotate] with the output of this function * you should multiply it by (180. / G_PI). * * Return value: the rotation value corresponding to @gravity. @@ -120,10 +61,10 @@ pango_gravity_to_rotation (PangoGravity gravity) /** * pango_gravity_get_for_matrix: - * @matrix: (nullable): a #PangoMatrix + * @matrix: (nullable): a `PangoMatrix` * * Finds the gravity that best matches the rotation component - * in a #PangoMatrix. + * in a `PangoMatrix`. * * Return value: the gravity of @matrix, which will never be * %PANGO_GRAVITY_AUTO, or %PANGO_GRAVITY_SOUTH if @matrix is %NULL @@ -295,8 +236,9 @@ get_script_properties (PangoScript script) * @base_gravity: base gravity of the paragraph * @hint: orientation hint * - * Based on the script, base gravity, and hint, returns actual gravity - * to use in laying out a single #PangoItem. + * Returns the gravity to use in laying out a `PangoItem`. + * + * The gravity is determined based on the script, base gravity, and hint. * * If @base_gravity is %PANGO_GRAVITY_AUTO, it is first replaced with the * preferred gravity of @script. To get the preferred gravity of a script, @@ -328,14 +270,16 @@ pango_gravity_get_for_script (PangoScript script, * @base_gravity: base gravity of the paragraph * @hint: orientation hint * - * Based on the script, East Asian width, base gravity, and hint, - * returns actual gravity to use in laying out a single character - * or #PangoItem. + * Returns the gravity to use in laying out a single character + * or `PangoItem`. + * + * The gravity is determined based on the script, East Asian width, + * base gravity, and hint, * - * This function is similar to pango_gravity_get_for_script() except + * This function is similar to [type_func@Pango.Gravity.get_for_script] except * that this function makes a distinction between narrow/half-width and - * wide/full-width characters also. Wide/full-width characters always - * stand <emphasis>upright</emphasis>, that is, they always take the base gravity, + * wide/full-width characters also. Wide/full-width characters always + * stand *upright*, that is, they always take the base gravity, * whereas narrow/full-width characters are always rotated in vertical * context. * diff --git a/pango/pango-gravity.h b/pango/pango-gravity.h index 63c29e5e..a3aa7f19 100644 --- a/pango/pango-gravity.h +++ b/pango/pango-gravity.h @@ -34,19 +34,22 @@ G_BEGIN_DECLS * @PANGO_GRAVITY_WEST: Glyphs are rotated 90 degrees counter-clockwise * @PANGO_GRAVITY_AUTO: Gravity is resolved from the context matrix * - * The #PangoGravity type represents the orientation of glyphs in a segment - * of text. This is useful when rendering vertical text layouts. In - * those situations, the layout is rotated using a non-identity PangoMatrix, - * and then glyph orientation is controlled using #PangoGravity. + * `PangoGravity` represents the orientation of glyphs in a segment + * of text. + * + * This is useful when rendering vertical text layouts. In those situations, + * the layout is rotated using a non-identity [struct@Pango.Matrix], and then + * glyph orientation is controlled using `PangoGravity`. + * * Not every value in this enumeration makes sense for every usage of - * #PangoGravity; for example, %PANGO_GRAVITY_AUTO only can be passed to - * pango_context_set_base_gravity() and can only be returned by - * pango_context_get_base_gravity(). + * `PangoGravity`; for example, %PANGO_GRAVITY_AUTO only can be passed to + * [method@Pango.Context.set_base_gravity] and can only be returned by + * [method@Pango.Context.get_base_gravity]. * - * See also: #PangoGravityHint + * See also: [enum@Pango.GravityHint] * * Since: 1.16 - **/ + */ typedef enum { PANGO_GRAVITY_SOUTH, PANGO_GRAVITY_EAST, @@ -66,11 +69,12 @@ typedef enum { * respects the line progression. This means, Latin and Arabic will take * opposite gravities and both flow top-to-bottom for example. * - * The #PangoGravityHint defines how horizontal scripts should behave in a - * vertical context. That is, English excerpt in a vertical paragraph for - * example. + * `PangoGravityHint` defines how horizontal scripts should behave in a + * vertical context. + * + * That is, English excerpts in a vertical paragraph for example. * - * See #PangoGravity. + * See also [enum@Pango.Gravity] * * Since: 1.16 **/ diff --git a/pango/pango-item.c b/pango/pango-item.c index dae65645..d1caa771 100644 --- a/pango/pango-item.c +++ b/pango/pango-item.c @@ -10,7 +10,7 @@ * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Library General Public License for more details. * * You should have received a copy of the GNU Library General Public @@ -27,11 +27,11 @@ /** * pango_item_new: * - * Creates a new #PangoItem structure initialized to default values. + * Creates a new `PangoItem` structure initialized to default values. * - * Return value: the newly allocated #PangoItem, which should - * be freed with pango_item_free(). - **/ + * Return value: the newly allocated `PangoItem`, which should + * be freed with [method@Pango.Item.free]. + */ PangoItem * pango_item_new (void) { @@ -42,14 +42,14 @@ pango_item_new (void) /** * pango_item_copy: - * @item: (nullable): a #PangoItem, may be %NULL + * @item: (nullable): a `PangoItem`, may be %NULL * - * Copy an existing #PangoItem structure. + * Copy an existing `PangoItem` structure. * - * Return value: (nullable): the newly allocated #PangoItem, which - * should be freed with pango_item_free(), or %NULL if - * @item was %NULL. - **/ + * Return value: (nullable): the newly allocated `PangoItem`, which + * should be freed with [method@Pango.Item.free], or %NULL if + * @item was %NULL. + */ PangoItem * pango_item_copy (PangoItem *item) { @@ -58,7 +58,7 @@ pango_item_copy (PangoItem *item) if (item == NULL) return NULL; - + result = g_slice_new (PangoItem); result->offset = item->offset; @@ -84,9 +84,9 @@ pango_item_copy (PangoItem *item) /** * pango_item_free: - * @item: (nullable): a #PangoItem, may be %NULL + * @item: (nullable): a `PangoItem`, may be %NULL * - * Free a #PangoItem and all associated memory. + * Free a `PangoItem` and all associated memory. **/ void pango_item_free (PangoItem *item) @@ -112,28 +112,31 @@ G_DEFINE_BOXED_TYPE (PangoItem, pango_item, /** * pango_item_split: - * @orig: a #PangoItem - * @split_index: byte index of position to split item, relative to the start of the item + * @orig: a `PangoItem` + * @split_index: byte index of position to split item, relative to the + * start of the item * @split_offset: number of chars between start of @orig and @split_index * * Modifies @orig to cover only the text after @split_index, and * returns a new item that covers the text before @split_index that - * used to be in @orig. You can think of @split_index as the length of - * the returned item. @split_index may not be 0, and it may not be - * greater than or equal to the length of @orig (that is, there must - * be at least one byte assigned to each item, you can't create a - * zero-length item). @split_offset is the length of the first item in - * chars, and must be provided because the text used to generate the - * item isn't available, so pango_item_split() can't count the char - * length of the split items itself. + * used to be in @orig. + * + * You can think of @split_index as the length of the returned item. + * @split_index may not be 0, and it may not be greater than or equal + * to the length of @orig (that is, there must be at least one byte + * assigned to each item, you can't create a zero-length item). + * @split_offset is the length of the first item in chars, and must be + * provided because the text used to generate the item isn't available, + * so `pango_item_split()` can't count the char length of the split items + * itself. * * Return value: new item representing text before @split_index, which - * should be freed with pango_item_free(). - **/ + * should be freed with [method@Pango.Item.free]. + */ PangoItem* -pango_item_split (PangoItem *orig, - int split_index, - int split_offset) +pango_item_split (PangoItem *orig, + int split_index, + int split_offset) { PangoItem *new_item; @@ -169,14 +172,15 @@ compare_attr (gconstpointer p1, gconstpointer p2) /** * pango_item_apply_attrs: - * @item: a #PangoItem - * @iter: a #PangoAttrIterator - * - * Add attributes to a PangoItem. The idea is that you have - * attributes that don't affect itemization, such as font features, - * so you filter them out using pango_attr_list_filter(), itemize - * your text, then reapply the attributes to the resulting items - * using this function. + * @item: a `PangoItem` + * @iter: a `PangoAttrIterator` + * + * Add attributes to a `PangoItem`. + * + * The idea is that you have attributes that don't affect itemization, + * such as font features, so you filter them out using + * [method@Pango.AttrList.filter], itemize your text, then reapply the + * attributes to the resulting items using this function. * * The @iter should be positioned before the range of the item, * and will be advanced past it. This function is meant to be called diff --git a/pango/pango-item.h b/pango/pango-item.h index d4162f90..a1e95086 100644 --- a/pango/pango-item.h +++ b/pango/pango-item.h @@ -34,7 +34,8 @@ typedef struct _PangoItem PangoItem; * PANGO_ANALYSIS_FLAG_CENTERED_BASELINE: * * Whether the segment should be shifted to center around the baseline. - * Used in vertical writing directions mostly. + * + * This is mainly used in vertical writing directions. * * Since: 1.16 */ @@ -43,8 +44,7 @@ typedef struct _PangoItem PangoItem; /** * PANGO_ANALYSIS_FLAG_IS_ELLIPSIS: * - * This flag is used to mark runs that hold ellipsized text, - * in an ellipsized layout. + * Whether this run holds ellipsized text. * * Since: 1.36.7 */ @@ -53,8 +53,7 @@ typedef struct _PangoItem PangoItem; /** * PANGO_ANALYSIS_FLAG_NEED_HYPHEN: * - * This flag tells Pango to add a hyphen at the end of the - * run during shaping. + * Whether to add a hyphen at the end of the run during shaping. * * Since: 1.44 */ @@ -66,19 +65,24 @@ typedef struct _PangoItem PangoItem; * @lang_engine: unused * @font: the font for this segment. * @level: the bidirectional level for this segment. - * @gravity: the glyph orientation for this segment (A #PangoGravity). + * @gravity: the glyph orientation for this segment (A `PangoGravity`). * @flags: boolean flags for this segment (Since: 1.16). - * @script: the detected script for this segment (A #PangoScript) (Since: 1.18). + * @script: the detected script for this segment (A `PangoScript`) (Since: 1.18). * @language: the detected language for this segment. * @extra_attrs: extra attributes for this segment. * - * The #PangoAnalysis structure stores information about + * The `PangoAnalysis` structure stores information about * the properties of a segment of text. */ struct _PangoAnalysis { +#ifndef __GI_SCANNER__ PangoEngineShape *shape_engine; PangoEngineLang *lang_engine; +#else + gpointer shape_engine; + gpointer lang_engine; +#endif PangoFont *font; guint8 level; @@ -98,7 +102,10 @@ struct _PangoAnalysis * @num_chars: number of Unicode characters in the item. * @analysis: analysis results for the item. * - * The #PangoItem structure stores information about a segment of text. + * The `PangoItem` structure stores information about a segment of text. + * + * You typically obtain `PangoItems` by itemizing a piece of text + * with [func@itemize]. */ struct _PangoItem { diff --git a/pango/pango-language.c b/pango/pango-language.c index 04c3e0ca..2f79acec 100644 --- a/pango/pango-language.c +++ b/pango/pango-language.c @@ -136,10 +136,10 @@ pango_language_free (PangoLanguage *language G_GNUC_UNUSED) /** * PangoLanguage: * - * The #PangoLanguage structure is used to + * The `PangoLanguage` structure is used to * represent a language. * - * #PangoLanguage pointers can be efficiently + * `PangoLanguage` pointers can be efficiently * copied and compared with each other. */ G_DEFINE_BOXED_TYPE (PangoLanguage, pango_language, @@ -151,13 +151,12 @@ G_DEFINE_BOXED_TYPE (PangoLanguage, pango_language, * * Return the Unix-style locale string for the language currently in * effect. On Unix systems, this is the return value from - * <literal>setlocale(LC_CTYPE, NULL)</literal>, and the user can - * affect this through the environment variables LC_ALL, LC_CTYPE or - * LANG (checked in that order). The locale strings typically is in - * the form lang_COUNTRY, where lang is an ISO-639 language code, and - * COUNTRY is an ISO-3166 country code. For instance, sv_FI for - * Swedish as written in Finland or pt_BR for Portuguese as written in - * Brazil. + * `setlocale (LC_CTYPE, NULL)`, and the user can affect this through + * the environment variables LC_ALL, LC_CTYPE or LANG (checked + * in that order). The locale strings typically is in the form lang_COUNTRY, + * where lang is an ISO-639 language code, and COUNTRY is an ISO-3166 country + * code. For instance, sv_FI for Swedish as written in Finland or pt_BR for + * Portuguese as written in Brazil. * * On Windows, the C library doesn't use any such environment * variables, and setting them won't affect the behavior of functions @@ -252,11 +251,10 @@ _pango_get_lc_ctype (void) /** * pango_language_get_default: * - * Returns the #PangoLanguage for the current locale of the process. - * Note that this can change over the life of an application. + * Returns the `PangoLanguage` for the current locale of the process. * * On Unix systems, this is the return value is derived from - * <literal>setlocale(LC_CTYPE, NULL)</literal>, and the user can + * `setlocale (LC_CTYPE, NULL)`, and the user can * affect this through the environment variables LC_ALL, LC_CTYPE or * LANG (checked in that order). The locale string typically is in * the form lang_COUNTRY, where lang is an ISO-639 language code, and @@ -274,13 +272,15 @@ _pango_get_lc_ctype (void) * variables, and does return a Unix-style locale string based on * either said environment variables or the thread's current locale. * - * Your application should call <literal>setlocale(LC_ALL, "");</literal> - * for the user settings to take effect. Gtk+ does this in its initialization + * Your application should call `setlocale(LC_ALL, "")` for the user + * settings to take effect. GTK does this in its initialization * functions automatically (by calling gtk_set_locale()). - * See <literal>man setlocale</literal> for more details. + * See the setlocale() manpage for more details. + * + * Note that the default language can change over the life of an application. * * Return value: (transfer none): the default language as a - * #PangoLanguage, must not be freed. + * `PangoLanguage`, must not be freed. * * Since: 1.16 **/ @@ -308,23 +308,23 @@ pango_language_get_default (void) * pango_language_from_string: * @language: (allow-none): a string representing a language tag, or %NULL * - * Take a RFC-3066 format language tag as a string and convert it to a - * #PangoLanguage pointer that can be efficiently copied (copy the - * pointer) and compared with other language tags (compare the - * pointer.) + * Convert a language tag to a `PangoLanguage`. + * + * The language tag must be in a RFC-3066 format. `PangoLanguage` pointers + * can be efficiently copied (copy the pointer) and compared with other + * language tags (compare the pointer.) * * This function first canonicalizes the string by converting it to * lowercase, mapping '_' to '-', and stripping all characters other * than letters and '-'. * - * Use pango_language_get_default() if you want to get the #PangoLanguage for - * the current locale of the process. + * Use [type_func@Pango.Language.get_default] if you want to get the `PangoLanguage` + * for the current locale of the process. * * Return value: (transfer none) (nullable): an opaque pointer to a - * #PangoLanguage structure, or %NULL if @language was - * %NULL. The returned pointer will be valid forever - * after, and should not be freed. - **/ + * `PangoLanguage` structure, or %NULL if @language was %NULL. The + * returned pointer will be valid forever after, and should not be freed. + */ PangoLanguage * pango_language_from_string (const char *language) { @@ -374,10 +374,10 @@ out: * pango_language_to_string: * @language: a language tag. * - * Gets the RFC-3066 format string representing the given language tag. + * Gets the RFC-3066 format string representing the given language tag. * - * Returns: a string representing the language tag. This is owned by - * Pango and should not be freed. + * Returns: a string representing the language tag. This is owned by + * Pango and should not be freed. */ const char * (pango_language_to_string) (PangoLanguage *language) @@ -387,21 +387,23 @@ const char * /** * pango_language_matches: - * @language: (nullable): a language tag (see pango_language_from_string()), - * %NULL is allowed and matches nothing but '*' + * @language: (nullable): a language tag (see [type_func@Pango.Language.from_string]), + * %NULL is allowed and matches nothing but '*' * @range_list: a list of language ranges, separated by ';', ':', * ',', or space characters. * Each element must either be '*', or a RFC 3066 language range - * canonicalized as by pango_language_from_string() + * canonicalized as by [type_func@Pango.Language.from_string] * * Checks if a language tag matches one of the elements in a list of - * language ranges. A language tag is considered to match a range + * language ranges. + * + * A language tag is considered to match a range * in the list if the range is '*', the range is exactly the tag, * or the range is a prefix of the tag, and the character after it * in the tag is '-'. * * Return value: %TRUE if a match was found. - **/ + */ gboolean pango_language_matches (PangoLanguage *language, const char *range_list) @@ -561,30 +563,31 @@ static const LangInfo lang_texts[] = { /** * pango_language_get_sample_string: - * @language: (nullable): a #PangoLanguage, or %NULL + * @language: (nullable): a `PangoLanguage`, or %NULL * * Get a string that is representative of the characters needed to * render a particular language. * - * The sample text may be a pangram, but is not necessarily. It is chosen to - * be demonstrative of normal text in the language, as well as exposing font - * feature requirements unique to the language. It is suitable for use + * The sample text may be a pangram, but is not necessarily. It is chosen + * to be demonstrative of normal text in the language, as well as exposing + * font feature requirements unique to the language. It is suitable for use * as sample text in a font selection dialog. * * If @language is %NULL, the default language as found by - * pango_language_get_default() is used. + * [type_func@Pango.Language.get_default] is used. * * If Pango does not have a sample string for @language, the classic * "The quick brown fox..." is returned. This can be detected by * comparing the returned pointer value to that returned for (non-existent) * language code "xx". That is, compare to: - * <informalexample><programlisting> + * + * ``` * pango_language_get_sample_string (pango_language_from_string ("xx")) - * </programlisting></informalexample> + * ``` * * Return value: the sample string. This value is owned by Pango * and should not be freed. - **/ + */ const char * pango_language_get_sample_string (PangoLanguage *language) { @@ -615,11 +618,12 @@ pango_language_get_sample_string (PangoLanguage *language) /** * pango_language_get_scripts: - * @language: (allow-none): a #PangoLanguage, or %NULL - * @num_scripts: (out caller-allocates) (allow-none): location to return number of scripts, - * or %NULL + * @language: (allow-none): a `PangoLanguage`, or %NULL + * @num_scripts: (out caller-allocates) (allow-none): location to + * return number of scripts, or %NULL * * Determines the scripts used to to write @language. + * * If nothing is known about the language tag @language, * or if @language is %NULL, then %NULL is returned. * The list of scripts returned starts with the script that the @@ -630,27 +634,27 @@ pango_language_get_sample_string (PangoLanguage *language) * * Most languages use only one script for writing, but there are * some that use two (Latin and Cyrillic for example), and a few - * use three (Japanese for example). Applications should not make + * use three (Japanese for example). Applications should not make * any assumptions on the maximum number of scripts returned * though, except that it is positive if the return value is not * %NULL, and it is a small number. * - * The pango_language_includes_script() function uses this function + * The [method@Pango.Language.includes_script] function uses this function * internally. * - * Note: while the return value is declared as PangoScript, the - * returned values are from the GUnicodeScript enumeration, which + * Note: while the return value is declared as `PangoScript`, the + * returned values are from the `GUnicodeScript` enumeration, which * may have more values. Callers need to handle unknown values. * * Return value: (array length=num_scripts) (nullable): An array of - * #PangoScript values, with the number of entries in the array stored - * in @num_scripts, or %NULL if Pango does not have any information - * about this particular language tag (also the case if @language is - * %NULL). The returned array is owned by Pango and should not be - * modified or freed. - + * `PangoScript` values, with the number of entries in the array + * stored in @num_scripts, or %NULL if Pango does not have any + * information about this particular language tag (also the case + * if @language is %NULL). The returned array is owned by Pango + * and should not be modified or freed. + * * Since: 1.22 - **/ + */ const PangoScript * pango_language_get_scripts (PangoLanguage *language, int *num_scripts) @@ -686,8 +690,8 @@ pango_language_get_scripts (PangoLanguage *language, /** * pango_language_includes_script: - * @language: (nullable): a #PangoLanguage, or %NULL - * @script: a #PangoScript + * @language: (nullable): a `PangoLanguage`, or %NULL + * @script: a `PangoScript` * * Determines if @script is one of the scripts used to * write @language. The returned value is conservative; @@ -697,18 +701,17 @@ pango_language_get_scripts (PangoLanguage *language, * * This routine is used in Pango's itemization process when * determining if a supplied language tag is relevant to - * a particular section of text. It probably is not useful for - * applications in most circumstances. + * a particular section of text. It probably is not useful + * for applications in most circumstances. * - * This function uses pango_language_get_scripts() internally. + * This function uses [method@Pango.Language.get_scripts] internally. * * Return value: %TRUE if @script is one of the scripts used - * to write @language or if nothing is known about @language - * (including the case that @language is %NULL), - * %FALSE otherwise. - + * to write @language or if nothing is known about @language + * (including the case that @language is %NULL), %FALSE otherwise. + * * Since: 1.4 - **/ + */ gboolean pango_language_includes_script (PangoLanguage *language, PangoScript script) @@ -838,18 +841,19 @@ out: /** * pango_language_get_preferred: * - * Returns the list of languages that the user prefers, as specified - * by the PANGO_LANGUAGE or LANGUAGE environment variables, in order - * of preference. Note that this list does not necessarily include - * the language returned by pango_language_get_default(). + * Returns the list of languages that the user prefers. + * + * The list is specified by the `PANGO_LANGUAGE` or `LANGUAGE` environment + * variables, in order of preference. Note that this list does not necessarily + * include the language returned by [type_func@Pango.Language.get_default]. * * When choosing language-specific resources, such as the sample - * text returned by pango_language_get_sample_string(), you should + * text returned by [method@Pango.Language.get_sample_string], you should * first try the default language, followed by the languages returned * by this function. * * Returns: (transfer none) (nullable): a %NULL-terminated array of - * PangoLanguage* + * `PangoLanguage`* * * Since: 1.48 */ @@ -864,44 +868,42 @@ pango_language_get_preferred (void) /** * pango_script_get_sample_language: - * @script: a #PangoScript + * @script: a `PangoScript` * - * Given a script, finds a language tag that is reasonably - * representative of that script. This will usually be the - * most widely spoken or used language written in that script: - * for instance, the sample language for %PANGO_SCRIPT_CYRILLIC - * is <literal>ru</literal> (Russian), the sample language - * for %PANGO_SCRIPT_ARABIC is <literal>ar</literal>. + * Finds a language tag that is reasonably representative of @script. * - * For some - * scripts, no sample language will be returned because there - * is no language that is sufficiently representative. The best - * example of this is %PANGO_SCRIPT_HAN, where various different + * The language will usually be the most widely spoken or used language written + * in that script: for instance, the sample language for %PANGO_SCRIPT_CYRILLIC + * is ru (Russian), the sample language for %PANGO_SCRIPT_ARABIC is ar. + * + * For some scripts, no sample language will be returned because + * there is no language that is sufficiently representative. The + * best example of this is %PANGO_SCRIPT_HAN, where various different * variants of written Chinese, Japanese, and Korean all use * significantly different sets of Han characters and forms * of shared characters. No sample language can be provided * for many historical scripts as well. * * As of 1.18, this function checks the environment variables - * PANGO_LANGUAGE and LANGUAGE (checked in that order) first. + * `PANGO_LANGUAGE` and `LANGUAGE` (checked in that order) first. * If one of them is set, it is parsed as a list of language tags - * separated by colons or other separators. This function + * separated by colons or other separators. This function * will return the first language in the parsed list that Pango - * believes may use @script for writing. This last predicate - * is tested using pango_language_includes_script(). This can + * believes may use @script for writing. This last predicate + * is tested using [method@Pango.Language.includes_script]. This can * be used to control Pango's font selection for non-primary - * languages. For example, a PANGO_LANGUAGE enviroment variable - * set to "en:fa" makes Pango choose fonts suitable for Persian (fa) + * languages. For example, a `PANGO_LANGUAGE` enviroment variable + * set to "en:fa" makes Pango choose fonts suitable for Persian (fa) * instead of Arabic (ar) when a segment of Arabic text is found - * in an otherwise non-Arabic text. The same trick can be used to + * in an otherwise non-Arabic text. The same trick can be used to * choose a default language for %PANGO_SCRIPT_HAN when setting * context language is not feasible. * - * Return value: (nullable): a #PangoLanguage that is representative + * Return value: (nullable): a `PangoLanguage` that is representative * of the script, or %NULL if no such language exists. * * Since: 1.4 - **/ + */ PangoLanguage * pango_script_get_sample_language (PangoScript script) { diff --git a/pango/pango-layout.c b/pango/pango-layout.c index 88e142af..5298647e 100644 --- a/pango/pango-layout.c +++ b/pango/pango-layout.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 @@ -20,56 +20,48 @@ */ /** - * SECTION:layout - * @short_description:High-level layout driver objects - * @title:Layout Objects + * PangoLayout: + * + * A `PangoLayout` structure represents an entire paragraph of text. * * While complete access to the layout capabilities of Pango is provided * using the detailed interfaces for itemization and shaping, using * that functionality directly involves writing a fairly large amount - * of code. The objects and functions in this section provide a - * high-level driver for formatting entire paragraphs of text - * at once. This includes paragraph-level functionality such as - * line-breaking, justification, alignment and ellipsization. - */ - -/** - * PangoLayout: - * - * The #PangoLayout structure represents an entire paragraph - * of text. It is initialized with a #PangoContext, UTF-8 string - * and set of attributes for that string. Once that is done, the - * set of formatted lines can be extracted from the object, - * the layout can be rendered, and conversion between logical - * character positions within the layout's text, and the physical - * position of the resulting glyphs can be made. - * - * There are also a number of parameters to adjust the formatting - * of a #PangoLayout, which are illustrated in <xref linkend="parameters"/>. - * It is possible, as well, to ignore the 2-D setup, and simply - * treat the results of a #PangoLayout as a list of lines. - * - * <figure id="parameters"> - * <title>Adjustable parameters (on the left) and font metrics (on the right) for a PangoLayout</title> - * <graphic fileref="layout.png" format="PNG"></graphic> - * </figure> - * - * The #PangoLayout structure is opaque, and has no user-visible - * fields. + * of code. `PangoLayout` provides a high-level driver for formatting + * entire paragraphs of text at once. This includes paragraph-level + * functionality such as line breaking, justification, alignment and + * ellipsization. + * + * A `PangoLayout is initialized with a `PangoContext`, UTF-8 string + * and set of attributes for that string. Once that is done, the set of + * formatted lines can be extracted from the object, the layout can be + * rendered, and conversion between logical character positions within + * the layout's text, and the physical position of the resulting glyphs + * can be made. + * + * There are a number of parameters to adjust the formatting of a + * `PangoLayout`. The following image shows adjustable parameters + * (on the left) and font metrics (on the right): + * + *  + * + * It is possible, as well, to ignore the 2-D setup, + * and simply treat the results of a `PangoLayout` as a list of lines. */ /** * PangoLayoutIter: * - * A #PangoLayoutIter structure can be used to - * iterate over the visual extents of a #PangoLayout. + * A `PangoLayoutIter` can be used to iterate over the visual + * extents of a `PangoLayout`. + * + * To obtain a `PangoLayoutIter`, use [method@Pango.Layout.get_iter]. * - * The #PangoLayoutIter structure is opaque, and - * has no user-visible fields. + * The `PangoLayoutIter` structure is opaque, and has no user-visible fields. */ #include "config.h" -#include "pango-glyph.h" /* For pango_shape() */ +#include "pango-glyph.h" /* For pango_shape() */ #include "pango-break.h" #include "pango-item.h" #include "pango-engine.h" @@ -145,7 +137,7 @@ struct _PangoLayoutClass #define ITER_IS_INVALID(iter) G_UNLIKELY (check_invalid ((iter), G_STRLOC)) static gboolean check_invalid (PangoLayoutIter *iter, - const char *loc) + const char *loc) { if (iter->line->layout == NULL) { @@ -169,24 +161,24 @@ static PangoAttrList *pango_layout_get_effective_attributes (PangoLayout *layout static PangoLayoutLine * pango_layout_line_new (PangoLayout *layout); static void pango_layout_line_postprocess (PangoLayoutLine *line, - ParaBreakState *state, - gboolean wrapped); + ParaBreakState *state, + gboolean wrapped); static int *pango_layout_line_get_log2vis_map (PangoLayoutLine *line, - gboolean strong); + gboolean strong); static int *pango_layout_line_get_vis2log_map (PangoLayoutLine *line, - gboolean strong); + gboolean strong); static void pango_layout_line_leaked (PangoLayoutLine *line); /* doesn't leak line */ static PangoLayoutLine* _pango_layout_iter_get_line (PangoLayoutIter *iter); static void pango_layout_get_item_properties (PangoItem *item, - ItemProperties *properties); + ItemProperties *properties); static void pango_layout_get_empty_extents_at_index (PangoLayout *layout, - int index, - PangoRectangle *logical_rect); + int index, + PangoRectangle *logical_rect); static void pango_layout_finalize (GObject *object); @@ -257,18 +249,16 @@ pango_layout_finalize (GObject *object) G_OBJECT_CLASS (pango_layout_parent_class)->finalize (object); } - /** * pango_layout_new: - * @context: a #PangoContext + * @context: a `PangoContext` * - * Create a new #PangoLayout object with attributes initialized to - * default values for a particular #PangoContext. + * Create a new `PangoLayout` object with attributes initialized to + * default values for a particular `PangoContext`. * - * Return value: the newly allocated #PangoLayout, with a reference - * count of one, which should be freed with - * g_object_unref(). - **/ + * Return value: the newly allocated `PangoLayout`, with a reference + * count of one, which should be freed with g_object_unref(). + */ PangoLayout * pango_layout_new (PangoContext *context) { @@ -287,16 +277,17 @@ pango_layout_new (PangoContext *context) /** * pango_layout_copy: - * @src: a #PangoLayout + * @src: a `PangoLayout` * - * Does a deep copy-by-value of the @src layout. The attribute list, - * tab array, and text from the original layout are all copied by - * value. + * Creates a deep copy-by-value of the layout. * - * Return value: (transfer full): the newly allocated #PangoLayout, - * with a reference count of one, which should be freed - * with g_object_unref(). - **/ + * The attribute list, tab array, and text from the original layout + * are all copied by value. + * + * Return value: (transfer full): the newly allocated `PangoLayout`, + * with a reference count of one, which should be freed + * with g_object_unref(). + */ PangoLayout* pango_layout_copy (PangoLayout *src) { @@ -319,21 +310,21 @@ pango_layout_copy (PangoLayout *src) /* Value fields */ memcpy (&layout->copy_begin, &src->copy_begin, - G_STRUCT_OFFSET (PangoLayout, copy_end) - G_STRUCT_OFFSET (PangoLayout, copy_begin)); + G_STRUCT_OFFSET (PangoLayout, copy_end) - G_STRUCT_OFFSET (PangoLayout, copy_begin)); return layout; } /** * pango_layout_get_context: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * - * Retrieves the #PangoContext used for this layout. + * Retrieves the `PangoContext` used for this layout. * - * Return value: (transfer none): the #PangoContext for the layout. - * This does not have an additional refcount added, so if you want to - * keep a copy of this around, you must reference it yourself. - **/ + * Return value: (transfer none): the `PangoContext` for the layout. + * This does not have an additional refcount added, so if you want to + * keep a copy of this around, you must reference it yourself. + */ PangoContext * pango_layout_get_context (PangoLayout *layout) { @@ -344,16 +335,18 @@ pango_layout_get_context (PangoLayout *layout) /** * pango_layout_set_width: - * @layout: a #PangoLayout. + * @layout: a `PangoLayout`. * @width: the desired width in Pango units, or -1 to indicate that no - * wrapping or ellipsization should be performed. + * wrapping or ellipsization should be performed. * - * Sets the width to which the lines of the #PangoLayout should wrap or - * ellipsized. The default value is -1: no width set. - **/ + * Sets the width to which the lines of the `PangoLayout` should wrap or + * ellipsized. + * + * The default value is -1: no width set. + */ void pango_layout_set_width (PangoLayout *layout, - int width) + int width) { g_return_if_fail (layout != NULL); @@ -374,12 +367,12 @@ pango_layout_set_width (PangoLayout *layout, /** * pango_layout_get_width: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * - * Gets the width to which the lines of the #PangoLayout should wrap. + * Gets the width to which the lines of the `PangoLayout` should wrap. * * Return value: the width in Pango units, or -1 if no width set. - **/ + */ int pango_layout_get_width (PangoLayout *layout) { @@ -389,28 +382,29 @@ pango_layout_get_width (PangoLayout *layout) /** * pango_layout_set_height: - * @layout: a #PangoLayout. + * @layout: a `PangoLayout`. * @height: the desired height of the layout in Pango units if positive, - * or desired number of lines if negative. + * or desired number of lines if negative. + * + * Sets the height to which the `PangoLayout` should be ellipsized at. * - * Sets the height to which the #PangoLayout should be ellipsized at. There - * are two different behaviors, based on whether @height is positive or - * negative. + * There are two different behaviors, based on whether @height is positive + * or negative. * - * If @height is positive, it will be the maximum height of the layout. Only + * If @height is positive, it will be the maximum height of the layout. Only * lines would be shown that would fit, and if there is any text omitted, - * an ellipsis added. At least one line is included in each paragraph regardless - * of how small the height value is. A value of zero will render exactly one + * an ellipsis added. At least one line is included in each paragraph regardless + * of how small the height value is. A value of zero will render exactly one * line for the entire layout. * - * If @height is negative, it will be the (negative of) maximum number of lines per - * paragraph. That is, the total number of lines shown may well be more than + * If @height is negative, it will be the (negative of) maximum number of lines + * per paragraph. That is, the total number of lines shown may well be more than * this value if the layout contains multiple paragraphs of text. * The default value of -1 means that first line of each paragraph is ellipsized. * This behavior may be changed in the future to act per layout instead of per - * paragraph. File a bug against pango at <ulink - * url="http://bugzilla.gnome.org/">http://bugzilla.gnome.org/</ulink> if your - * code relies on this behavior. + * paragraph. File a bug against pango at + * [https://gitlab.gnome.org/gnome/pango](https://gitlab.gnome.org/gnome/pango) + * if your code relies on this behavior. * * Height setting only has effect if a positive width is set on * @layout and ellipsization mode of @layout is not %PANGO_ELLIPSIZE_NONE. @@ -419,10 +413,10 @@ pango_layout_get_width (PangoLayout *layout) * future. * * Since: 1.20 - **/ + */ void pango_layout_set_height (PangoLayout *layout, - int height) + int height) { g_return_if_fail (layout != NULL); @@ -435,26 +429,27 @@ pango_layout_set_height (PangoLayout *layout, * Bug 549003 */ if (layout->ellipsize != PANGO_ELLIPSIZE_NONE && - !(layout->lines && layout->is_ellipsized == FALSE && - height < 0 && layout->line_count <= (guint) -height)) - layout_changed (layout); + !(layout->lines && layout->is_ellipsized == FALSE && + height < 0 && layout->line_count <= (guint) -height)) + layout_changed (layout); } } /** * pango_layout_get_height: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * - * Gets the height of layout used for ellipsization. See - * pango_layout_set_height() for details. + * Gets the height of layout used for ellipsization. * - * Return value: the height, in Pango units if positive, or - * number of lines if negative. + * See [method@Pango.Layout.set_height] for details. + * + * Return value: the height, in Pango units if positive, + * or number of lines if negative. * * Since: 1.20 - **/ + */ int -pango_layout_get_height (PangoLayout *layout) +pango_layout_get_height (PangoLayout *layout) { g_return_val_if_fail (layout != NULL, 0); return layout->height; @@ -462,16 +457,18 @@ pango_layout_get_height (PangoLayout *layout) /** * pango_layout_set_wrap: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * @wrap: the wrap mode * - * Sets the wrap mode; the wrap mode only has effect if a width - * is set on the layout with pango_layout_set_width(). - * To turn off wrapping, set the width to -1. - **/ + * Sets the wrap mode. + * + * The wrap mode only has effect if a width is set on the layout + * with [method@Pango.Layout.set_width]. To turn off wrapping, + * set the width to -1. + */ void -pango_layout_set_wrap (PangoLayout *layout, - PangoWrapMode wrap) +pango_layout_set_wrap (PangoLayout *layout, + PangoWrapMode wrap) { g_return_if_fail (PANGO_IS_LAYOUT (layout)); @@ -480,21 +477,21 @@ pango_layout_set_wrap (PangoLayout *layout, layout->wrap = wrap; if (layout->width != -1) - layout_changed (layout); + layout_changed (layout); } } /** * pango_layout_get_wrap: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * * Gets the wrap mode for the layout. * - * Use pango_layout_is_wrapped() to query whether any paragraphs - * were actually wrapped. + * Use [method@Pango.Layout.is_wrapped] to query whether + * any paragraphs were actually wrapped. * * Return value: active wrap mode. - **/ + */ PangoWrapMode pango_layout_get_wrap (PangoLayout *layout) { @@ -505,7 +502,7 @@ pango_layout_get_wrap (PangoLayout *layout) /** * pango_layout_is_wrapped: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * * Queries whether the layout had to wrap any paragraphs. * @@ -515,7 +512,7 @@ pango_layout_get_wrap (PangoLayout *layout) * to be wrapped. * * Return value: %TRUE if any paragraphs had to be wrapped, %FALSE - * otherwise. + * otherwise. * * Since: 1.16 */ @@ -531,20 +528,21 @@ pango_layout_is_wrapped (PangoLayout *layout) /** * pango_layout_set_indent: - * @layout: a #PangoLayout. + * @layout: a `PangoLayout`. * @indent: the amount by which to indent. * - * Sets the width in Pango units to indent each paragraph. A negative value - * of @indent will produce a hanging indentation. That is, the first line will - * have the full width, and subsequent lines will be indented by the - * absolute value of @indent. + * Sets the width in Pango units to indent each paragraph. + * + * A negative value of @indent will produce a hanging indentation. + * That is, the first line will have the full width, and subsequent + * lines will be indented by the absolute value of @indent. * * The indent setting is ignored if layout alignment is set to * %PANGO_ALIGN_CENTER. - **/ + */ void pango_layout_set_indent (PangoLayout *layout, - int indent) + int indent) { g_return_if_fail (layout != NULL); @@ -557,13 +555,14 @@ pango_layout_set_indent (PangoLayout *layout, /** * pango_layout_get_indent: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` + * + * Gets the paragraph indent width in Pango units. * - * Gets the paragraph indent width in Pango units. A negative value - * indicates a hanging indentation. + * A negative value indicates a hanging indentation. * * Return value: the indent in Pango units. - **/ + */ int pango_layout_get_indent (PangoLayout *layout) { @@ -573,24 +572,25 @@ pango_layout_get_indent (PangoLayout *layout) /** * pango_layout_set_spacing: - * @layout: a #PangoLayout. + * @layout: a `PangoLayout`. * @spacing: the amount of spacing * * Sets the amount of spacing in Pango unit between - * the lines of the layout. When placing lines with - * spacing, Pango arranges things so that + * the lines of the layout. + * + * When placing lines with spacing, Pango arranges things so that * * line2.top = line1.bottom + spacing * - * Note: Since 1.44, Pango defaults to using the - * line height (as determined by the font) for placing - * lines. The @spacing set with this function is only - * taken into account when the line-height factor is - * set to zero with pango_layout_set_line_spacing(). - **/ + * Note: Since 1.44, Pango defaults to using the line height + * (as determined by the font) for placing lines. The @spacing + * set with this function is only taken into account when the + * line height factor is set to zero with + * [method@Pango.Layout.set_line_spacing]. + */ void pango_layout_set_spacing (PangoLayout *layout, - int spacing) + int spacing) { g_return_if_fail (layout != NULL); @@ -603,12 +603,12 @@ pango_layout_set_spacing (PangoLayout *layout, /** * pango_layout_get_spacing: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * * Gets the amount of spacing between the lines of the layout. * * Return value: the spacing in Pango units. - **/ + */ int pango_layout_get_spacing (PangoLayout *layout) { @@ -618,31 +618,28 @@ pango_layout_get_spacing (PangoLayout *layout) /** * pango_layout_set_line_spacing: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * @factor: the new line spacing factor * * Sets a factor for line spacing. - * Typical values are: 0, 1, 1.5, 2. - * The default values is 0. * - * If @factor is non-zero, lines are placed - * so that + * Typical values are: 0, 1, 1.5, 2. The default values is 0. * - * baseline2 = baseline1 + factor * height2 + * If @factor is non-zero, lines are placed so that * - * where height2 is the line height of the - * second line (as determined by the font(s)). - * In this case, the spacing set with - * pango_layout_set_spacing() is ignored. + * baseline2 = baseline1 + factor * height2 * - * If @factor is zero, spacing is applied as - * before. + * where height2 is the line height of the second line + * (as determined by the font(s)). In this case, the spacing + * set with [method@Pango.Layout.set_spacing] is ignored. + * + * If @factor is zero, spacing is applied as before. * * Since: 1.44 */ void pango_layout_set_line_spacing (PangoLayout *layout, - float factor) + float factor) { g_return_if_fail (layout != NULL); @@ -655,10 +652,11 @@ pango_layout_set_line_spacing (PangoLayout *layout, /** * pango_layout_get_line_spacing: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` + * + * Gets the line spacing factor of @layout. * - * Gets the value that has been - * set with pango_layout_set_line_spacing(). + * See [method@Pango.Layout.set_line_spacing]. * * Since: 1.44 */ @@ -671,12 +669,12 @@ pango_layout_get_line_spacing (PangoLayout *layout) /** * pango_layout_set_attributes: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * @attrs: (allow-none) (transfer none): a #PangoAttrList, can be %NULL * * Sets the text attributes for a layout object. * References @attrs, so the caller can unref its reference. - **/ + */ void pango_layout_set_attributes (PangoLayout *layout, PangoAttrList *attrs) @@ -698,7 +696,6 @@ pango_layout_set_attributes (PangoLayout *layout, /* We always clear lines such that this function can be called * whenever attrs changes. */ - layout->attrs = attrs; if (layout->attrs) pango_attr_list_ref (layout->attrs); @@ -712,13 +709,13 @@ pango_layout_set_attributes (PangoLayout *layout, /** * pango_layout_get_attributes: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * * Gets the attribute list for the layout, if any. * - * Return value: (transfer none) (nullable): a #PangoAttrList or %NULL + * Return value: (transfer none) (nullable): a `PangoAttrList` or %NULL * if none was set. - **/ + */ PangoAttrList* pango_layout_get_attributes (PangoLayout *layout) { @@ -729,17 +726,18 @@ pango_layout_get_attributes (PangoLayout *layout) /** * pango_layout_set_font_description: - * @layout: a #PangoLayout - * @desc: (allow-none): the new #PangoFontDescription, or %NULL to unset the - * current font description + * @layout: a `PangoLayout` + * @desc: (allow-none): the new `PangoFontDescription`, or %NULL + * to unset the current font description + * + * Sets the default font description for the layout. * - * Sets the default font description for the layout. If no font - * description is set on the layout, the font description from + * If no font description is set on the layout, the font description from * the layout's context is used. - **/ + */ void -pango_layout_set_font_description (PangoLayout *layout, - const PangoFontDescription *desc) +pango_layout_set_font_description (PangoLayout *layout, + const PangoFontDescription *desc) { g_return_if_fail (layout != NULL); @@ -747,7 +745,7 @@ pango_layout_set_font_description (PangoLayout *layout, (!desc || !layout->font_desc || !pango_font_description_equal(desc, layout->font_desc))) { if (layout->font_desc) - pango_font_description_free (layout->font_desc); + pango_font_description_free (layout->font_desc); layout->font_desc = desc ? pango_font_description_copy (desc) : NULL; @@ -758,17 +756,17 @@ pango_layout_set_font_description (PangoLayout *layout, /** * pango_layout_get_font_description: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * * Gets the font description for the layout, if any. * * Return value: (nullable): a pointer to the layout's font - * description, or %NULL if the font description from the layout's - * context is inherited. This value is owned by the layout and must - * not be modified or freed. + * description, or %NULL if the font description from the layout's + * context is inherited. This value is owned by the layout and must + * not be modified or freed. * * Since: 1.8 - **/ + */ const PangoFontDescription * pango_layout_get_font_description (PangoLayout *layout) { @@ -779,21 +777,22 @@ pango_layout_get_font_description (PangoLayout *layout) /** * pango_layout_set_justify: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * @justify: whether the lines in the layout should be justified. * - * Sets whether each complete line should be stretched to - * fill the entire width of the layout. This stretching is typically - * done by adding whitespace, but for some scripts (such as Arabic), - * the justification may be done in more complex ways, like extending - * the characters. + * Sets whether each complete line should be stretched to fill the + * entire width of the layout. * - * Note that this setting is not implemented and so is ignored in Pango - * older than 1.18. - **/ + * Stretching is typically done by adding whitespace, but for some scripts + * (such as Arabic), the justification may be done in more complex ways, + * like extending the characters. + * + * Note that this setting is not implemented and so is ignored in + * Pango older than 1.18. + */ void pango_layout_set_justify (PangoLayout *layout, - gboolean justify) + gboolean justify) { g_return_if_fail (layout != NULL); @@ -802,19 +801,19 @@ pango_layout_set_justify (PangoLayout *layout, layout->justify = justify; if (layout->is_ellipsized || layout->is_wrapped) - layout_changed (layout); + layout_changed (layout); } } /** * pango_layout_get_justify: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * * Gets whether each complete line should be stretched to fill the entire * width of the layout. * * Return value: the justify. - **/ + */ gboolean pango_layout_get_justify (PangoLayout *layout) { @@ -824,32 +823,32 @@ pango_layout_get_justify (PangoLayout *layout) /** * pango_layout_set_auto_dir: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * @auto_dir: if %TRUE, compute the bidirectional base direction * from the layout's contents. * - * Sets whether to calculate the bidirectional base direction - * for the layout according to the contents of the layout; - * when this flag is on (the default), then paragraphs in - @layout that begin with strong right-to-left characters - * (Arabic and Hebrew principally), will have right-to-left - * layout, paragraphs with letters from other scripts will - * have left-to-right layout. Paragraphs with only neutral - * characters get their direction from the surrounding paragraphs. + * Sets whether to calculate the base direction + * for the layout according to its contents. * - * When %FALSE, the choice between left-to-right and - * right-to-left layout is done according to the base direction - * of the layout's #PangoContext. (See pango_context_set_base_dir()). + * When this flag is on (the default), then paragraphs in @layout that + * begin with strong right-to-left characters (Arabic and Hebrew principally), + * will have right-to-left layout, paragraphs with letters from other scripts + * will have left-to-right layout. Paragraphs with only neutral characters + * get their direction from the surrounding paragraphs. + * + * When %FALSE, the choice between left-to-right and right-to-left + * layout is done according to the base direction of the layout's + * `PangoContext`. (See [method@Pango.Context.set_base_dir]). * * When the auto-computed direction of a paragraph differs from the * base direction of the context, the interpretation of * %PANGO_ALIGN_LEFT and %PANGO_ALIGN_RIGHT are swapped. * * Since: 1.4 - **/ + */ void pango_layout_set_auto_dir (PangoLayout *layout, - gboolean auto_dir) + gboolean auto_dir) { g_return_if_fail (PANGO_IS_LAYOUT (layout)); @@ -864,17 +863,18 @@ pango_layout_set_auto_dir (PangoLayout *layout, /** * pango_layout_get_auto_dir: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` + * + * Gets whether to calculate the base direction for the layout + * according to its contents. * - * Gets whether to calculate the bidirectional base direction - * for the layout according to the contents of the layout. - * See pango_layout_set_auto_dir(). + * See [method@Pango.Layout.set_auto_dir]. * * Return value: %TRUE if the bidirectional base direction * is computed from the layout's contents, %FALSE otherwise. * * Since: 1.4 - **/ + */ gboolean pango_layout_get_auto_dir (PangoLayout *layout) { @@ -885,15 +885,15 @@ pango_layout_get_auto_dir (PangoLayout *layout) /** * pango_layout_set_alignment: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * @alignment: the alignment * * Sets the alignment for the layout: how partial lines are * positioned within the horizontal space available. - **/ + */ void pango_layout_set_alignment (PangoLayout *layout, - PangoAlignment alignment) + PangoAlignment alignment) { g_return_if_fail (layout != NULL); @@ -906,13 +906,13 @@ pango_layout_set_alignment (PangoLayout *layout, /** * pango_layout_get_alignment: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * * Gets the alignment for the layout: how partial lines are * positioned within the horizontal space available. * * Return value: the alignment. - **/ + */ PangoAlignment pango_layout_get_alignment (PangoLayout *layout) { @@ -923,17 +923,18 @@ pango_layout_get_alignment (PangoLayout *layout) /** * pango_layout_set_tabs: - * @layout: a #PangoLayout - * @tabs: (allow-none): a #PangoTabArray, or %NULL + * @layout: a `PangoLayout` + * @tabs: (allow-none): a `PangoTabArray`, or %NULL * - * Sets the tabs to use for @layout, overriding the default tabs - * (by default, tabs are every 8 spaces). If @tabs is %NULL, the default - * tabs are reinstated. @tabs is copied into the layout; you must - * free your copy of @tabs yourself. - **/ + * Sets the tabs to use for @layout, overriding the default tabs. + * + * By default, tabs are every 8 spaces. If @tabs is %NULL, the + * default tabs are reinstated. @tabs is copied into the layout; + * you must free your copy of @tabs yourself. + */ void pango_layout_set_tabs (PangoLayout *layout, - PangoTabArray *tabs) + PangoTabArray *tabs) { g_return_if_fail (PANGO_IS_LAYOUT (layout)); @@ -941,7 +942,7 @@ pango_layout_set_tabs (PangoLayout *layout, if (tabs != layout->tabs) { if (layout->tabs) - pango_tab_array_free (layout->tabs); + pango_tab_array_free (layout->tabs); layout->tabs = tabs ? pango_tab_array_copy (tabs) : NULL; @@ -951,16 +952,18 @@ pango_layout_set_tabs (PangoLayout *layout, /** * pango_layout_get_tabs: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * - * Gets the current #PangoTabArray used by this layout. If no - * #PangoTabArray has been set, then the default tabs are in use - * and %NULL is returned. Default tabs are every 8 spaces. - * The return value should be freed with pango_tab_array_free(). + * Gets the current `PangoTabArray` used by this layout. * - * Return value: (nullable): a copy of the tabs for this layout, or - * %NULL. - **/ + * If no `PangoTabArray` has been set, then the default tabs are + * in use and %NULL is returned. Default tabs are every 8 spaces. + * + * The return value should be freed with [method@Pango.TabArray.free]. + * + * Return value: (nullable): a copy of the tabs for this layout, + * or %NULL. + */ PangoTabArray* pango_layout_get_tabs (PangoLayout *layout) { @@ -974,17 +977,19 @@ pango_layout_get_tabs (PangoLayout *layout) /** * pango_layout_set_single_paragraph_mode: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * @setting: new setting * + * Sets the single paragraph mode of @layout. + * * If @setting is %TRUE, do not treat newlines and similar characters * as paragraph separators; instead, keep all text in a single paragraph, * and display a glyph for paragraph separator characters. Used when * you want to allow editing of newlines on a single text line. - **/ + */ void pango_layout_set_single_paragraph_mode (PangoLayout *layout, - gboolean setting) + gboolean setting) { g_return_if_fail (PANGO_IS_LAYOUT (layout)); @@ -999,13 +1004,15 @@ pango_layout_set_single_paragraph_mode (PangoLayout *layout, /** * pango_layout_get_single_paragraph_mode: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` + * + * Obtains whether @layout is in single paragraph mode. * - * Obtains the value set by pango_layout_set_single_paragraph_mode(). + * See [method@Pango.Layout.set_single_paragraph_mode]. * * Return value: %TRUE if the layout does not break paragraphs at * paragraph separator characters, %FALSE otherwise. - **/ + */ gboolean pango_layout_get_single_paragraph_mode (PangoLayout *layout) { @@ -1016,26 +1023,27 @@ pango_layout_get_single_paragraph_mode (PangoLayout *layout) /** * pango_layout_set_ellipsize: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * @ellipsize: the new ellipsization mode for @layout * * Sets the type of ellipsization being performed for @layout. + * * Depending on the ellipsization mode @ellipsize text is * removed from the start, middle, or end of text so they * fit within the width and height of layout set with - * pango_layout_set_width() and pango_layout_set_height(). + * [method@Pango.Layout.set_width] and [method@Pango.Layout.set_height]. * * If the layout contains characters such as newlines that * force it to be layed out in multiple paragraphs, then whether * each paragraph is ellipsized separately or the entire layout * is ellipsized as a whole depends on the set height of the layout. - * See pango_layout_set_height() for details. + * See [method@Pango.Layout.set_height] for details. * * Since: 1.6 - **/ + */ void pango_layout_set_ellipsize (PangoLayout *layout, - PangoEllipsizeMode ellipsize) + PangoEllipsizeMode ellipsize) { g_return_if_fail (PANGO_IS_LAYOUT (layout)); @@ -1044,24 +1052,25 @@ pango_layout_set_ellipsize (PangoLayout *layout, layout->ellipsize = ellipsize; if (layout->is_ellipsized || layout->is_wrapped) - layout_changed (layout); + layout_changed (layout); } } /** * pango_layout_get_ellipsize: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * * Gets the type of ellipsization being performed for @layout. - * See pango_layout_set_ellipsize() * - * Return value: the current ellipsization mode for @layout. + * See [method@Pango.Layout.set_ellipsize]. * - * Use pango_layout_is_ellipsized() to query whether any paragraphs - * were actually ellipsized. + * Use [method@Pango.Layout.is_ellipsized] to query whether any + * paragraphs were actually ellipsized. + * + * Return value: the current ellipsization mode for @layout. * * Since: 1.6 - **/ + */ PangoEllipsizeMode pango_layout_get_ellipsize (PangoLayout *layout) { @@ -1072,7 +1081,7 @@ pango_layout_get_ellipsize (PangoLayout *layout) /** * pango_layout_is_ellipsized: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * * Queries whether the layout had to ellipsize any paragraphs. * @@ -1098,29 +1107,28 @@ pango_layout_is_ellipsized (PangoLayout *layout) /** * pango_layout_set_text: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * @text: the text * @length: maximum length of @text, in bytes. -1 indicates that - * the string is nul-terminated and the length should be - * calculated. The text will also be truncated on - * encountering a nul-termination even when @length is - * positive. + * the string is nul-terminated and the length should be calculated. + * The text will also be truncated on encountering a nul-termination + * even when @length is positive. * * Sets the text of the layout. - * + * * This function validates @text and renders invalid UTF-8 * with a placeholder glyph. * - * Note that if you have used pango_layout_set_markup() or - * pango_layout_set_markup_with_accel() on @layout before, you may - * want to call pango_layout_set_attributes() to clear the attributes - * set on the layout from the markup as this function does not clear - * attributes. - **/ + * Note that if you have used [method@Pango.Layout.set_markup] or + * [method@Pango.Layout.set_markup_with_accel] on @layout before, you + * may want to call [method@Pango.Layout.set_attributes] to clear the + * attributes set on the layout from the markup as this function does + * not clear attributes. + */ void pango_layout_set_text (PangoLayout *layout, - const char *text, - int length) + const char *text, + int length) { char *old_text, *start, *end; @@ -1182,7 +1190,7 @@ pango_layout_set_text (PangoLayout *layout, /** * pango_layout_get_text: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * * Gets the text in the layout. The returned text should not * be freed or modified. @@ -1204,13 +1212,13 @@ pango_layout_get_text (PangoLayout *layout) /** * pango_layout_get_character_count: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * * Returns the number of Unicode characters in the * the text of @layout. * * Return value: the number of Unicode characters - * in the text of @layout + * in the text of @layout * * Since: 1.30 */ @@ -1224,37 +1232,41 @@ pango_layout_get_character_count (PangoLayout *layout) /** * pango_layout_set_markup: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * @markup: marked-up text * @length: length of marked-up text in bytes, or -1 if @markup is - * null-terminated + * null-terminated * - * Same as pango_layout_set_markup_with_accel(), but - * the markup text isn't scanned for accelerators. + * Sets the layout text and attribute list from marked-up text. * - **/ + * See [Pango Markup](pango_markup.html)). + * Replaces the current text and attribute list. + * + * This is the Same as [method@Pango.Layout.set_markup_with_accel], + * but the markup text isn't scanned for accelerators. + */ void pango_layout_set_markup (PangoLayout *layout, - const char *markup, - int length) + const char *markup, + int length) { pango_layout_set_markup_with_accel (layout, markup, length, 0, NULL); } /** * pango_layout_set_markup_with_accel: - * @layout: a #PangoLayout - * @markup: marked-up text - * (see <link linkend="PangoMarkupFormat">markup format</link>) + * @layout: a `PangoLayout` + * @markup: marked-up text (see [Pango Markup](pango_markup.html)) * @length: length of marked-up text in bytes, or -1 if @markup is - * null-terminated + * null-terminated * @accel_marker: marker for accelerators in the text * @accel_char: (out caller-allocates) (allow-none): return location - * for first located accelerator, or %NULL + * for first located accelerator, or %NULL * - * Sets the layout text and attribute list from marked-up text (see - * <link linkend="PangoMarkupFormat">markup format</link>). Replaces - * the current text and attribute list. + * Sets the layout text and attribute list from marked-up text. + * + * See [Pango Markup](pango_markup.html)). + * Replaces the current text and attribute list. * * If @accel_marker is nonzero, the given character will mark the * character following it as an accelerator. For example, @accel_marker @@ -1263,13 +1275,13 @@ pango_layout_set_markup (PangoLayout *layout, * and the first character so marked will be returned in @accel_char. * Two @accel_marker characters following each other produce a single * literal @accel_marker character. - **/ + */ void -pango_layout_set_markup_with_accel (PangoLayout *layout, - const char *markup, - int length, - gunichar accel_marker, - gunichar *accel_char) +pango_layout_set_markup_with_accel (PangoLayout *layout, + const char *markup, + int length, + gunichar accel_marker, + gunichar *accel_char) { PangoAttrList *list = NULL; char *text = NULL; @@ -1280,10 +1292,10 @@ pango_layout_set_markup_with_accel (PangoLayout *layout, error = NULL; if (!pango_parse_markup (markup, length, - accel_marker, - &list, &text, - accel_char, - &error)) + accel_marker, + &list, &text, + accel_char, + &error)) { g_warning ("pango_layout_set_markup_with_accel: %s", error->message); g_error_free (error); @@ -1298,11 +1310,9 @@ pango_layout_set_markup_with_accel (PangoLayout *layout, /** * pango_layout_get_unknown_glyphs_count: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * - * Counts the number unknown glyphs in @layout. That is, zero if - * glyphs for all characters in the layout text were found, or more - * than zero otherwise. + * Counts the number of unknown glyphs in @layout. * * This function can be used to determine if there are any fonts * available to render all characters in a certain string, or when @@ -1332,22 +1342,22 @@ pango_layout_get_unknown_glyphs_count (PangoLayout *layout) lines_list = layout->lines; while (lines_list) { - line = lines_list->data; - runs_list = line->runs; - - while (runs_list) - { - run = runs_list->data; - - for (i = 0; i < run->glyphs->num_glyphs; i++) - { - if (run->glyphs->glyphs[i].glyph & PANGO_GLYPH_UNKNOWN_FLAG) - count++; - } - - runs_list = runs_list->next; - } - lines_list = lines_list->next; + line = lines_list->data; + runs_list = line->runs; + + while (runs_list) + { + run = runs_list->data; + + for (i = 0; i < run->glyphs->num_glyphs; i++) + { + if (run->glyphs->glyphs[i].glyph & PANGO_GLYPH_UNKNOWN_FLAG) + count++; + } + + runs_list = runs_list->next; + } + lines_list = lines_list->next; } layout->unknown_glyphs_count = count; @@ -1376,13 +1386,14 @@ layout_changed (PangoLayout *layout) /** * pango_layout_context_changed: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * - * Forces recomputation of any state in the #PangoLayout that - * might depend on the layout's context. This function should - * be called if you make changes to the context subsequent - * to creating the layout. - **/ + * Forces recomputation of any state in the `PangoLayout` that + * might depend on the layout's context. + * + * This function should be called if you make changes to the context + * subsequent to creating the layout. + */ void pango_layout_context_changed (PangoLayout *layout) { @@ -1394,23 +1405,25 @@ pango_layout_context_changed (PangoLayout *layout) /** * pango_layout_get_serial: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` + * + * Returns the current serial number of @layout. * - * Returns the current serial number of @layout. The serial number is - * initialized to an small number larger than zero when a new layout - * is created and is increased whenever the layout is changed using any - * of the setter functions, or the #PangoContext it uses has changed. - * The serial may wrap, but will never have the value 0. Since it - * can wrap, never compare it with "less than", always use "not equals". + * The serial number is initialized to an small number larger than zero + * when a new layout is created and is increased whenever the layout is + * changed using any of the setter functions, or the `PangoContext` it + * uses has changed. The serial may wrap, but will never have the value 0. + * Since it can wrap, never compare it with "less than", always use "not equals". * - * This can be used to automatically detect changes to a #PangoLayout, and - * is useful for example to decide whether a layout needs redrawing. - * To force the serial to be increased, use pango_layout_context_changed(). + * This can be used to automatically detect changes to a `PangoLayout`, + * and is useful for example to decide whether a layout needs redrawing. + * To force the serial to be increased, use + * [method@Pango.Layout.context_changed]. * * Return value: The current serial number of @layout. * * Since: 1.32.4 - **/ + */ guint pango_layout_get_serial (PangoLayout *layout) { @@ -1420,23 +1433,23 @@ pango_layout_get_serial (PangoLayout *layout) /** * pango_layout_get_log_attrs: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * @attrs: (out)(array length=n_attrs)(transfer container): - * location to store a pointer to an array of logical attributes - * This value must be freed with g_free(). + * location to store a pointer to an array of logical attributes + * This value must be freed with g_free(). * @n_attrs: (out): location to store the number of the attributes in the - * array. (The stored value will be one more than the total number - * of characters in the layout, since there need to be attributes - * corresponding to both the position before the first character - * and the position after the last character.) + * array. (The stored value will be one more than the total number + * of characters in the layout, since there need to be attributes + * corresponding to both the position before the first character + * and the position after the last character.) * * Retrieves an array of logical attributes for each character in * the @layout. - **/ + */ void -pango_layout_get_log_attrs (PangoLayout *layout, - PangoLogAttr **attrs, - gint *n_attrs) +pango_layout_get_log_attrs (PangoLayout *layout, + PangoLogAttr **attrs, + gint *n_attrs) { g_return_if_fail (layout != NULL); @@ -1454,14 +1467,14 @@ pango_layout_get_log_attrs (PangoLayout *layout, /** * pango_layout_get_log_attrs_readonly: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * @n_attrs: (out): location to store the number of the attributes in * the array * * Retrieves an array of logical attributes for each character in * the @layout. * - * This is a faster alternative to pango_layout_get_log_attrs(). + * This is a faster alternative to [method@Pango.Layout.get_log_attrs]. * The returned array is part of @layout and must not be modified. * Modifying the layout will invalidate the returned array. * @@ -1493,12 +1506,12 @@ pango_layout_get_log_attrs_readonly (PangoLayout *layout, /** * pango_layout_get_line_count: - * @layout: #PangoLayout + * @layout: `PangoLayout` * * Retrieves the count of lines for the @layout. * * Return value: the line count. - **/ + */ int pango_layout_get_line_count (PangoLayout *layout) { @@ -1510,18 +1523,18 @@ pango_layout_get_line_count (PangoLayout *layout) /** * pango_layout_get_lines: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * * Returns the lines of the @layout as a list. * - * Use the faster pango_layout_get_lines_readonly() if you do not plan - * to modify the contents of the lines (glyphs, glyph widths, etc.). + * Use the faster [method@Pango.Layout.get_lines_readonly] if you do not + * plan to modify the contents of the lines (glyphs, glyph widths, etc.). * - * Return value: (element-type Pango.LayoutLine) (transfer none): a #GSList containing - * the lines in the layout. This points to internal data of the #PangoLayout - * and must be used with care. It will become invalid on any change to the layout's - * text or properties. - **/ + * Return value: (element-type Pango.LayoutLine) (transfer none): a `GSList` + * containing the lines in the layout. This points to internal data of the + * `PangoLayout` and must be used with care. It will become invalid on any + * change to the layout's text or properties. + */ GSList * pango_layout_get_lines (PangoLayout *layout) { @@ -1531,12 +1544,12 @@ pango_layout_get_lines (PangoLayout *layout) { GSList *tmp_list = layout->lines; while (tmp_list) - { - PangoLayoutLine *line = tmp_list->data; - tmp_list = tmp_list->next; + { + PangoLayoutLine *line = tmp_list->data; + tmp_list = tmp_list->next; - pango_layout_line_leaked (line); - } + pango_layout_line_leaked (line); + } } return layout->lines; @@ -1544,21 +1557,22 @@ pango_layout_get_lines (PangoLayout *layout) /** * pango_layout_get_lines_readonly: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * * Returns the lines of the @layout as a list. * - * This is a faster alternative to pango_layout_get_lines(), - * but the user is not expected - * to modify the contents of the lines (glyphs, glyph widths, etc.). + * This is a faster alternative to [method@Pango.Layout.get_lines], + * but the user is not expected to modify the contents of the lines + * (glyphs, glyph widths, etc.). * - * Return value: (element-type Pango.LayoutLine) (transfer none): a #GSList containing - * the lines in the layout. This points to internal data of the #PangoLayout and - * must be used with care. It will become invalid on any change to the layout's - * text or properties. No changes should be made to the lines. + * Return value: (element-type Pango.LayoutLine) (transfer none): a `GSList` + * containing the lines in the layout. This points to internal data of the + * `PangoLayout` and must be used with care. It will become invalid on any + * change to the layout's text or properties. No changes should be made to + * the lines. * * Since: 1.16 - **/ + */ GSList * pango_layout_get_lines_readonly (PangoLayout *layout) { @@ -1569,24 +1583,23 @@ pango_layout_get_lines_readonly (PangoLayout *layout) /** * pango_layout_get_line: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * @line: the index of a line, which must be between 0 and - * <literal>pango_layout_get_line_count(layout) - 1</literal>, inclusive. + * `pango_layout_get_line_count(layout) - 1`, inclusive. * - * Retrieves a particular line from a #PangoLayout. + * Retrieves a particular line from a `PangoLayout`. * - * Use the faster pango_layout_get_line_readonly() if you do not plan - * to modify the contents of the line (glyphs, glyph widths, etc.). + * Use the faster [method@Pango.Layout.get_line_readonly] if you do not + * plan to modify the contents of the line (glyphs, glyph widths, etc.). * - * Return value: (transfer none) (nullable): the requested - * #PangoLayoutLine, or %NULL if the index is out of - * range. This layout line can be ref'ed and retained, - * but will become invalid if changes are made to the - * #PangoLayout. - **/ + * Return value: (transfer none) (nullable): the requested `PangoLayoutLine`, + * or %NULL if the index is out of range. This layout line can be ref'ed + * and retained, but will become invalid if changes are made to the + * `PangoLayout`. + */ PangoLayoutLine * pango_layout_get_line (PangoLayout *layout, - int line) + int line) { GSList *list_item; g_return_val_if_fail (layout != NULL, NULL); @@ -1611,27 +1624,26 @@ pango_layout_get_line (PangoLayout *layout, /** * pango_layout_get_line_readonly: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * @line: the index of a line, which must be between 0 and - * <literal>pango_layout_get_line_count(layout) - 1</literal>, inclusive. + * `pango_layout_get_line_count(layout) - 1`, inclusive. * - * Retrieves a particular line from a #PangoLayout. + * Retrieves a particular line from a `PangoLayout`. * - * This is a faster alternative to pango_layout_get_line(), - * but the user is not expected - * to modify the contents of the line (glyphs, glyph widths, etc.). + * This is a faster alternative to [method@Pango.Layout.get_line], + * but the user is not expected to modify the contents of the line + * (glyphs, glyph widths, etc.). * - * Return value: (transfer none) (nullable): the requested - * #PangoLayoutLine, or %NULL if the index is out of - * range. This layout line can be ref'ed and retained, - * but will become invalid if changes are made to the - * #PangoLayout. No changes should be made to the line. + * Return value: (transfer none) (nullable): the requested `PangoLayoutLine`, + * or %NULL if the index is out of range. This layout line can be ref'ed + * and retained, but will become invalid if changes are made to the + * `PangoLayout`. No changes should be made to the line. * * Since: 1.16 - **/ + */ PangoLayoutLine * pango_layout_get_line_readonly (PangoLayout *layout, - int line) + int line) { GSList *list_item; g_return_val_if_fail (layout != NULL, NULL); @@ -1654,21 +1666,20 @@ pango_layout_get_line_readonly (PangoLayout *layout, /** * pango_layout_line_index_to_x: - * @line: a #PangoLayoutLine - * @index_: byte offset of a grapheme within the layout + * @line: a `PangoLayoutLine` + * @index_: byte offset of a grapheme within the layout * @trailing: an integer indicating the edge of the grapheme to retrieve - * the position of. If > 0, the trailing edge of the grapheme, - * if 0, the leading of the grapheme. - * @x_pos: (out): location to store the x_offset (in Pango unit) + * the position of. If > 0, the trailing edge of the grapheme, + * if 0, the leading of the grapheme. + * @x_pos: (out): location to store the x_offset (in Pango units) * * Converts an index within a line to a X position. - * - **/ + */ void -pango_layout_line_index_to_x (PangoLayoutLine *line, - int index, - int trailing, - int *x_pos) +pango_layout_line_index_to_x (PangoLayoutLine *line, + int index, + int trailing, + int *x_pos) { PangoLayout *layout = line->layout; GSList *run_list = line->runs; @@ -1679,39 +1690,39 @@ pango_layout_line_index_to_x (PangoLayoutLine *line, PangoLayoutRun *run = run_list->data; if (run->item->offset <= index && run->item->offset + run->item->length > index) - { - int offset = g_utf8_pointer_to_offset (layout->text, layout->text + index); - if (trailing) - { - while (index < line->start_index + line->length && - offset + 1 < layout->n_chars && - !layout->log_attrs[offset + 1].is_cursor_position) - { - offset++; - index = g_utf8_next_char (layout->text + index) - layout->text; - } - } - else - { - while (index > line->start_index && - !layout->log_attrs[offset].is_cursor_position) - { - offset--; - index = g_utf8_prev_char (layout->text + index) - layout->text; - } - - } - - pango_glyph_string_index_to_x (run->glyphs, - layout->text + run->item->offset, - run->item->length, - &run->item->analysis, - index - run->item->offset, trailing, x_pos); - if (x_pos) - *x_pos += width; - - return; - } + { + int offset = g_utf8_pointer_to_offset (layout->text, layout->text + index); + if (trailing) + { + while (index < line->start_index + line->length && + offset + 1 < layout->n_chars && + !layout->log_attrs[offset + 1].is_cursor_position) + { + offset++; + index = g_utf8_next_char (layout->text + index) - layout->text; + } + } + else + { + while (index > line->start_index && + !layout->log_attrs[offset].is_cursor_position) + { + offset--; + index = g_utf8_prev_char (layout->text + index) - layout->text; + } + + } + + pango_glyph_string_index_to_x (run->glyphs, + layout->text + run->item->offset, + run->item->length, + &run->item->analysis, + index - run->item->offset, trailing, x_pos); + if (x_pos) + *x_pos += width; + + return; + } width += pango_glyph_string_get_width (run->glyphs); @@ -1724,10 +1735,10 @@ pango_layout_line_index_to_x (PangoLayoutLine *line, static PangoLayoutLine * pango_layout_index_to_line (PangoLayout *layout, - int index, - int *line_nr, - PangoLayoutLine **line_before, - PangoLayoutLine **line_after) + int index, + int *line_nr, + PangoLayoutLine **line_before, + PangoLayoutLine **line_after) { GSList *tmp_list; GSList *line_list; @@ -1741,7 +1752,7 @@ pango_layout_index_to_line (PangoLayout *layout, PangoLayoutLine *tmp_line = tmp_list->data; if (tmp_line->start_index > index) - break; /* index was in paragraph delimiters */ + break; /* index was in paragraph delimiters */ prev_line = line; line = tmp_line; @@ -1749,7 +1760,7 @@ pango_layout_index_to_line (PangoLayout *layout, i++; if (line->start_index + line->length > index) - break; + break; tmp_list = tmp_list->next; } @@ -1768,8 +1779,8 @@ pango_layout_index_to_line (PangoLayout *layout, static PangoLayoutLine * pango_layout_index_to_line_and_extents (PangoLayout *layout, - int index, - PangoRectangle *line_rect) + int index, + PangoRectangle *line_rect) { PangoLayoutIter iter; PangoLayoutLine *line = NULL; @@ -1779,20 +1790,20 @@ pango_layout_index_to_line_and_extents (PangoLayout *layout, if (!ITER_IS_INVALID (&iter)) while (TRUE) { - PangoLayoutLine *tmp_line = _pango_layout_iter_get_line (&iter); + PangoLayoutLine *tmp_line = _pango_layout_iter_get_line (&iter); - if (tmp_line->start_index > index) - break; /* index was in paragraph delimiters */ + if (tmp_line->start_index > index) + break; /* index was in paragraph delimiters */ - line = tmp_line; + line = tmp_line; - pango_layout_iter_get_line_extents (&iter, NULL, line_rect); + pango_layout_iter_get_line_extents (&iter, NULL, line_rect); - if (line->start_index + line->length > index) - break; + if (line->start_index + line->length > index) + break; - if (!pango_layout_iter_next_line (&iter)) - break; /* Use end of last line */ + if (!pango_layout_iter_next_line (&iter)) + break; /* Use end of last line */ } _pango_layout_iter_destroy (&iter); @@ -1802,25 +1813,26 @@ pango_layout_index_to_line_and_extents (PangoLayout *layout, /** * pango_layout_index_to_line_x: - * @layout: a #PangoLayout - * @index_: the byte index of a grapheme within the layout. - * @trailing: an integer indicating the edge of the grapheme to retrieve the - * position of. If > 0, the trailing edge of the grapheme, if 0, - * the leading of the grapheme. + * @layout: a `PangoLayout` + * @index_: the byte index of a grapheme within the layout. + * @trailing: an integer indicating the edge of the grapheme to retrieve the + * position of. If > 0, the trailing edge of the grapheme, if 0, + * the leading of the grapheme. * @line: (out) (allow-none): location to store resulting line index. (which will - * between 0 and pango_layout_get_line_count(layout) - 1), or %NULL + * between 0 and pango_layout_get_line_count(layout) - 1), or %NULL * @x_pos: (out) (allow-none): location to store resulting position within line - * (%PANGO_SCALE units per device unit), or %NULL + * (%PANGO_SCALE units per device unit), or %NULL * * Converts from byte @index_ within the @layout to line and X position. - * (X position is measured from the left edge of the line) + * + * The X position is measured from the left edge of the line. */ void pango_layout_index_to_line_x (PangoLayout *layout, - int index, - gboolean trailing, - int *line, - int *x_pos) + int index, + gboolean trailing, + int *line, + int *x_pos) { int line_num; PangoLayoutLine *layout_line = NULL; @@ -1832,77 +1844,77 @@ pango_layout_index_to_line_x (PangoLayout *layout, pango_layout_check_lines (layout); layout_line = pango_layout_index_to_line (layout, index, - &line_num, NULL, NULL); + &line_num, NULL, NULL); if (layout_line) { /* use end of line if index was in the paragraph delimiters */ if (index > layout_line->start_index + layout_line->length) - index = layout_line->start_index + layout_line->length; + index = layout_line->start_index + layout_line->length; if (line) - *line = line_num; + *line = line_num; pango_layout_line_index_to_x (layout_line, index, trailing, x_pos); } else { if (line) - *line = -1; + *line = -1; if (x_pos) - *x_pos = -1; + *x_pos = -1; } } /** * pango_layout_move_cursor_visually: - * @layout: a #PangoLayout. - * @strong: whether the moving cursor is the strong cursor or the - * weak cursor. The strong cursor is the cursor corresponding - * to text insertion in the base direction for the layout. + * @layout: a `PangoLayout` + * @strong: whether the moving cursor is the strong cursor or the + * weak cursor. The strong cursor is the cursor corresponding + * to text insertion in the base direction for the layout. * @old_index: the byte index of the grapheme for the old index * @old_trailing: if 0, the cursor was at the leading edge of the - * grapheme indicated by @old_index, if > 0, the cursor - * was at the trailing edge. + * grapheme indicated by @old_index, if > 0, the cursor + * was at the trailing edge. * @direction: direction to move cursor. A negative - * value indicates motion to the left. - * @new_index: (out): location to store the new cursor byte index. A value of -1 - * indicates that the cursor has been moved off the beginning - * of the layout. A value of %G_MAXINT indicates that - * the cursor has been moved off the end of the layout. - * @new_trailing: (out): number of characters to move forward from the - * location returned for @new_index to get the position - * where the cursor should be displayed. This allows - * distinguishing the position at the beginning of one - * line from the position at the end of the preceding - * line. @new_index is always on the line where the - * cursor should be displayed. - * - * Computes a new cursor position from an old position and - * a count of positions to move visually. If @direction is positive, - * then the new strong cursor position will be one position - * to the right of the old cursor position. If @direction is negative, - * then the new strong cursor position will be one position - * to the left of the old cursor position. - * - * In the presence of bidirectional text, the correspondence - * between logical and visual order will depend on the direction - * of the current run, and there may be jumps when the cursor - * is moved off of the end of a run. - * - * Motion here is in cursor positions, not in characters, so a - * single call to pango_layout_move_cursor_visually() may move the - * cursor over multiple characters when multiple characters combine - * to form a single grapheme. - **/ + * value indicates motion to the left. + * @new_index: (out): location to store the new cursor byte index. + * A value of -1 indicates that the cursor has been moved off the + * beginning of the layout. A value of %G_MAXINT indicates that + * the cursor has been moved off the end of the layout. + * @new_trailing: (out): number of characters to move forward from + * the location returned for @new_index to get the position where + * the cursor should be displayed. This allows distinguishing the + * position at the beginning of one line from the position at the + * end of the preceding line. @new_index is always on the line where + * the cursor should be displayed. + * + * Computes a new cursor position from an old position and a count of + * positions to move visually. + * + * If @direction is positive, then the new strong cursor position will be + * one position to the right of the old cursor position. If @direction is + * negative, then the new strong cursor position will be one position to + * the left of the old cursor position. + * + * In the presence of bidirectional text, the correspondence between + * logical and visual order will depend on the direction of the current + * run, and there may be jumps when the cursor is moved off of the end + * of a run. + * + * Motion here is in cursor positions, not in characters, so a single + * call to [method@Pango.Layout.move_cursor_visually] may move the cursor over + * multiple characters when multiple characters combine to form a single + * grapheme. + */ void pango_layout_move_cursor_visually (PangoLayout *layout, - gboolean strong, - int old_index, - int old_trailing, - int direction, - int *new_index, - int *new_trailing) + gboolean strong, + int old_index, + int old_trailing, + int direction, + int *new_index, + int *new_trailing) { PangoLayoutLine *line = NULL; PangoLayoutLine *prev_line; @@ -1928,7 +1940,7 @@ pango_layout_move_cursor_visually (PangoLayout *layout, /* Find the line the old cursor is on */ line = pango_layout_index_to_line (layout, old_index, - NULL, &prev_line, &next_line); + NULL, &prev_line, &next_line); start_offset = g_utf8_pointer_to_offset (layout->text, layout->text + line->start_index); @@ -1950,16 +1962,16 @@ pango_layout_move_cursor_visually (PangoLayout *layout, if (vis_pos == 0 && direction < 0) { if (line->resolved_dir == PANGO_DIRECTION_LTR) - off_start = TRUE; + off_start = TRUE; else - off_end = TRUE; + off_end = TRUE; } else if (vis_pos == n_vis && direction > 0) { if (line->resolved_dir == PANGO_DIRECTION_LTR) - off_end = TRUE; + off_end = TRUE; else - off_start = TRUE; + off_start = TRUE; } if (off_start || off_end) @@ -1970,59 +1982,59 @@ pango_layout_move_cursor_visually (PangoLayout *layout, gboolean paragraph_boundary; if (off_start) - { - if (!prev_line) - { - *new_index = -1; - *new_trailing = 0; - return; - } - line = prev_line; - paragraph_boundary = (line->start_index + line->length != old_index); - } + { + if (!prev_line) + { + *new_index = -1; + *new_trailing = 0; + return; + } + line = prev_line; + paragraph_boundary = (line->start_index + line->length != old_index); + } else - { - if (!next_line) - { - *new_index = G_MAXINT; - *new_trailing = 0; - return; - } - line = next_line; - paragraph_boundary = (line->start_index != old_index); - } + { + if (!next_line) + { + *new_index = G_MAXINT; + *new_trailing = 0; + return; + } + line = next_line; + paragraph_boundary = (line->start_index != old_index); + } n_vis = pango_utf8_strlen (layout->text + line->start_index, line->length); start_offset = g_utf8_pointer_to_offset (layout->text, layout->text + line->start_index); if (vis_pos == 0 && direction < 0) - { - vis_pos = n_vis; - if (paragraph_boundary) - vis_pos++; - } + { + vis_pos = n_vis; + if (paragraph_boundary) + vis_pos++; + } else /* (vis_pos == n_vis && direction > 0) */ - { - vis_pos = 0; - if (paragraph_boundary) - vis_pos--; - } + { + vis_pos = 0; + if (paragraph_boundary) + vis_pos--; + } } vis2log_map = pango_layout_line_get_vis2log_map (line, strong); vis_pos_old = vis_pos + direction; log_pos = g_utf8_pointer_to_offset (layout->text + line->start_index, - layout->text + line->start_index + vis2log_map[vis_pos_old]); + layout->text + line->start_index + vis2log_map[vis_pos_old]); do { vis_pos += direction; log_pos += g_utf8_pointer_to_offset (layout->text + line->start_index + vis2log_map[vis_pos_old], - layout->text + line->start_index + vis2log_map[vis_pos]); + layout->text + line->start_index + vis2log_map[vis_pos]); vis_pos_old = vis_pos; } while (vis_pos > 0 && vis_pos < n_vis && - !layout->log_attrs[start_offset + log_pos].is_cursor_position); + !layout->log_attrs[start_offset + log_pos].is_cursor_position); *new_index = line->start_index + vis2log_map[vis_pos]; g_free (vis2log_map); @@ -2032,45 +2044,45 @@ pango_layout_move_cursor_visually (PangoLayout *layout, if (*new_index == line->start_index + line->length && line->length > 0) { do - { - log_pos--; - *new_index = g_utf8_prev_char (layout->text + *new_index) - layout->text; - (*new_trailing)++; - } + { + log_pos--; + *new_index = g_utf8_prev_char (layout->text + *new_index) - layout->text; + (*new_trailing)++; + } while (log_pos > 0 && !layout->log_attrs[start_offset + log_pos].is_cursor_position); } } /** * pango_layout_xy_to_index: - * @layout: a #PangoLayout - * @x: the X offset (in Pango units) - * from the left edge of the layout. - * @y: the Y offset (in Pango units) - * from the top edge of the layout - * @index_: (out): location to store calculated byte index + * @layout: a `PangoLayout` + * @x: the X offset (in Pango units) from the left edge of the layout. + * @y: the Y offset (in Pango units) from the top edge of the layout + * @index_: (out): location to store calculated byte index * @trailing: (out): location to store a integer indicating where - * in the grapheme the user clicked. It will either - * be zero, or the number of characters in the - * grapheme. 0 represents the leading edge of the grapheme. - * - * Converts from X and Y position within a layout to the byte - * index to the character at that logical position. If the - * Y position is not inside the layout, the closest position is chosen - * (the position will be clamped inside the layout). If the - * X position is not within the layout, then the start or the - * end of the line is chosen as described for pango_layout_line_x_to_index(). - * If either the X or Y positions were not inside the layout, then the - * function returns %FALSE; on an exact hit, it returns %TRUE. + * in the grapheme the user clicked. It will either be zero, or the + * number of characters in the grapheme. 0 represents the leading edge + * of the grapheme. + * + * Converts from X and Y position within a layout to the byte index to the + * character at that logical position. + * + * If the Y position is not inside the + * layout, the closest position is chosen (the position will be clamped + * inside the layout). If the X position is not within the layout, then + * the start or the end of the line is chosen as described for + * [method@Pango.LayoutLine.x_to_index]. If either the X or Y positions + * were not inside the layout, then the function returns %FALSE; on an + * exact hit, it returns %TRUE. * * Return value: %TRUE if the coordinates were inside text, %FALSE otherwise. - **/ + */ gboolean pango_layout_xy_to_index (PangoLayout *layout, - int x, - int y, - int *index, - gint *trailing) + int x, + int y, + int *index, + gint *trailing) { PangoLayoutIter iter; PangoLayoutLine *prev_line = NULL; @@ -2096,34 +2108,34 @@ pango_layout_xy_to_index (PangoLayout *layout, pango_layout_iter_get_line_yrange (&iter, &first_y, &last_y); if (y < first_y) - { - if (prev_line && y < (prev_last + (first_y - prev_last) / 2)) - { - found = prev_line; - found_line_x = prev_line_x; - } - else - { - if (prev_line == NULL) - outside = TRUE; /* off the top */ - - found = _pango_layout_iter_get_line (&iter); - found_line_x = x - line_logical.x; - } - } + { + if (prev_line && y < (prev_last + (first_y - prev_last) / 2)) + { + found = prev_line; + found_line_x = prev_line_x; + } + else + { + if (prev_line == NULL) + outside = TRUE; /* off the top */ + + found = _pango_layout_iter_get_line (&iter); + found_line_x = x - line_logical.x; + } + } else if (y >= first_y && - y < last_y) - { - found = _pango_layout_iter_get_line (&iter); - found_line_x = x - line_logical.x; - } + y < last_y) + { + found = _pango_layout_iter_get_line (&iter); + found_line_x = x - line_logical.x; + } prev_line = _pango_layout_iter_get_line (&iter); prev_last = last_y; prev_line_x = x - line_logical.x; if (found != NULL) - break; + break; } while (pango_layout_iter_next_line (&iter)); @@ -2139,8 +2151,8 @@ pango_layout_xy_to_index (PangoLayout *layout, } retval = pango_layout_line_x_to_index (found, - found_line_x, - index, trailing); + found_line_x, + index, trailing); if (outside) retval = FALSE; @@ -2150,21 +2162,22 @@ pango_layout_xy_to_index (PangoLayout *layout, /** * pango_layout_index_to_pos: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * @index_: byte index within @layout * @pos: (out): rectangle in which to store the position of the grapheme * - * Converts from an index within a #PangoLayout to the onscreen position - * corresponding to the grapheme at that index, which is represented - * as rectangle. Note that <literal>pos->x</literal> is always the leading - * edge of the grapheme and <literal>pos->x + pos->width</literal> the trailing - * edge of the grapheme. If the directionality of the grapheme is right-to-left, - * then <literal>pos->width</literal> will be negative. - **/ + * Converts from an index within a `PangoLayout` to the onscreen position + * corresponding to the grapheme at that index. + * + * The return value is represented as rectangle. Note that `pos->x` is + * always the leading edge of the grapheme and `pos->x + pos->width` the + * trailing edge of the grapheme. If the directionality of the grapheme + * is right-to-left, then `pos->width` will be negative. + */ void pango_layout_index_to_pos (PangoLayout *layout, - int index, - PangoRectangle *pos) + int index, + PangoRectangle *pos) { PangoRectangle logical_rect; PangoLayoutIter iter; @@ -2180,35 +2193,35 @@ pango_layout_index_to_pos (PangoLayout *layout, if (!ITER_IS_INVALID (&iter)) { while (TRUE) - { - PangoLayoutLine *tmp_line = _pango_layout_iter_get_line (&iter); - - if (tmp_line->start_index > index) - { - /* index is in the paragraph delim&iters, move to - * end of previous line - * - * This shouldn’t occur in the first loop &iteration as the first - * line’s start_index should always be 0. - */ - g_assert (layout_line != NULL); - index = layout_line->start_index + layout_line->length; - break; - } - - layout_line = tmp_line; - - pango_layout_iter_get_line_extents (&iter, NULL, &logical_rect); - - if (layout_line->start_index + layout_line->length > index) - break; - - if (!pango_layout_iter_next_line (&iter)) - { - index = layout_line->start_index + layout_line->length; - break; - } - } + { + PangoLayoutLine *tmp_line = _pango_layout_iter_get_line (&iter); + + if (tmp_line->start_index > index) + { + /* index is in the paragraph delim&iters, move to + * end of previous line + * + * This shouldn’t occur in the first loop &iteration as the first + * line’s start_index should always be 0. + */ + g_assert (layout_line != NULL); + index = layout_line->start_index + layout_line->length; + break; + } + + layout_line = tmp_line; + + pango_layout_iter_get_line_extents (&iter, NULL, &logical_rect); + + if (layout_line->start_index + layout_line->length > index) + break; + + if (!pango_layout_iter_next_line (&iter)) + { + index = layout_line->start_index + layout_line->length; + break; + } + } pos->y = logical_rect.y; pos->height = logical_rect.height; @@ -2217,12 +2230,12 @@ pango_layout_index_to_pos (PangoLayout *layout, pos->x = logical_rect.x + x_pos; if (index < layout_line->start_index + layout_line->length) - { - pango_layout_line_index_to_x (layout_line, index, 1, &x_pos); - pos->width = (logical_rect.x + x_pos) - pos->x; - } + { + pango_layout_line_index_to_x (layout_line, index, 1, &x_pos); + pos->width = (logical_rect.x + x_pos) - pos->x; + } else - pos->width = 0; + pos->width = 0; } _pango_layout_iter_destroy (&iter); @@ -2230,8 +2243,8 @@ pango_layout_index_to_pos (PangoLayout *layout, static void pango_layout_line_get_range (PangoLayoutLine *line, - char **start, - char **end) + char **start, + char **end) { char *p; @@ -2245,7 +2258,7 @@ pango_layout_line_get_range (PangoLayoutLine *line, static int * pango_layout_line_get_vis2log_map (PangoLayoutLine *line, - gboolean strong) + gboolean strong) { PangoLayout *layout = line->layout; PangoDirection prev_dir; @@ -2286,39 +2299,39 @@ pango_layout_line_get_vis2log_map (PangoLayoutLine *line, /* p is the logical byte index at the start of the run */ if (run_dir == PANGO_DIRECTION_LTR) - { - if ((cursor_dir == PANGO_DIRECTION_LTR) || - (prev_dir == run_dir)) - result[pos] = p - start; - - p = g_utf8_next_char (p); - - for (i = 1; i < run_n_chars; i++) - { - result[pos + i] = p - start; - p = g_utf8_next_char (p); - } - - if (cursor_dir == PANGO_DIRECTION_LTR) - result[pos + run_n_chars] = p - start; - } + { + if ((cursor_dir == PANGO_DIRECTION_LTR) || + (prev_dir == run_dir)) + result[pos] = p - start; + + p = g_utf8_next_char (p); + + for (i = 1; i < run_n_chars; i++) + { + result[pos + i] = p - start; + p = g_utf8_next_char (p); + } + + if (cursor_dir == PANGO_DIRECTION_LTR) + result[pos + run_n_chars] = p - start; + } else - { - if (cursor_dir == PANGO_DIRECTION_RTL) - result[pos + run_n_chars] = p - start; + { + if (cursor_dir == PANGO_DIRECTION_RTL) + result[pos + run_n_chars] = p - start; - p = g_utf8_next_char (p); + p = g_utf8_next_char (p); - for (i = 1; i < run_n_chars; i++) - { - result[pos + run_n_chars - i] = p - start; - p = g_utf8_next_char (p); - } + for (i = 1; i < run_n_chars; i++) + { + result[pos + run_n_chars - i] = p - start; + p = g_utf8_next_char (p); + } - if ((cursor_dir == PANGO_DIRECTION_RTL) || - (prev_dir == run_dir)) - result[pos] = p - start; - } + if ((cursor_dir == PANGO_DIRECTION_RTL) || + (prev_dir == run_dir)) + result[pos] = p - start; + } pos += run_n_chars; prev_dir = run_dir; @@ -2335,7 +2348,7 @@ pango_layout_line_get_vis2log_map (PangoLayoutLine *line, static int * pango_layout_line_get_log2vis_map (PangoLayoutLine *line, - gboolean strong) + gboolean strong) { gchar *start, *end; int *reverse_map; @@ -2359,7 +2372,7 @@ pango_layout_line_get_log2vis_map (PangoLayoutLine *line, static PangoDirection pango_layout_line_get_char_direction (PangoLayoutLine *layout_line, - int index) + int index) { GSList *run_list; @@ -2369,7 +2382,7 @@ pango_layout_line_get_char_direction (PangoLayoutLine *layout_line, PangoLayoutRun *run = run_list->data; if (run->item->offset <= index && run->item->offset + run->item->length > index) - return run->item->analysis.level % 2 ? PANGO_DIRECTION_RTL : PANGO_DIRECTION_LTR; + return run->item->analysis.level % 2 ? PANGO_DIRECTION_RTL : PANGO_DIRECTION_LTR; run_list = run_list->next; } @@ -2381,11 +2394,10 @@ pango_layout_line_get_char_direction (PangoLayoutLine *layout_line, /** * pango_layout_get_direction: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * @index: the byte index of the char * - * Gets the text direction at the given character - * position in @layout. + * Gets the text direction at the given character position in @layout. * * Returns: the text direction at @index * @@ -2407,26 +2419,27 @@ pango_layout_get_direction (PangoLayout *layout, /** * pango_layout_get_cursor_pos: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * @index_: the byte index of the cursor - * @strong_pos: (out) (allow-none): location to store the strong cursor position - * (may be %NULL) - * @weak_pos: (out) (allow-none): location to store the weak cursor position (may be %NULL) + * @strong_pos: (out) (allow-none): location to store the strong + * cursor position (may be %NULL) + * @weak_pos: (out) (allow-none): location to store the weak cursor + * position (may be %NULL) * * Given an index within a layout, determines the positions that of the - * strong and weak cursors if the insertion point is at that - * index. The position of each cursor is stored as a zero-width - * rectangle. The strong cursor location is the location where - * characters of the directionality equal to the base direction of the - * layout are inserted. The weak cursor location is the location - * where characters of the directionality opposite to the base - * direction of the layout are inserted. - **/ + * strong and weak cursors if the insertion point is at that index. + * + * The position of each cursor is stored as a zero-width rectangle. + * The strong cursor location is the location where characters of the + * directionality equal to the base direction of the layout are inserted. + * The weak cursor location is the location where characters of the + * directionality opposite to the base direction of the layout are inserted. + */ void pango_layout_get_cursor_pos (PangoLayout *layout, - int index, - PangoRectangle *strong_pos, - PangoRectangle *weak_pos) + int index, + PangoRectangle *strong_pos, + PangoRectangle *weak_pos) { PangoDirection dir1; PangoRectangle line_rect; @@ -2438,7 +2451,7 @@ pango_layout_get_cursor_pos (PangoLayout *layout, g_return_if_fail (index >= 0 && index <= layout->length); layout_line = pango_layout_index_to_line_and_extents (layout, index, - &line_rect); + &line_rect); g_assert (index >= layout_line->start_index); @@ -2447,17 +2460,17 @@ pango_layout_get_cursor_pos (PangoLayout *layout, { dir1 = layout_line->resolved_dir; if (layout_line->resolved_dir == PANGO_DIRECTION_LTR) - x1_trailing = 0; + x1_trailing = 0; else - x1_trailing = line_rect.width; + x1_trailing = line_rect.width; } else if (index >= layout_line->start_index + layout_line->length) { dir1 = layout_line->resolved_dir; if (layout_line->resolved_dir == PANGO_DIRECTION_LTR) - x1_trailing = line_rect.width; + x1_trailing = line_rect.width; else - x1_trailing = 0; + x1_trailing = 0; } else { @@ -2470,9 +2483,9 @@ pango_layout_get_cursor_pos (PangoLayout *layout, if (index >= layout_line->start_index + layout_line->length) { if (layout_line->resolved_dir == PANGO_DIRECTION_LTR) - x2 = line_rect.width; + x2 = line_rect.width; else - x2 = 0; + x2 = 0; } else { @@ -2484,9 +2497,9 @@ pango_layout_get_cursor_pos (PangoLayout *layout, strong_pos->x = line_rect.x; if (dir1 == layout_line->resolved_dir) - strong_pos->x += x1_trailing; + strong_pos->x += x1_trailing; else - strong_pos->x += x2; + strong_pos->x += x2; strong_pos->y = line_rect.y; strong_pos->width = 0; @@ -2498,9 +2511,9 @@ pango_layout_get_cursor_pos (PangoLayout *layout, weak_pos->x = line_rect.x; if (dir1 == layout_line->resolved_dir) - weak_pos->x += x2; + weak_pos->x += x2; else - weak_pos->x += x1_trailing; + weak_pos->x += x1_trailing; weak_pos->y = line_rect.y; weak_pos->width = 0; @@ -2531,7 +2544,7 @@ direction_simple (PangoDirection d) static PangoAlignment get_alignment (PangoLayout *layout, - PangoLayoutLine *line) + PangoLayoutLine *line) { PangoAlignment alignment = layout->alignment; @@ -2540,9 +2553,9 @@ get_alignment (PangoLayout *layout, -direction_simple (pango_context_get_base_dir (layout->context))) { if (alignment == PANGO_ALIGN_LEFT) - alignment = PANGO_ALIGN_RIGHT; + alignment = PANGO_ALIGN_RIGHT; else if (alignment == PANGO_ALIGN_RIGHT) - alignment = PANGO_ALIGN_LEFT; + alignment = PANGO_ALIGN_LEFT; } return alignment; @@ -2550,10 +2563,10 @@ get_alignment (PangoLayout *layout, static void get_x_offset (PangoLayout *layout, - PangoLayoutLine *line, - int layout_width, - int line_width, - int *x_offset) + PangoLayoutLine *line, + int layout_width, + int line_width, + int *x_offset) { PangoAlignment alignment = get_alignment (layout, line); @@ -2567,14 +2580,13 @@ get_x_offset (PangoLayout *layout, /* hinting */ if (((layout_width | line_width) & (PANGO_SCALE - 1)) == 0) { - *x_offset = PANGO_UNITS_ROUND (*x_offset); + *x_offset = PANGO_UNITS_ROUND (*x_offset); } } else *x_offset = 0; /* Indentation */ - /* For center, we ignore indentation; I think I've seen word * processors that still do the indentation here as if it were * indented left/right, though we can't sensibly do that without @@ -2587,22 +2599,22 @@ get_x_offset (PangoLayout *layout, if (line->is_paragraph_start) { if (layout->indent > 0) - { - if (alignment == PANGO_ALIGN_LEFT) - *x_offset += layout->indent; - else - *x_offset -= layout->indent; - } + { + if (alignment == PANGO_ALIGN_LEFT) + *x_offset += layout->indent; + else + *x_offset -= layout->indent; + } } else { if (layout->indent < 0) - { - if (alignment == PANGO_ALIGN_LEFT) - *x_offset -= layout->indent; - else - *x_offset += layout->indent; - } + { + if (alignment == PANGO_ALIGN_LEFT) + *x_offset -= layout->indent; + else + *x_offset += layout->indent; + } } } @@ -2613,12 +2625,12 @@ pango_layout_line_get_extents_and_height (PangoLayoutLine *line, int *height); static void get_line_extents_layout_coords (PangoLayout *layout, - PangoLayoutLine *line, - int layout_width, - int y_offset, - int *baseline, - PangoRectangle *line_ink_layout, - PangoRectangle *line_logical_layout) + PangoLayoutLine *line, + int layout_width, + int y_offset, + int *baseline, + PangoRectangle *line_ink_layout, + PangoRectangle *line_logical_layout) { int x_offset; /* Line extents in line coords (origin at line baseline) */ @@ -2668,8 +2680,8 @@ get_line_extents_layout_coords (PangoLayout *layout, */ static void pango_layout_get_extents_internal (PangoLayout *layout, - PangoRectangle *ink_rect, - PangoRectangle *logical_rect, + PangoRectangle *ink_rect, + PangoRectangle *logical_rect, Extents **line_extents) { GSList *line_list; @@ -2710,14 +2722,14 @@ pango_layout_get_extents_internal (PangoLayout *layout, */ line_list = layout->lines; while (line_list && !need_width) - { - PangoLayoutLine *line = line_list->data; + { + PangoLayoutLine *line = line_list->data; - if (get_alignment (layout, line) != PANGO_ALIGN_LEFT) - need_width = TRUE; + if (get_alignment (layout, line) != PANGO_ALIGN_LEFT) + need_width = TRUE; - line_list = line_list->next; - } + line_list = line_list->next; + } } else if (layout->alignment != PANGO_ALIGN_LEFT) need_width = TRUE; @@ -2757,79 +2769,79 @@ pango_layout_get_extents_internal (PangoLayout *layout, /* This block gets the line extents in layout coords */ { - get_line_extents_layout_coords (layout, line, - width, y_offset, - &baseline, - ink_rect ? &line_ink_layout : NULL, - &line_logical_layout); - - if (line_extents && layout->line_count > 0) - { - Extents *ext = &(*line_extents)[line_index]; - ext->baseline = baseline; - ext->ink_rect = line_ink_layout; - ext->logical_rect = line_logical_layout; - } + get_line_extents_layout_coords (layout, line, + width, y_offset, + &baseline, + ink_rect ? &line_ink_layout : NULL, + &line_logical_layout); + + if (line_extents && layout->line_count > 0) + { + Extents *ext = &(*line_extents)[line_index]; + ext->baseline = baseline; + ext->ink_rect = line_ink_layout; + ext->logical_rect = line_logical_layout; + } } if (ink_rect) - { - /* Compute the union of the current ink_rect with - * line_ink_layout - */ - - if (line_list == layout->lines) - { - *ink_rect = line_ink_layout; - } - else - { - new_pos = MIN (ink_rect->x, line_ink_layout.x); - ink_rect->width = - MAX (ink_rect->x + ink_rect->width, - line_ink_layout.x + line_ink_layout.width) - new_pos; - ink_rect->x = new_pos; - - new_pos = MIN (ink_rect->y, line_ink_layout.y); - ink_rect->height = - MAX (ink_rect->y + ink_rect->height, - line_ink_layout.y + line_ink_layout.height) - new_pos; - ink_rect->y = new_pos; - } - } + { + /* Compute the union of the current ink_rect with + * line_ink_layout + */ + + if (line_list == layout->lines) + { + *ink_rect = line_ink_layout; + } + else + { + new_pos = MIN (ink_rect->x, line_ink_layout.x); + ink_rect->width = + MAX (ink_rect->x + ink_rect->width, + line_ink_layout.x + line_ink_layout.width) - new_pos; + ink_rect->x = new_pos; + + new_pos = MIN (ink_rect->y, line_ink_layout.y); + ink_rect->height = + MAX (ink_rect->y + ink_rect->height, + line_ink_layout.y + line_ink_layout.height) - new_pos; + ink_rect->y = new_pos; + } + } if (logical_rect) - { - if (layout->width == -1) - { - /* When no width is set on layout, we can just compute the max of the - * line lengths to get the horizontal extents ... logical_rect.x = 0. - */ - logical_rect->width = MAX (logical_rect->width, line_logical_layout.width); - } - else - { - /* When a width is set, we have to compute the union of the horizontal - * extents of all the lines. - */ - if (line_list == layout->lines) - { - logical_rect->x = line_logical_layout.x; - logical_rect->width = line_logical_layout.width; - } - else - { - new_pos = MIN (logical_rect->x, line_logical_layout.x); - logical_rect->width = - MAX (logical_rect->x + logical_rect->width, - line_logical_layout.x + line_logical_layout.width) - new_pos; - logical_rect->x = new_pos; - - } - } - - logical_rect->height = line_logical_layout.y + line_logical_layout.height - logical_rect->y; - } + { + if (layout->width == -1) + { + /* When no width is set on layout, we can just compute the max of the + * line lengths to get the horizontal extents ... logical_rect.x = 0. + */ + logical_rect->width = MAX (logical_rect->width, line_logical_layout.width); + } + else + { + /* When a width is set, we have to compute the union of the horizontal + * extents of all the lines. + */ + if (line_list == layout->lines) + { + logical_rect->x = line_logical_layout.x; + logical_rect->width = line_logical_layout.width; + } + else + { + new_pos = MIN (logical_rect->x, line_logical_layout.x); + logical_rect->width = + MAX (logical_rect->x + logical_rect->width, + line_logical_layout.x + line_logical_layout.width) - new_pos; + logical_rect->x = new_pos; + + } + } + + logical_rect->height = line_logical_layout.y + line_logical_layout.height - logical_rect->y; + } y_offset = line_logical_layout.y + line_logical_layout.height + layout->spacing; line_list = line_list->next; @@ -2850,28 +2862,27 @@ pango_layout_get_extents_internal (PangoLayout *layout, /** * pango_layout_get_extents: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * @ink_rect: (out) (allow-none): rectangle used to store the extents of the - * layout as drawn or %NULL to indicate that the result is - * not needed. + * layout 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 layout or %NULL to indicate that the - * result is not needed. + * extents of the layout or %NULL to indicate that the result is not needed. + * + * Computes the logical and ink extents of @layout. * - * Computes the logical and ink extents of @layout. Logical extents - * are usually what you want for positioning things. Note that both extents - * may have non-zero x and y. You may want to use those to offset where you - * render the layout. Not doing that is a very typical bug that shows up as - * right-to-left layouts not being correctly positioned in a layout with - * a set width. + * Logical extents are usually what you want for positioning things. Note + * that both extents may have non-zero x and y. You may want to use those + * to offset where you render the layout. Not doing that is a very typical + * bug that shows up as right-to-left layouts not being correctly positioned + * in a layout with a set width. * * The extents are given in layout coordinates and in Pango units; layout * coordinates begin at the top left corner of the layout. */ void pango_layout_get_extents (PangoLayout *layout, - PangoRectangle *ink_rect, - PangoRectangle *logical_rect) + PangoRectangle *ink_rect, + PangoRectangle *logical_rect) { g_return_if_fail (layout != NULL); @@ -2880,24 +2891,23 @@ pango_layout_get_extents (PangoLayout *layout, /** * pango_layout_get_pixel_extents: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * @ink_rect: (out) (allow-none): rectangle used to store the extents of the - * layout as drawn or %NULL to indicate that the result is - * not needed. + * layout 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 layout or %NULL to indicate that the - * result is not needed. + * extents of the layout or %NULL to indicate that the result is not needed. * * Computes the logical and ink extents of @layout in device units. - * This function just calls pango_layout_get_extents() followed by - * two pango_extents_to_pixels() calls, rounding @ink_rect and @logical_rect + * + * This function just calls [method@Pango.Layout.get_extents] followed by + * two [func@extents_to_pixels] calls, rounding @ink_rect and @logical_rect * such that the rounded rectangles fully contain the unrounded one (that is, - * passes them as first argument to pango_extents_to_pixels()). - **/ + * passes them as first argument to `pango_extents_to_pixels()`). + */ void -pango_layout_get_pixel_extents (PangoLayout *layout, - PangoRectangle *ink_rect, - PangoRectangle *logical_rect) +pango_layout_get_pixel_extents (PangoLayout *layout, + PangoRectangle *ink_rect, + PangoRectangle *logical_rect) { g_return_if_fail (PANGO_IS_LAYOUT (layout)); @@ -2908,18 +2918,19 @@ pango_layout_get_pixel_extents (PangoLayout *layout, /** * pango_layout_get_size: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * @width: (out) (allow-none): location to store the logical width, or %NULL * @height: (out) (allow-none): location to store the logical height, or %NULL * - * Determines the logical width and height of a #PangoLayout - * in Pango units (device units scaled by %PANGO_SCALE). This - * is simply a convenience function around pango_layout_get_extents(). - **/ + * Determines the logical width and height of a `PangoLayout` in Pango + * units. + * + * This is simply a convenience function around [method@Pango.Layout.get_extents]. + */ void pango_layout_get_size (PangoLayout *layout, - int *width, - int *height) + int *width, + int *height) { PangoRectangle logical_rect; @@ -2933,20 +2944,21 @@ pango_layout_get_size (PangoLayout *layout, /** * pango_layout_get_pixel_size: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * @width: (out) (allow-none): location to store the logical width, or %NULL * @height: (out) (allow-none): location to store the logical height, or %NULL * - * Determines the logical width and height of a #PangoLayout - * in device units. (pango_layout_get_size() returns the width - * and height scaled by %PANGO_SCALE.) This - * is simply a convenience function around - * pango_layout_get_pixel_extents(). - **/ + * Determines the logical width and height of a `PangoLayout` in device + * units. + * + * [method@Pango.Layout.get_size] returns the width and height + * scaled by %PANGO_SCALE. This is simply a convenience function around + * [method@Pango.Layout.get_pixel_extents]. + */ void pango_layout_get_pixel_size (PangoLayout *layout, - int *width, - int *height) + int *width, + int *height) { PangoRectangle logical_rect; @@ -2961,16 +2973,16 @@ pango_layout_get_pixel_size (PangoLayout *layout, /** * pango_layout_get_baseline: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * * Gets the Y position of baseline of the first line in @layout. * * Return value: baseline of first line, from top of @layout. * * Since: 1.22 - **/ + */ int -pango_layout_get_baseline (PangoLayout *layout) +pango_layout_get_baseline (PangoLayout *layout) { int baseline; Extents *extents = NULL; @@ -2991,13 +3003,13 @@ pango_layout_clear_lines (PangoLayout *layout) { GSList *tmp_list = layout->lines; while (tmp_list) - { - PangoLayoutLine *line = tmp_list->data; - tmp_list = tmp_list->next; + { + PangoLayoutLine *line = tmp_list->data; + tmp_list = tmp_list->next; - line->layout = NULL; - pango_layout_line_unref (line); - } + line->layout = NULL; + pango_layout_line_unref (line); + } g_slist_free (layout->lines); layout->lines = NULL; @@ -3038,7 +3050,7 @@ pango_layout_line_leaked (PangoLayoutLine *line) static void shape_tab (PangoLayoutLine *line, PangoItem *item, - PangoGlyphString *glyphs); + PangoGlyphString *glyphs); static void free_run (PangoLayoutRun *run, gpointer data) @@ -3138,7 +3150,7 @@ ensure_tab_width (PangoLayout *layout) * problems with the font. */ if (layout->tab_width <= 0) - layout->tab_width = 50 * PANGO_SCALE; /* pretty much arbitrary */ + layout->tab_width = 50 * PANGO_SCALE; /* pretty much arbitrary */ } } @@ -3146,7 +3158,9 @@ ensure_tab_width (PangoLayout *layout) * all tabs are left-aligned. */ static int -get_tab_pos (PangoLayout *layout, int index, gboolean *is_default) +get_tab_pos (PangoLayout *layout, + int index, + gboolean *is_default) { gint n_tabs; gboolean in_pixels; @@ -3156,14 +3170,14 @@ get_tab_pos (PangoLayout *layout, int index, gboolean *is_default) n_tabs = pango_tab_array_get_size (layout->tabs); in_pixels = pango_tab_array_get_positions_in_pixels (layout->tabs); if (is_default) - *is_default = FALSE; + *is_default = FALSE; } else { n_tabs = 0; in_pixels = FALSE; if (is_default) - *is_default = TRUE; + *is_default = TRUE; } if (index < n_tabs) @@ -3173,9 +3187,9 @@ get_tab_pos (PangoLayout *layout, int index, gboolean *is_default) pango_tab_array_get_tab (layout->tabs, index, NULL, &pos); if (in_pixels) - return pos * PANGO_SCALE; + return pos * PANGO_SCALE; else - return pos; + return pos; } if (n_tabs > 0) @@ -3190,24 +3204,24 @@ get_tab_pos (PangoLayout *layout, int index, gboolean *is_default) pango_tab_array_get_tab (layout->tabs, n_tabs - 1, NULL, &last_pos); if (n_tabs > 1) - pango_tab_array_get_tab (layout->tabs, n_tabs - 2, NULL, &next_to_last_pos); + pango_tab_array_get_tab (layout->tabs, n_tabs - 2, NULL, &next_to_last_pos); else - next_to_last_pos = 0; + next_to_last_pos = 0; if (in_pixels) - { - next_to_last_pos *= PANGO_SCALE; - last_pos *= PANGO_SCALE; - } + { + next_to_last_pos *= PANGO_SCALE; + last_pos *= PANGO_SCALE; + } if (last_pos > next_to_last_pos) - { - tab_width = last_pos - next_to_last_pos; - } + { + tab_width = last_pos - next_to_last_pos; + } else - { - tab_width = layout->tab_width; - } + { + tab_width = layout->tab_width; + } return last_pos + tab_width * (index - n_tabs + 1); } @@ -3234,7 +3248,7 @@ line_width (PangoLayoutLine *line) PangoLayoutRun *run = l->data; for (i=0; i < run->glyphs->num_glyphs; i++) - width += run->glyphs->glyphs[i].geometry.width; + width += run->glyphs->glyphs[i].geometry.width; } return width; @@ -3260,7 +3274,7 @@ showing_space (const PangoAnalysis *analysis) static void shape_tab (PangoLayoutLine *line, PangoItem *item, - PangoGlyphString *glyphs) + PangoGlyphString *glyphs) { int i, space_width; @@ -3292,17 +3306,17 @@ shape_tab (PangoLayoutLine *line, * the pixel. */ if (tab_pos >= current_width + (is_default ? space_width : 1)) - { - glyphs->glyphs[0].geometry.width = tab_pos - current_width; - break; - } + { + glyphs->glyphs[0].geometry.width = tab_pos - current_width; + break; + } } } static inline gboolean can_break_at (PangoLayout *layout, - gint offset, - gboolean always_wrap_char) + gint offset, + gboolean always_wrap_char) { PangoWrapMode wrap; /* We probably should have a mode where we treat all white-space as @@ -3329,9 +3343,9 @@ can_break_at (PangoLayout *layout, static inline gboolean can_break_in (PangoLayout *layout, - int start_offset, - int num_chars, - gboolean allow_break_at_start) + int start_offset, + int num_chars, + gboolean allow_break_at_start) { int i; @@ -3344,8 +3358,8 @@ can_break_in (PangoLayout *layout, static inline void distribute_letter_spacing (int letter_spacing, - int *space_left, - int *space_right) + int *space_left, + int *space_right) { *space_left = letter_spacing / 2; /* hinting */ @@ -3368,41 +3382,41 @@ typedef enum struct _ParaBreakState { /* maintained per layout */ - int line_height; /* Estimate of height of current line; < 0 is no estimate */ - int remaining_height; /* Remaining height of the layout; only defined if layout->height >= 0 */ + int line_height; /* Estimate of height of current line; < 0 is no estimate */ + int remaining_height; /* Remaining height of the layout; only defined if layout->height >= 0 */ /* maintained per paragraph */ - PangoAttrList *attrs; /* Attributes being used for itemization */ - GList *items; /* This paragraph turned into items */ - PangoDirection base_dir; /* Current resolved base direction */ - int line_of_par; /* Line of the paragraph, starting at 1 for first line */ - - PangoGlyphString *glyphs; /* Glyphs for the first item in state->items */ - int start_offset; /* Character offset of first item in state->items in layout->text */ - ItemProperties properties; /* Properties for the first item in state->items */ - int *log_widths; /* Logical widths for first item in state->items.. */ + PangoAttrList *attrs; /* Attributes being used for itemization */ + GList *items; /* This paragraph turned into items */ + PangoDirection base_dir; /* Current resolved base direction */ + int line_of_par; /* Line of the paragraph, starting at 1 for first line */ + + PangoGlyphString *glyphs; /* Glyphs for the first item in state->items */ + int start_offset; /* Character offset of first item in state->items in layout->text */ + ItemProperties properties; /* Properties for the first item in state->items */ + int *log_widths; /* Logical widths for first item in state->items.. */ int log_widths_offset; /* Offset into log_widths to the point corresponding - * to the remaining portion of the first item */ + * to the remaining portion of the first item */ int *need_hyphen; /* Insert a hyphen if breaking here ? */ - int line_start_index; /* Start index (byte offset) of line in layout->text */ - int line_start_offset; /* Character offset of line in layout->text */ + int line_start_index; /* Start index (byte offset) of line in layout->text */ + int line_start_offset; /* Character offset of line in layout->text */ /* maintained per line */ - int line_width; /* Goal width of line currently processing; < 0 is infinite */ - int remaining_width; /* Amount of space remaining on line; < 0 is infinite */ + int line_width; /* Goal width of line currently processing; < 0 is infinite */ + int remaining_width; /* Amount of space remaining on line; < 0 is infinite */ int hyphen_width; /* How much space a hyphen will take */ }; static gboolean should_ellipsize_current_line (PangoLayout *layout, - ParaBreakState *state); + ParaBreakState *state); static PangoGlyphString * shape_run (PangoLayoutLine *line, - ParaBreakState *state, - PangoItem *item) + ParaBreakState *state, + PangoItem *item) { PangoLayout *layout = line->layout; PangoGlyphString *glyphs = pango_glyph_string_new (); @@ -3417,9 +3431,9 @@ shape_run (PangoLayoutLine *line, shape_flags |= PANGO_SHAPE_ROUND_POSITIONS; if (state->properties.shape_set) - _pango_shape_shape (layout->text + item->offset, item->num_chars, - state->properties.shape_ink_rect, state->properties.shape_logical_rect, - glyphs); + _pango_shape_shape (layout->text + item->offset, item->num_chars, + state->properties.shape_ink_rect, state->properties.shape_logical_rect, + glyphs); else pango_shape_with_flags (layout->text + item->offset, item->length, layout->text, layout->length, @@ -3427,24 +3441,24 @@ shape_run (PangoLayoutLine *line, shape_flags); if (state->properties.letter_spacing) - { - PangoGlyphItem glyph_item; - int space_left, space_right; + { + PangoGlyphItem glyph_item; + int space_left, space_right; - glyph_item.item = item; - glyph_item.glyphs = glyphs; + glyph_item.item = item; + glyph_item.glyphs = glyphs; - pango_glyph_item_letter_space (&glyph_item, - layout->text, - layout->log_attrs + state->start_offset, - state->properties.letter_spacing); + pango_glyph_item_letter_space (&glyph_item, + layout->text, + layout->log_attrs + state->start_offset, + state->properties.letter_spacing); - distribute_letter_spacing (state->properties.letter_spacing, &space_left, &space_right); + distribute_letter_spacing (state->properties.letter_spacing, &space_left, &space_right); - glyphs->glyphs[0].geometry.width += space_left; - glyphs->glyphs[0].geometry.x_offset += space_left; - glyphs->glyphs[glyphs->num_glyphs - 1].geometry.width += space_right; - } + glyphs->glyphs[0].geometry.width += space_left; + glyphs->glyphs[0].geometry.x_offset += space_left; + glyphs->glyphs[glyphs->num_glyphs - 1].geometry.width += space_right; + } } return glyphs; @@ -3452,9 +3466,9 @@ shape_run (PangoLayoutLine *line, static void insert_run (PangoLayoutLine *line, - ParaBreakState *state, - PangoItem *run_item, - gboolean last_run) + ParaBreakState *state, + PangoItem *run_item, + gboolean last_run) { PangoLayoutRun *run = g_slice_new (PangoLayoutRun); @@ -3468,7 +3482,7 @@ insert_run (PangoLayoutLine *line, if (last_run) { if (state->log_widths_offset > 0) - pango_glyph_string_free (state->glyphs); + pango_glyph_string_free (state->glyphs); state->glyphs = NULL; g_free (state->log_widths); state->log_widths = NULL; @@ -3524,19 +3538,19 @@ get_need_hyphen (PangoItem *item, if (attr) insert_hyphens = ((PangoAttrInt*)attr)->value; - /* Some scripts don't use hyphen.*/ - switch (item->analysis.script) - { - case PANGO_SCRIPT_COMMON: - case PANGO_SCRIPT_HAN: - case PANGO_SCRIPT_HANGUL: - case PANGO_SCRIPT_HIRAGANA: - case PANGO_SCRIPT_KATAKANA: - insert_hyphens = FALSE; - break; - default: - break; - } + /* Some scripts don't use hyphen.*/ + switch (item->analysis.script) + { + case PANGO_SCRIPT_COMMON: + case PANGO_SCRIPT_HAN: + case PANGO_SCRIPT_HANGUL: + case PANGO_SCRIPT_HIRAGANA: + case PANGO_SCRIPT_KATAKANA: + insert_hyphens = FALSE; + break; + default: + break; + } } switch (g_unichar_type (wc)) @@ -3627,7 +3641,7 @@ find_hyphen_width (PangoItem *item) static int find_break_extra_width (PangoLayout *layout, - ParaBreakState *state, + ParaBreakState *state, int pos) { /* Check whether to insert a hyphen */ @@ -3652,11 +3666,11 @@ debug (const char *where, PangoLayoutLine *line, ParaBreakState *state) { int line_width = pango_layout_line_get_width (line); - g_debug ("rem %d + line %d = %d %s", - state->remaining_width, - line_width, - state->remaining_width + line_width, - where); + g_debug ("rem %d + line %d = %d %s", + state->remaining_width, + line_width, + state->remaining_width + line_width, + where); } #else # define DEBUG(where, line, state) do { } while (0) @@ -3683,10 +3697,10 @@ debug (const char *where, PangoLayoutLine *line, ParaBreakState *state) */ static BreakResult process_item (PangoLayout *layout, - PangoLayoutLine *line, - ParaBreakState *state, - gboolean force_fit, - gboolean no_break_at_end) + PangoLayoutLine *line, + ParaBreakState *state, + gboolean force_fit, + gboolean no_break_at_end) { PangoItem *item = state->items->data; gboolean shape_set = FALSE; @@ -3737,7 +3751,7 @@ process_item (PangoLayout *layout, else { for (i = 0; i < item->num_chars; i++) - width += state->log_widths[state->log_widths_offset + i]; + width += state->log_widths[state->log_widths_offset + i]; } if ((width <= state->remaining_width || (item->num_chars == 1 && !line->runs)) && @@ -3759,13 +3773,13 @@ process_item (PangoLayout *layout, gboolean retrying_with_char_breaks = FALSE; if (processing_new_item) - { - PangoGlyphItem glyph_item = {item, state->glyphs}; - state->log_widths = g_new (int, item->num_chars); - pango_glyph_item_get_logical_widths (&glyph_item, layout->text, state->log_widths); - state->need_hyphen = g_new (int, item->num_chars); + { + PangoGlyphItem glyph_item = {item, state->glyphs}; + state->log_widths = g_new (int, item->num_chars); + pango_glyph_item_get_logical_widths (&glyph_item, layout->text, state->log_widths); + state->need_hyphen = g_new (int, item->num_chars); get_need_hyphen (item, layout->text, state->need_hyphen); - } + } retry_break: @@ -3773,103 +3787,103 @@ process_item (PangoLayout *layout, width = 0; extra_width = 0; for (num_chars = 0; num_chars < item->num_chars; num_chars++) - { - if (width + extra_width > state->remaining_width && break_num_chars < item->num_chars) + { + if (width + extra_width > state->remaining_width && break_num_chars < item->num_chars) { break; } - /* If there are no previous runs we have to take care to grab at least one char. */ - if (can_break_at (layout, state->start_offset + num_chars, retrying_with_char_breaks) && - (num_chars > 0 || line->runs)) - { - break_num_chars = num_chars; - break_width = width; + /* If there are no previous runs we have to take care to grab at least one char. */ + if (can_break_at (layout, state->start_offset + num_chars, retrying_with_char_breaks) && + (num_chars > 0 || line->runs)) + { + break_num_chars = num_chars; + break_width = width; break_extra_width = extra_width; extra_width = find_break_extra_width (layout, state, num_chars); - } + } else extra_width = 0; - width += state->log_widths[state->log_widths_offset + num_chars]; - } + width += state->log_widths[state->log_widths_offset + num_chars]; + } /* If there's a space at the end of the line, include that also. * The logic here should match zero_line_final_space(). * XXX Currently it doesn't quite match the logic there. We don't check * the cluster here. But should be fine in practice. */ if (break_num_chars > 0 && break_num_chars < item->num_chars && - layout->log_attrs[state->start_offset + break_num_chars - 1].is_white) + layout->log_attrs[state->start_offset + break_num_chars - 1].is_white) { - break_width -= state->log_widths[state->log_widths_offset + break_num_chars - 1]; + break_width -= state->log_widths[state->log_widths_offset + break_num_chars - 1]; } if (layout->wrap == PANGO_WRAP_WORD_CHAR && force_fit && break_width + break_extra_width > state->remaining_width && !retrying_with_char_breaks) - { - retrying_with_char_breaks = TRUE; - num_chars = item->num_chars; - width = orig_width; - break_num_chars = num_chars; - break_width = width; - goto retry_break; - } - - if (force_fit || break_width + break_extra_width <= state->remaining_width) /* Successfully broke the item */ - { - if (state->remaining_width >= 0) - { - state->remaining_width -= break_width; - state->remaining_width = MAX (state->remaining_width, 0); - } - - if (break_num_chars == item->num_chars) - { + { + retrying_with_char_breaks = TRUE; + num_chars = item->num_chars; + width = orig_width; + break_num_chars = num_chars; + break_width = width; + goto retry_break; + } + + if (force_fit || break_width + break_extra_width <= state->remaining_width) /* Successfully broke the item */ + { + if (state->remaining_width >= 0) + { + state->remaining_width -= break_width; + state->remaining_width = MAX (state->remaining_width, 0); + } + + if (break_num_chars == item->num_chars) + { if (break_needs_hyphen (layout, state, break_num_chars)) item->analysis.flags |= PANGO_ANALYSIS_FLAG_NEED_HYPHEN; - insert_run (line, state, item, TRUE); + insert_run (line, state, item, TRUE); - return BREAK_ALL_FIT; - } - else if (break_num_chars == 0) - { - return BREAK_EMPTY_FIT; - } - else - { - PangoItem *new_item; + return BREAK_ALL_FIT; + } + else if (break_num_chars == 0) + { + return BREAK_EMPTY_FIT; + } + else + { + PangoItem *new_item; - length = g_utf8_offset_to_pointer (layout->text + item->offset, break_num_chars) - (layout->text + item->offset); + length = g_utf8_offset_to_pointer (layout->text + item->offset, break_num_chars) - (layout->text + item->offset); - new_item = pango_item_split (item, length, break_num_chars); + new_item = pango_item_split (item, length, break_num_chars); if (break_needs_hyphen (layout, state, break_num_chars)) new_item->analysis.flags |= PANGO_ANALYSIS_FLAG_NEED_HYPHEN; - /* Add the width back, to the line, reshape, subtract the new width */ - state->remaining_width += break_width; - insert_run (line, state, new_item, FALSE); - break_width = pango_glyph_string_get_width (((PangoGlyphItem *)(line->runs->data))->glyphs); - state->remaining_width -= break_width; + /* Add the width back, to the line, reshape, subtract the new width */ + state->remaining_width += break_width; + insert_run (line, state, new_item, FALSE); + break_width = pango_glyph_string_get_width (((PangoGlyphItem *)(line->runs->data))->glyphs); + state->remaining_width -= break_width; - state->log_widths_offset += break_num_chars; + state->log_widths_offset += break_num_chars; - /* Shaped items should never be broken */ - g_assert (!shape_set); + /* Shaped items should never be broken */ + g_assert (!shape_set); - return BREAK_SOME_FIT; - } - } + return BREAK_SOME_FIT; + } + } else - { - pango_glyph_string_free (state->glyphs); - state->glyphs = NULL; - g_free (state->log_widths); - state->log_widths = NULL; - g_free (state->need_hyphen); - state->need_hyphen = NULL; - - return BREAK_NONE_FIT; - } + { + pango_glyph_string_free (state->glyphs); + state->glyphs = NULL; + g_free (state->log_widths); + state->log_widths = NULL; + g_free (state->need_hyphen); + state->need_hyphen = NULL; + + return BREAK_NONE_FIT; + } } } @@ -3878,7 +3892,7 @@ process_item (PangoLayout *layout, */ static void line_set_resolved_dir (PangoLayoutLine *line, - PangoDirection direction) + PangoDirection direction) { switch (direction) { @@ -3897,14 +3911,14 @@ line_set_resolved_dir (PangoLayoutLine *line, } /* The direction vs. gravity dance: - * - If gravity is SOUTH, leave direction untouched. - * - If gravity is NORTH, switch direction. - * - If gravity is EAST, set to LTR, as - * it's a clockwise-rotated layout, so the rotated - * top is unrotated left. - * - If gravity is WEST, set to RTL, as - * it's a counter-clockwise-rotated layout, so the rotated - * top is unrotated right. + * - If gravity is SOUTH, leave direction untouched. + * - If gravity is NORTH, switch direction. + * - If gravity is EAST, set to LTR, as + * it's a clockwise-rotated layout, so the rotated + * top is unrotated left. + * - If gravity is WEST, set to RTL, as + * it's a counter-clockwise-rotated layout, so the rotated + * top is unrotated right. * * A similar dance is performed in pango-context.c: * itemize_state_add_character(). Keep in synch. @@ -3917,8 +3931,8 @@ line_set_resolved_dir (PangoLayoutLine *line, break; case PANGO_GRAVITY_NORTH: line->resolved_dir = PANGO_DIRECTION_LTR - + PANGO_DIRECTION_RTL - - line->resolved_dir; + + PANGO_DIRECTION_RTL + - line->resolved_dir; break; case PANGO_GRAVITY_EAST: /* This is in fact why deprecated TTB_RTL is LTR */ @@ -3932,19 +3946,19 @@ line_set_resolved_dir (PangoLayoutLine *line, } static gboolean -should_ellipsize_current_line (PangoLayout *layout, - ParaBreakState *state) +should_ellipsize_current_line (PangoLayout *layout, + ParaBreakState *state) { if (G_LIKELY (layout->ellipsize == PANGO_ELLIPSIZE_NONE || layout->width < 0)) return FALSE; - if (layout->height >= 0) { /* state->remaining_height is height of layout left */ /* if we can't stuff two more lines at the current guess of line height, - * the line we are going to produce is going to be the last line */ + * the line we are going to produce is going to be the last line + */ return state->line_height * 2 > state->remaining_height; } else @@ -3956,7 +3970,7 @@ should_ellipsize_current_line (PangoLayout *layout, static void add_line (PangoLayoutLine *line, - ParaBreakState *state) + ParaBreakState *state) { PangoLayout *layout = line->layout; @@ -3976,13 +3990,13 @@ add_line (PangoLayoutLine *line, static void process_line (PangoLayout *layout, - ParaBreakState *state) + ParaBreakState *state) { PangoLayoutLine *line; gboolean have_break = FALSE; /* If we've seen a possible break yet */ int break_remaining_width = 0; /* Remaining width before adding run with break */ - int break_start_offset = 0; /* Start offset before adding run with break */ + int break_start_offset = 0; /* Start offset before adding run with break */ GSList *break_link = NULL; /* Link holding run before break */ gboolean wrapped = FALSE; /* If we had to wrap the line */ @@ -3995,9 +4009,9 @@ process_line (PangoLayout *layout, if (state->line_width >= 0 && layout->alignment != PANGO_ALIGN_CENTER) { if (line->is_paragraph_start && layout->indent >= 0) - state->line_width -= layout->indent; + state->line_width -= layout->indent; else if (!line->is_paragraph_start && layout->indent < 0) - state->line_width += layout->indent; + state->line_width += layout->indent; if (state->line_width < 0) state->line_width = 0; @@ -4024,58 +4038,58 @@ process_line (PangoLayout *layout, result = process_item (layout, line, state, !have_break, FALSE); switch (result) - { - case BREAK_ALL_FIT: - if (can_break_in (layout, state->start_offset, old_num_chars, first_item_in_line)) - { - have_break = TRUE; - break_remaining_width = old_remaining_width; - break_start_offset = state->start_offset; - break_link = line->runs->next; - } + { + case BREAK_ALL_FIT: + if (can_break_in (layout, state->start_offset, old_num_chars, first_item_in_line)) + { + have_break = TRUE; + break_remaining_width = old_remaining_width; + break_start_offset = state->start_offset; + break_link = line->runs->next; + } - state->items = g_list_delete_link (state->items, state->items); - state->start_offset += old_num_chars; + state->items = g_list_delete_link (state->items, state->items); + state->start_offset += old_num_chars; - break; + break; - case BREAK_EMPTY_FIT: - wrapped = TRUE; - goto done; + case BREAK_EMPTY_FIT: + wrapped = TRUE; + goto done; - case BREAK_SOME_FIT: - state->start_offset += old_num_chars - item->num_chars; - wrapped = TRUE; - goto done; + case BREAK_SOME_FIT: + state->start_offset += old_num_chars - item->num_chars; + wrapped = TRUE; + goto done; - case BREAK_NONE_FIT: - /* Back up over unused runs to run where there is a break */ - while (line->runs && line->runs != break_link) - state->items = g_list_prepend (state->items, uninsert_run (line)); + case BREAK_NONE_FIT: + /* Back up over unused runs to run where there is a break */ + while (line->runs && line->runs != break_link) + state->items = g_list_prepend (state->items, uninsert_run (line)); - state->start_offset = break_start_offset; - state->remaining_width = break_remaining_width; + state->start_offset = break_start_offset; + state->remaining_width = break_remaining_width; - /* Reshape run to break */ - item = state->items->data; + /* Reshape run to break */ + item = state->items->data; - old_num_chars = item->num_chars; - result = process_item (layout, line, state, TRUE, TRUE); - g_assert (result == BREAK_SOME_FIT || result == BREAK_EMPTY_FIT); + old_num_chars = item->num_chars; + result = process_item (layout, line, state, TRUE, TRUE); + g_assert (result == BREAK_SOME_FIT || result == BREAK_EMPTY_FIT); - state->start_offset += old_num_chars - item->num_chars; + state->start_offset += old_num_chars - item->num_chars; - wrapped = TRUE; - goto done; + wrapped = TRUE; + goto done; - case BREAK_LINE_SEPARATOR: - state->items = g_list_delete_link (state->items, state->items); - state->start_offset += old_num_chars; - /* A line-separate is just a forced break. Set wrapped, so we do - * justification */ - wrapped = TRUE; - goto done; - } + case BREAK_LINE_SEPARATOR: + state->items = g_list_delete_link (state->items, state->items); + state->start_offset += old_num_chars; + /* A line-separate is just a forced break. Set wrapped, so we do + * justification */ + wrapped = TRUE; + goto done; + } } done: @@ -4090,8 +4104,8 @@ static void get_items_log_attrs (const char *text, int start, int length, - GList *items, - PangoLogAttr *log_attrs, + GList *items, + PangoLogAttr *log_attrs, int log_attrs_len) { int offset = 0; @@ -4304,7 +4318,7 @@ pango_layout_check_lines (PangoLayout *layout) { prev_base_dir = pango_find_base_dir (layout->text, layout->length); if (prev_base_dir == PANGO_DIRECTION_NEUTRAL) - prev_base_dir = pango_context_get_base_dir (layout->context); + prev_base_dir = pango_context_get_base_dir (layout->context); } else base_dir = pango_context_get_base_dir (layout->context); @@ -4326,50 +4340,50 @@ pango_layout_check_lines (PangoLayout *layout) int delimiter_index, next_para_index; if (layout->single_paragraph) - { - delimiter_index = layout->length; - next_para_index = layout->length; - } + { + delimiter_index = layout->length; + next_para_index = layout->length; + } else - { - pango_find_paragraph_boundary (start, - (layout->text + layout->length) - start, - &delimiter_index, - &next_para_index); - } + { + pango_find_paragraph_boundary (start, + (layout->text + layout->length) - start, + &delimiter_index, + &next_para_index); + } g_assert (next_para_index >= delimiter_index); if (layout->auto_dir) - { - base_dir = pango_find_base_dir (start, delimiter_index); + { + base_dir = pango_find_base_dir (start, delimiter_index); - /* Propagate the base direction for neutral paragraphs */ - if (base_dir == PANGO_DIRECTION_NEUTRAL) - base_dir = prev_base_dir; - else - prev_base_dir = base_dir; - } + /* Propagate the base direction for neutral paragraphs */ + if (base_dir == PANGO_DIRECTION_NEUTRAL) + base_dir = prev_base_dir; + else + prev_base_dir = base_dir; + } end = start + delimiter_index; delim_len = next_para_index - delimiter_index; if (end == (layout->text + layout->length)) - done = TRUE; + done = TRUE; g_assert (end <= (layout->text + layout->length)); g_assert (start <= (layout->text + layout->length)); - g_assert (delim_len < 4); /* PS is 3 bytes */ + g_assert (delim_len < 4); /* PS is 3 bytes */ g_assert (delim_len >= 0); state.attrs = itemize_attrs; state.items = pango_itemize_with_base_dir (layout->context, - base_dir, - layout->text, - start - layout->text, - end - start, - itemize_attrs, + base_dir, + layout->text, + start - layout->text, + end - start, + itemize_attrs, itemize_attrs ? &iter : NULL); apply_attributes_to_items (state.items, shape_attrs); @@ -4378,7 +4392,7 @@ pango_layout_check_lines (PangoLayout *layout) start - layout->text, delimiter_index + delim_len, state.items, - layout->log_attrs + start_offset, + layout->log_attrs + start_offset, layout->n_chars + 1 - start_offset); state.base_dir = base_dir; @@ -4399,27 +4413,27 @@ pango_layout_check_lines (PangoLayout *layout) state.hyphen_width = -1; if (state.items) - { - while (state.items) - process_line (layout, &state); - } + { + while (state.items) + process_line (layout, &state); + } else - { - PangoLayoutLine *empty_line; + { + PangoLayoutLine *empty_line; - empty_line = pango_layout_line_new (layout); - empty_line->start_index = state.line_start_index; - empty_line->is_paragraph_start = TRUE; - line_set_resolved_dir (empty_line, base_dir); + empty_line = pango_layout_line_new (layout); + empty_line->start_index = state.line_start_index; + empty_line->is_paragraph_start = TRUE; + line_set_resolved_dir (empty_line, base_dir); - add_line (empty_line, &state); - } + add_line (empty_line, &state); + } if (layout->height >= 0 && state.remaining_height < state.line_height) - done = TRUE; + done = TRUE; if (!done) - start_offset += pango_utf8_strlen (start, (end - start) + delim_len); + start_offset += pango_utf8_strlen (start, (end - start) + delim_len); start = end + delim_len; } @@ -4442,14 +4456,14 @@ pango_layout_check_lines (PangoLayout *layout) /** * pango_layout_line_ref: - * @line: (nullable): a #PangoLayoutLine, may be %NULL + * @line: (nullable): a `PangoLayoutLine`, may be %NULL * - * Increase the reference count of a #PangoLayoutLine by one. + * Increase the reference count of a `PangoLayoutLine` by one. * * Return value: the line passed in. * * Since: 1.10 - **/ + */ PangoLayoutLine * pango_layout_line_ref (PangoLayoutLine *line) { @@ -4465,12 +4479,12 @@ pango_layout_line_ref (PangoLayoutLine *line) /** * pango_layout_line_unref: - * @line: a #PangoLayoutLine + * @line: a `PangoLayoutLine` * - * Decrease the reference count of a #PangoLayoutLine by one. + * Decrease the reference count of a `PangoLayoutLine` by one. * If the result is zero, the line and all associated memory * will be freed. - **/ + */ void pango_layout_line_unref (PangoLayoutLine *line) { @@ -4495,34 +4509,32 @@ G_DEFINE_BOXED_TYPE (PangoLayoutLine, pango_layout_line, /** * pango_layout_line_x_to_index: - * @line: a #PangoLayoutLine - * @x_pos: the X offset (in Pango units) - * from the left edge of the line. - * @index_: (out): location to store calculated byte index for - * the grapheme in which the user clicked. - * @trailing: (out): location to store an integer indicating where - * in the grapheme the user clicked. It will either - * be zero, or the number of characters in the - * grapheme. 0 represents the leading edge of the grapheme. - * - * Converts from x offset to the byte index of the corresponding - * character within the text of the layout. If @x_pos is outside the line, - * @index_ and @trailing will point to the very first or very last position - * in the line. This determination is based on the resolved direction - * of the paragraph; for example, if the resolved direction is - * right-to-left, then an X position to the right of the line (after it) - * results in 0 being stored in @index_ and @trailing. An X position to the - * left of the line results in @index_ pointing to the (logical) last - * grapheme in the line and @trailing being set to the number of characters - * in that grapheme. The reverse is true for a left-to-right line. + * @line: a `PangoLayoutLine` + * @x_pos: the X offset (in Pango units) from the left edge of the line. + * @index_: (out): location to store calculated byte index for the grapheme + * in which the user clicked. + * @trailing: (out): location to store an integer indicating where in the + * grapheme the user clicked. It will either be zero, or the number of + * characters in the grapheme. 0 represents the leading edge of the grapheme. + * + * Converts from x offset to the byte index of the corresponding character + * within the text of the layout. If @x_pos is outside the line, @index_ and + * @trailing will point to the very first or very last position in the line. + * This determination is based on the resolved direction of the paragraph; + * for example, if the resolved direction is right-to-left, then an X position + * to the right of the line (after it) results in 0 being stored in @index_ + * and @trailing. An X position to the left of the line results in @index_ + * pointing to the (logical) last grapheme in the line and @trailing being + * set to the number of characters in that grapheme. The reverse is true for + * a left-to-right line. * * Return value: %FALSE if @x_pos was outside the line, %TRUE if inside - **/ + */ gboolean pango_layout_line_x_to_index (PangoLayoutLine *line, - int x_pos, - int *index, - int *trailing) + int x_pos, + int *index, + int *trailing) { GSList *tmp_list; gint start_pos = 0; @@ -4547,9 +4559,9 @@ pango_layout_line_x_to_index (PangoLayoutLine *line, if (line->length == 0) { if (index) - *index = first_index; + *index = first_index; if (trailing) - *trailing = 0; + *trailing = 0; return FALSE; } @@ -4610,10 +4622,10 @@ pango_layout_line_x_to_index (PangoLayoutLine *line, { /* pick the leftmost char */ if (index) - *index = (line->resolved_dir == PANGO_DIRECTION_LTR) ? first_index : last_index; + *index = (line->resolved_dir == PANGO_DIRECTION_LTR) ? first_index : last_index; /* and its leftmost edge */ if (trailing) - *trailing = (line->resolved_dir == PANGO_DIRECTION_LTR || suppress_last_trailing) ? 0 : last_trailing; + *trailing = (line->resolved_dir == PANGO_DIRECTION_LTR || suppress_last_trailing) ? 0 : last_trailing; return FALSE; } @@ -4627,58 +4639,58 @@ pango_layout_line_x_to_index (PangoLayoutLine *line, logical_width = pango_glyph_string_get_width (run->glyphs); if (x_pos >= start_pos && x_pos < start_pos + logical_width) - { - int offset; - gboolean char_trailing; - int grapheme_start_index; - int grapheme_start_offset; - int grapheme_end_offset; - int pos; - int char_index; - - pango_glyph_string_x_to_index (run->glyphs, - layout->text + run->item->offset, run->item->length, - &run->item->analysis, - x_pos - start_pos, - &pos, &char_trailing); - - char_index = run->item->offset + pos; - - /* Convert from characters to graphemes */ - - offset = g_utf8_pointer_to_offset (layout->text, layout->text + char_index); - - grapheme_start_offset = offset; - grapheme_start_index = char_index; - while (grapheme_start_offset > first_offset && - !layout->log_attrs[grapheme_start_offset].is_cursor_position) - { - grapheme_start_index = g_utf8_prev_char (layout->text + grapheme_start_index) - layout->text; - grapheme_start_offset--; - } - - grapheme_end_offset = offset; - do - { - grapheme_end_offset++; - } - while (grapheme_end_offset < end_offset && - !layout->log_attrs[grapheme_end_offset].is_cursor_position); - - if (index) - *index = grapheme_start_index; - - if (trailing) - { - if ((grapheme_end_offset == end_offset && suppress_last_trailing) || - offset + char_trailing <= (grapheme_start_offset + grapheme_end_offset) / 2) - *trailing = 0; - else - *trailing = grapheme_end_offset - grapheme_start_offset; - } - - return TRUE; - } + { + int offset; + gboolean char_trailing; + int grapheme_start_index; + int grapheme_start_offset; + int grapheme_end_offset; + int pos; + int char_index; + + pango_glyph_string_x_to_index (run->glyphs, + layout->text + run->item->offset, run->item->length, + &run->item->analysis, + x_pos - start_pos, + &pos, &char_trailing); + + char_index = run->item->offset + pos; + + /* Convert from characters to graphemes */ + + offset = g_utf8_pointer_to_offset (layout->text, layout->text + char_index); + + grapheme_start_offset = offset; + grapheme_start_index = char_index; + while (grapheme_start_offset > first_offset && + !layout->log_attrs[grapheme_start_offset].is_cursor_position) + { + grapheme_start_index = g_utf8_prev_char (layout->text + grapheme_start_index) - layout->text; + grapheme_start_offset--; + } + + grapheme_end_offset = offset; + do + { + grapheme_end_offset++; + } + while (grapheme_end_offset < end_offset && + !layout->log_attrs[grapheme_end_offset].is_cursor_position); + + if (index) + *index = grapheme_start_index; + + if (trailing) + { + if ((grapheme_end_offset == end_offset && suppress_last_trailing) || + offset + char_trailing <= (grapheme_start_offset + grapheme_end_offset) / 2) + *trailing = 0; + else + *trailing = grapheme_end_offset - grapheme_start_offset; + } + + return TRUE; + } start_pos += logical_width; tmp_list = tmp_list->next; @@ -4715,24 +4727,21 @@ pango_layout_line_get_width (PangoLayoutLine *line) /** * pango_layout_line_get_x_ranges: - * @line: a #PangoLayoutLine + * @line: a `PangoLayoutLine` * @start_index: Start byte index of the logical range. If this value - * is less than the start index for the line, then - * the first range will extend all the way to the leading - * edge of the layout. Otherwise it will start at the - * leading edge of the first character. - * @end_index: Ending byte index of the logical range. If this value - * is greater than the end index for the line, then - * the last range will extend all the way to the trailing - * edge of the layout. Otherwise, it will end at the - * trailing edge of the last character. - * @ranges: (out) (array length=n_ranges) (transfer full): - * location to store a pointer to an array of ranges. - * The array will be of length <literal>2*n_ranges</literal>, - * with each range starting at <literal>(*ranges)[2*n]</literal> - * and of width <literal>(*ranges)[2*n + 1] - (*ranges)[2*n]</literal>. - * This array must be freed with g_free(). The coordinates are relative - * to the layout and are in Pango units. + * is less than the start index for the line, then the first range + * will extend all the way to the leading edge of the layout. Otherwise, + * it will start at the leading edge of the first character. + * @end_index: Ending byte index of the logical range. If this value is + * greater than the end index for the line, then the last range will + * extend all the way to the trailing edge of the layout. Otherwise, + * it will end at the trailing edge of the last character. + * @ranges: (out) (array length=n_ranges) (transfer full): location to + * store a pointer to an array of ranges. The array will be of length + * `2*n_ranges`, with each range starting at `(*ranges)[2*n]` and of + * width `(*ranges)[2*n + 1] - (*ranges)[2*n]`. This array must be freed + * with g_free(). The coordinates are relative to the layout and are in + * Pango units. * @n_ranges: The number of ranges stored in @ranges. * * Gets a list of visual ranges corresponding to a given logical range. @@ -4740,13 +4749,13 @@ pango_layout_line_get_width (PangoLayoutLine *line) * ranges which are adjacent. The ranges will be sorted from left to * right. The ranges are with respect to the left edge of the entire * layout, not with respect to the line. - **/ + */ void pango_layout_line_get_x_ranges (PangoLayoutLine *line, - int start_index, - int end_index, - int **ranges, - int *n_ranges) + int start_index, + int end_index, + int **ranges, + int *n_ranges) { gint line_start_index = 0; GSList *tmp_list; @@ -4794,10 +4803,10 @@ pango_layout_line_get_x_ranges (PangoLayoutLine *line, (line->resolved_dir == PANGO_DIRECTION_RTL && end_index > line_start_index + line->length))) { if (ranges) - { - (*ranges)[2*range_count] = 0; - (*ranges)[2*range_count + 1] = x_offset; - } + { + (*ranges)[2*range_count] = 0; + (*ranges)[2*range_count + 1] = x_offset; + } range_count ++; } @@ -4808,42 +4817,42 @@ pango_layout_line_get_x_ranges (PangoLayoutLine *line, PangoLayoutRun *run = (PangoLayoutRun *)tmp_list->data; if ((start_index < run->item->offset + run->item->length && - end_index > run->item->offset)) - { - if (ranges) - { - int run_start_index = MAX (start_index, run->item->offset); - int run_end_index = MIN (end_index, run->item->offset + run->item->length); - int run_start_x, run_end_x; - - g_assert (run_end_index > 0); - - /* Back the end_index off one since we want to find the trailing edge of the preceding character */ - - run_end_index = g_utf8_prev_char (line->layout->text + run_end_index) - line->layout->text; - - pango_glyph_string_index_to_x (run->glyphs, - line->layout->text + run->item->offset, - run->item->length, - &run->item->analysis, - run_start_index - run->item->offset, FALSE, - &run_start_x); - pango_glyph_string_index_to_x (run->glyphs, - line->layout->text + run->item->offset, - run->item->length, - &run->item->analysis, - run_end_index - run->item->offset, TRUE, - &run_end_x); - - (*ranges)[2*range_count] = x_offset + accumulated_width + MIN (run_start_x, run_end_x); - (*ranges)[2*range_count + 1] = x_offset + accumulated_width + MAX (run_start_x, run_end_x); - } - - range_count++; - } + end_index > run->item->offset)) + { + if (ranges) + { + int run_start_index = MAX (start_index, run->item->offset); + int run_end_index = MIN (end_index, run->item->offset + run->item->length); + int run_start_x, run_end_x; + + g_assert (run_end_index > 0); + + /* Back the end_index off one since we want to find the trailing edge of the preceding character */ + + run_end_index = g_utf8_prev_char (line->layout->text + run_end_index) - line->layout->text; + + pango_glyph_string_index_to_x (run->glyphs, + line->layout->text + run->item->offset, + run->item->length, + &run->item->analysis, + run_start_index - run->item->offset, FALSE, + &run_start_x); + pango_glyph_string_index_to_x (run->glyphs, + line->layout->text + run->item->offset, + run->item->length, + &run->item->analysis, + run_end_index - run->item->offset, TRUE, + &run_end_x); + + (*ranges)[2*range_count] = x_offset + accumulated_width + MIN (run_start_x, run_end_x); + (*ranges)[2*range_count + 1] = x_offset + accumulated_width + MAX (run_start_x, run_end_x); + } + + range_count++; + } if (tmp_list->next) - accumulated_width += pango_glyph_string_get_width (run->glyphs); + accumulated_width += pango_glyph_string_get_width (run->glyphs); tmp_list = tmp_list->next; } @@ -4853,10 +4862,10 @@ pango_layout_line_get_x_ranges (PangoLayoutLine *line, (line->resolved_dir == PANGO_DIRECTION_RTL && start_index < line_start_index))) { if (ranges) - { - (*ranges)[2*range_count] = x_offset + line_width; - (*ranges)[2*range_count + 1] = line->layout->width; - } + { + (*ranges)[2*range_count] = x_offset + line_width; + (*ranges)[2*range_count + 1] = line->layout->width; + } range_count ++; } @@ -4867,8 +4876,8 @@ pango_layout_line_get_x_ranges (PangoLayoutLine *line, static void pango_layout_get_empty_extents_at_index (PangoLayout *layout, - int index, - PangoRectangle *logical_rect) + int index, + PangoRectangle *logical_rect) { if (logical_rect) { @@ -4880,76 +4889,76 @@ pango_layout_get_empty_extents_at_index (PangoLayout *layout, if (layout->font_desc) { - font_desc = pango_font_description_copy_static (font_desc); - pango_font_description_merge (font_desc, layout->font_desc, TRUE); - free_font_desc = TRUE; - } + font_desc = pango_font_description_copy_static (font_desc); + pango_font_description_merge (font_desc, layout->font_desc, TRUE); + free_font_desc = TRUE; + } /* Find the font description for this line */ if (layout->attrs) - { + { PangoAttrIterator iter; - int start, end; + int start, end; _pango_attr_list_get_iterator (layout->attrs, &iter); - do - { + do + { pango_attr_iterator_range (&iter, &start, &end); - if (start <= index && index < end) - { - if (!free_font_desc) - { - font_desc = pango_font_description_copy_static (font_desc); - free_font_desc = TRUE; - } + if (start <= index && index < end) + { + if (!free_font_desc) + { + font_desc = pango_font_description_copy_static (font_desc); + free_font_desc = TRUE; + } pango_attr_iterator_get_font (&iter, - font_desc, - NULL, - NULL); + font_desc, + NULL, + NULL); - break; - } + break; + } - } + } while (pango_attr_iterator_next (&iter)); _pango_attr_iterator_destroy (&iter); - } + } font = pango_context_load_font (layout->context, font_desc); if (font) - { - PangoFontMetrics *metrics; - - metrics = pango_font_get_metrics (font, - pango_context_get_language (layout->context)); - - if (metrics) - { - logical_rect->y = - pango_font_metrics_get_ascent (metrics); - logical_rect->height = - logical_rect->y + pango_font_metrics_get_descent (metrics); - - pango_font_metrics_unref (metrics); - } - else - { - logical_rect->y = 0; - logical_rect->height = 0; - } - g_object_unref (font); - } + { + PangoFontMetrics *metrics; + + metrics = pango_font_get_metrics (font, + pango_context_get_language (layout->context)); + + if (metrics) + { + logical_rect->y = - pango_font_metrics_get_ascent (metrics); + logical_rect->height = - logical_rect->y + pango_font_metrics_get_descent (metrics); + + pango_font_metrics_unref (metrics); + } + else + { + logical_rect->y = 0; + logical_rect->height = 0; + } + g_object_unref (font); + } else - { - logical_rect->y = 0; - logical_rect->height = 0; - } + { + logical_rect->y = 0; + logical_rect->height = 0; + } if (free_font_desc) - pango_font_description_free (font_desc); + pango_font_description_free (font_desc); logical_rect->x = 0; logical_rect->width = 0; @@ -4958,7 +4967,7 @@ pango_layout_get_empty_extents_at_index (PangoLayout *layout, static void pango_layout_line_get_empty_extents (PangoLayoutLine *line, - PangoRectangle *logical_rect) + PangoRectangle *logical_rect) { pango_layout_get_empty_extents_at_index (line->layout, line->start_index, logical_rect); } @@ -4992,12 +5001,12 @@ pango_layout_run_get_extents_and_height (PangoLayoutRun *run, if (properties.shape_set) _pango_shape_get_extents (run->item->num_chars, - properties.shape_ink_rect, - properties.shape_logical_rect, - run_ink, run_logical); + properties.shape_ink_rect, + properties.shape_logical_rect, + run_ink, run_logical); else pango_glyph_string_extents (run->glyphs, run->item->analysis.font, - run_ink, run_logical); + run_ink, run_logical); if (run_ink && (has_underline || has_overline || properties.strikethrough)) { @@ -5009,7 +5018,7 @@ pango_layout_run_get_extents_and_height (PangoLayoutRun *run, if (!metrics) metrics = pango_font_get_metrics (run->item->analysis.font, - run->item->analysis.language); + run->item->analysis.language); underline_thickness = pango_font_metrics_get_underline_thickness (metrics); underline_position = pango_font_metrics_get_underline_position (metrics); @@ -5028,18 +5037,18 @@ pango_layout_run_get_extents_and_height (PangoLayoutRun *run, */ if (properties.strikethrough) - { - if (run_ink->height == 0) - { - run_ink->height = strikethrough_thickness; - run_ink->y = -strikethrough_position; - } - } + { + if (run_ink->height == 0) + { + run_ink->height = strikethrough_thickness; + run_ink->y = -strikethrough_position; + } + } if (properties.oline_single) { - run_ink->y -= underline_thickness; - run_ink->height += underline_thickness; + run_ink->y -= underline_thickness; + run_ink->height += underline_thickness; } if (properties.uline_low) @@ -5059,7 +5068,7 @@ pango_layout_run_get_extents_and_height (PangoLayoutRun *run, { if (!metrics) metrics = pango_font_get_metrics (run->item->analysis.font, - run->item->analysis.language); + run->item->analysis.language); *height = pango_font_metrics_get_height (metrics); } @@ -5069,7 +5078,7 @@ pango_layout_run_get_extents_and_height (PangoLayoutRun *run, int adjustment = run_logical->y + run_logical->height / 2; if (is_hinted) - adjustment = PANGO_UNITS_ROUND (adjustment); + adjustment = PANGO_UNITS_ROUND (adjustment); properties.rise += adjustment; } @@ -5077,10 +5086,10 @@ pango_layout_run_get_extents_and_height (PangoLayoutRun *run, if (properties.rise != 0) { if (run_ink) - run_ink->y -= properties.rise; + run_ink->y -= properties.rise; if (run_logical) - run_logical->y -= properties.rise; + run_logical->y -= properties.rise; } if (metrics) @@ -5107,28 +5116,28 @@ pango_layout_line_get_extents_and_height (PangoLayoutLine *line, { case CACHED: { - if (ink_rect) - *ink_rect = private->ink_rect; - if (logical_rect) - *logical_rect = private->logical_rect; + if (ink_rect) + *ink_rect = private->ink_rect; + if (logical_rect) + *logical_rect = private->logical_rect; if (height) *height = private->height; - return; + return; } case NOT_CACHED: { - caching = TRUE; - if (!ink_rect) - ink_rect = &private->ink_rect; - if (!logical_rect) - logical_rect = &private->logical_rect; + caching = TRUE; + if (!ink_rect) + ink_rect = &private->ink_rect; + if (!logical_rect) + logical_rect = &private->logical_rect; if (!height) height = &private->height; - break; + break; } case LEAKED: { - break; + break; } } @@ -5166,37 +5175,37 @@ pango_layout_line_get_extents_and_height (PangoLayoutLine *line, height ? &run_height : NULL); if (ink_rect) - { - if (ink_rect->width == 0 || ink_rect->height == 0) - { - *ink_rect = run_ink; - ink_rect->x += x_pos; - } - else if (run_ink.width != 0 && run_ink.height != 0) - { - new_pos = MIN (ink_rect->x, x_pos + run_ink.x); - ink_rect->width = MAX (ink_rect->x + ink_rect->width, - x_pos + run_ink.x + run_ink.width) - new_pos; - ink_rect->x = new_pos; - - new_pos = MIN (ink_rect->y, run_ink.y); - ink_rect->height = MAX (ink_rect->y + ink_rect->height, - run_ink.y + run_ink.height) - new_pos; - ink_rect->y = new_pos; - } - } + { + if (ink_rect->width == 0 || ink_rect->height == 0) + { + *ink_rect = run_ink; + ink_rect->x += x_pos; + } + else if (run_ink.width != 0 && run_ink.height != 0) + { + new_pos = MIN (ink_rect->x, x_pos + run_ink.x); + ink_rect->width = MAX (ink_rect->x + ink_rect->width, + x_pos + run_ink.x + run_ink.width) - new_pos; + ink_rect->x = new_pos; + + new_pos = MIN (ink_rect->y, run_ink.y); + ink_rect->height = MAX (ink_rect->y + ink_rect->height, + run_ink.y + run_ink.height) - new_pos; + ink_rect->y = new_pos; + } + } if (logical_rect) { new_pos = MIN (logical_rect->x, x_pos + run_logical.x); logical_rect->width = MAX (logical_rect->x + logical_rect->width, - x_pos + run_logical.x + run_logical.width) - new_pos; - logical_rect->x = new_pos; + x_pos + run_logical.x + run_logical.width) - new_pos; + logical_rect->x = new_pos; - new_pos = MIN (logical_rect->y, run_logical.y); - logical_rect->height = MAX (logical_rect->y + logical_rect->height, - run_logical.y + run_logical.height) - new_pos; - logical_rect->y = new_pos; + new_pos = MIN (logical_rect->y, run_logical.y); + logical_rect->height = MAX (logical_rect->y + logical_rect->height, + run_logical.y + run_logical.height) - new_pos; + logical_rect->y = new_pos; } if (height) @@ -5212,9 +5221,9 @@ pango_layout_line_get_extents_and_height (PangoLayoutLine *line, if (caching) { if (&private->ink_rect != ink_rect) - private->ink_rect = *ink_rect; + private->ink_rect = *ink_rect; if (&private->logical_rect != logical_rect) - private->logical_rect = *logical_rect; + private->logical_rect = *logical_rect; if (&private->height != height) private->height = *height; private->cache_status = CACHED; @@ -5223,37 +5232,37 @@ pango_layout_line_get_extents_and_height (PangoLayoutLine *line, /** * pango_layout_line_get_extents: - * @line: a #PangoLayoutLine + * @line: a `PangoLayoutLine` * @ink_rect: (out) (allow-none): rectangle used to store the extents of - * the glyph string as drawn, or %NULL + * the glyph string as drawn, or %NULL * @logical_rect: (out) (allow-none):rectangle used to store the logical - * extents of the glyph string, or %NULL + * extents of the glyph string, or %NULL * * Computes the logical and ink extents of a layout line. See - * pango_font_get_glyph_extents() for details about the interpretation - * of the rectangles. + * [method@Pango.Font.get_glyph_extents] for details about the + * interpretation of the rectangles. */ void pango_layout_line_get_extents (PangoLayoutLine *line, - PangoRectangle *ink_rect, - PangoRectangle *logical_rect) + PangoRectangle *ink_rect, + PangoRectangle *logical_rect) { pango_layout_line_get_extents_and_height (line, ink_rect, logical_rect, NULL); } /** * pango_layout_line_get_height: - * @line: a #PangoLayoutLine + * @line: a `PangoLayoutLine` * @height: (out) (allow-none): return location for the line height * - * Computes the height of the line, ie the distance between + * Computes the height of the line, i.e. the distance between * this and the previous lines baseline. * * Since: 1.44 */ void pango_layout_line_get_height (PangoLayoutLine *line, - int *height) + int *height) { pango_layout_line_get_extents_and_height (line, NULL, NULL, height); } @@ -5277,22 +5286,23 @@ pango_layout_line_new (PangoLayout *layout) /** * pango_layout_line_get_pixel_extents: - * @layout_line: a #PangoLayoutLine + * @layout_line: a `PangoLayoutLine` * @ink_rect: (out) (allow-none): rectangle used to store the extents of - * the glyph string as drawn, or %NULL + * the glyph string as drawn, or %NULL * @logical_rect: (out) (allow-none): rectangle used to store the logical - * extents of the glyph string, or %NULL + * extents of the glyph string, or %NULL * * Computes the logical and ink extents of @layout_line in device units. - * This function just calls pango_layout_line_get_extents() followed by - * two pango_extents_to_pixels() calls, rounding @ink_rect and @logical_rect + * + * This function just calls [method@Pango.LayoutLine.get_extents] followed by + * two [func@extents_to_pixels] calls, rounding @ink_rect and @logical_rect * such that the rounded rectangles fully contain the unrounded one (that is, - * passes them as first argument to pango_extents_to_pixels()). - **/ + * passes them as first argument to [func@extents_to_pixels]). + */ void pango_layout_line_get_pixel_extents (PangoLayoutLine *layout_line, - PangoRectangle *ink_rect, - PangoRectangle *logical_rect) + PangoRectangle *ink_rect, + PangoRectangle *logical_rect) { g_return_if_fail (LINE_IS_VALID (layout_line)); @@ -5305,9 +5315,9 @@ pango_layout_line_get_pixel_extents (PangoLayoutLine *layout_line, * NB: This implement the exact same algorithm as * reorder-items.c:pango_reorder_items(). */ - static GSList * -reorder_runs_recurse (GSList *items, int n_items) +reorder_runs_recurse (GSList *items, + int n_items) { GSList *tmp_list, *level_start_node; int i, level_start_i; @@ -5335,23 +5345,23 @@ reorder_runs_recurse (GSList *items, int n_items) PangoLayoutRun *run = tmp_list->data; if (run->item->analysis.level == min_level) - { - if (min_level % 2) - { - if (i > level_start_i) - result = g_slist_concat (reorder_runs_recurse (level_start_node, i - level_start_i), result); - result = g_slist_prepend (result, run); - } - else - { - if (i > level_start_i) - result = g_slist_concat (result, reorder_runs_recurse (level_start_node, i - level_start_i)); - result = g_slist_append (result, run); - } - - level_start_i = i + 1; - level_start_node = tmp_list->next; - } + { + if (min_level % 2) + { + if (i > level_start_i) + result = g_slist_concat (reorder_runs_recurse (level_start_node, i - level_start_i), result); + result = g_slist_prepend (result, run); + } + else + { + if (i > level_start_i) + result = g_slist_concat (result, reorder_runs_recurse (level_start_node, i - level_start_i)); + result = g_slist_append (result, run); + } + + level_start_i = i + 1; + level_start_node = tmp_list->next; + } tmp_list = tmp_list->next; } @@ -5359,12 +5369,12 @@ reorder_runs_recurse (GSList *items, int n_items) if (min_level % 2) { if (i > level_start_i) - result = g_slist_concat (reorder_runs_recurse (level_start_node, i - level_start_i), result); + result = g_slist_concat (reorder_runs_recurse (level_start_node, i - level_start_i), result); } else { if (i > level_start_i) - result = g_slist_concat (result, reorder_runs_recurse (level_start_node, i - level_start_i)); + result = g_slist_concat (result, reorder_runs_recurse (level_start_node, i - level_start_i)); } return result; @@ -5420,8 +5430,8 @@ get_item_letter_spacing (PangoItem *item) static void pad_glyphstring_right (PangoGlyphString *glyphs, - ParaBreakState *state, - int adjustment) + ParaBreakState *state, + int adjustment) { int glyph = glyphs->num_glyphs - 1; @@ -5442,8 +5452,8 @@ pad_glyphstring_right (PangoGlyphString *glyphs, static void pad_glyphstring_left (PangoGlyphString *glyphs, - ParaBreakState *state, - int adjustment) + ParaBreakState *state, + int adjustment) { int glyph = 0; @@ -5460,15 +5470,15 @@ pad_glyphstring_left (PangoGlyphString *glyphs, static gboolean is_tab_run (PangoLayout *layout, - PangoLayoutRun *run) + PangoLayoutRun *run) { return (layout->text[run->item->offset] == '\t'); } static void zero_line_final_space (PangoLayoutLine *line, - ParaBreakState *state, - PangoLayoutRun *run) + ParaBreakState *state, + PangoLayoutRun *run) { PangoLayout *layout = line->layout; PangoItem *item = run->item; @@ -5509,7 +5519,7 @@ zero_line_final_space (PangoLayoutLine *line, */ static void adjust_line_letter_spacing (PangoLayoutLine *line, - ParaBreakState *state) + ParaBreakState *state) { PangoLayout *layout = line->layout; gboolean reversed; @@ -5526,12 +5536,12 @@ adjust_line_letter_spacing (PangoLayoutLine *line, if (line->resolved_dir == PANGO_DIRECTION_RTL) { for (l = line->runs; l; l = l->next) - if (is_tab_run (layout, l->data)) - { - line->runs = g_slist_reverse (line->runs); - reversed = TRUE; - break; - } + if (is_tab_run (layout, l->data)) + { + line->runs = g_slist_reverse (line->runs); + reversed = TRUE; + break; + } } /* Walk over the runs in the line, redistributing letter @@ -5543,7 +5553,6 @@ adjust_line_letter_spacing (PangoLayoutLine *line, * which we add onto the next tab stop space to keep the * things properly aligned. */ - last_run = NULL; tab_adjustment = 0; for (l = line->runs; l; l = l->next) @@ -5552,43 +5561,43 @@ adjust_line_letter_spacing (PangoLayoutLine *line, PangoLayoutRun *next_run = l->next ? l->next->data : NULL; if (is_tab_run (layout, run)) - { - pad_glyphstring_right (run->glyphs, state, tab_adjustment); - tab_adjustment = 0; - } + { + pad_glyphstring_right (run->glyphs, state, tab_adjustment); + tab_adjustment = 0; + } else - { - PangoLayoutRun *visual_next_run = reversed ? last_run : next_run; - PangoLayoutRun *visual_last_run = reversed ? next_run : last_run; - int run_spacing = get_item_letter_spacing (run->item); - int space_left, space_right; - - distribute_letter_spacing (run_spacing, &space_left, &space_right); - - if (run->glyphs->glyphs[0].geometry.width == 0) - { - /* we've zeroed this space glyph at the end of line, now remove - * the letter spacing added to its adjacent glyph */ - pad_glyphstring_left (run->glyphs, state, - space_left); - } - else if (!visual_last_run || is_tab_run (layout, visual_last_run)) - { - pad_glyphstring_left (run->glyphs, state, - space_left); - tab_adjustment += space_left; - } - - if (run->glyphs->glyphs[run->glyphs->num_glyphs - 1].geometry.width == 0) - { - /* we've zeroed this space glyph at the end of line, now remove - * the letter spacing added to its adjacent glyph */ - pad_glyphstring_right (run->glyphs, state, - space_right); - } - else if (!visual_next_run || is_tab_run (layout, visual_next_run)) - { - pad_glyphstring_right (run->glyphs, state, - space_right); - tab_adjustment += space_right; - } - } + { + PangoLayoutRun *visual_next_run = reversed ? last_run : next_run; + PangoLayoutRun *visual_last_run = reversed ? next_run : last_run; + int run_spacing = get_item_letter_spacing (run->item); + int space_left, space_right; + + distribute_letter_spacing (run_spacing, &space_left, &space_right); + + if (run->glyphs->glyphs[0].geometry.width == 0) + { + /* we've zeroed this space glyph at the end of line, now remove + * the letter spacing added to its adjacent glyph */ + pad_glyphstring_left (run->glyphs, state, - space_left); + } + else if (!visual_last_run || is_tab_run (layout, visual_last_run)) + { + pad_glyphstring_left (run->glyphs, state, - space_left); + tab_adjustment += space_left; + } + + if (run->glyphs->glyphs[run->glyphs->num_glyphs - 1].geometry.width == 0) + { + /* we've zeroed this space glyph at the end of line, now remove + * the letter spacing added to its adjacent glyph */ + pad_glyphstring_right (run->glyphs, state, - space_right); + } + else if (!visual_next_run || is_tab_run (layout, visual_next_run)) + { + pad_glyphstring_right (run->glyphs, state, - space_right); + tab_adjustment += space_right; + } + } last_run = run; } @@ -5599,7 +5608,7 @@ adjust_line_letter_spacing (PangoLayoutLine *line, static void justify_clusters (PangoLayoutLine *line, - ParaBreakState *state) + ParaBreakState *state) { const gchar *text = line->layout->text; const PangoLogAttr *log_attrs = line->layout->log_attrs; @@ -5631,120 +5640,120 @@ justify_clusters (PangoLayoutLine *line, gaps_so_far = 0; for (run_iter = line->runs; run_iter; run_iter = run_iter->next) - { - PangoLayoutRun *run = run_iter->data; - PangoGlyphString *glyphs = run->glyphs; - PangoGlyphItemIter cluster_iter; - gboolean have_cluster; - int dir; - int offset; - - dir = run->item->analysis.level % 2 == 0 ? +1 : -1; - - /* We need character offset of the start of the run. We don't have this. - * Compute by counting from the beginning of the line. The naming is - * confusing. Note that: - * - * run->item->offset is byte offset of start of run in layout->text. - * state->line_start_index is byte offset of start of line in layout->text. - * state->line_start_offset is character offset of start of line in layout->text. - */ - g_assert (run->item->offset >= state->line_start_index); - offset = state->line_start_offset - + pango_utf8_strlen (text + state->line_start_index, - run->item->offset - state->line_start_index); - - for (have_cluster = dir > 0 ? - pango_glyph_item_iter_init_start (&cluster_iter, run, text) : - pango_glyph_item_iter_init_end (&cluster_iter, run, text); - have_cluster; - have_cluster = dir > 0 ? - pango_glyph_item_iter_next_cluster (&cluster_iter) : - pango_glyph_item_iter_prev_cluster (&cluster_iter)) - { - int i; - int width = 0; - - /* don't expand in the middle of graphemes */ - if (!log_attrs[offset + cluster_iter.start_char].is_cursor_position) - continue; - - for (i = cluster_iter.start_glyph; i != cluster_iter.end_glyph; i += dir) - width += glyphs->glyphs[i].geometry.width; - - /* also don't expand zero-width clusters. */ - if (width == 0) - continue; - - gaps_so_far++; - - if (mode == ADJUST) - { - int leftmost, rightmost; - int adjustment, space_left, space_right; - - adjustment = total_remaining_width / total_gaps + residual; - if (is_hinted) - { - int old_adjustment = adjustment; - adjustment = PANGO_UNITS_ROUND (adjustment); - residual = old_adjustment - adjustment; - } - /* distribute to before/after */ - distribute_letter_spacing (adjustment, &space_left, &space_right); - - if (cluster_iter.start_glyph < cluster_iter.end_glyph) - { - /* LTR */ - leftmost = cluster_iter.start_glyph; - rightmost = cluster_iter.end_glyph - 1; - } - else - { - /* RTL */ - leftmost = cluster_iter.end_glyph + 1; - rightmost = cluster_iter.start_glyph; - } - /* Don't add to left-side of left-most glyph of left-most non-zero run. */ - if (leftedge) - leftedge = FALSE; - else - { - glyphs->glyphs[leftmost].geometry.width += space_left ; - glyphs->glyphs[leftmost].geometry.x_offset += space_left ; - added_so_far += space_left; - } - /* Don't add to right-side of right-most glyph of right-most non-zero run. */ - { - /* Save so we can undo later. */ - rightmost_glyphs = glyphs; - rightmost_space = space_right; - - glyphs->glyphs[rightmost].geometry.width += space_right; - added_so_far += space_right; - } - } - } - } + { + PangoLayoutRun *run = run_iter->data; + PangoGlyphString *glyphs = run->glyphs; + PangoGlyphItemIter cluster_iter; + gboolean have_cluster; + int dir; + int offset; + + dir = run->item->analysis.level % 2 == 0 ? +1 : -1; + + /* We need character offset of the start of the run. We don't have this. + * Compute by counting from the beginning of the line. The naming is + * confusing. Note that: + * + * run->item->offset is byte offset of start of run in layout->text. + * state->line_start_index is byte offset of start of line in layout->text. + * state->line_start_offset is character offset of start of line in layout->text. + */ + g_assert (run->item->offset >= state->line_start_index); + offset = state->line_start_offset + + pango_utf8_strlen (text + state->line_start_index, + run->item->offset - state->line_start_index); + + for (have_cluster = dir > 0 ? + pango_glyph_item_iter_init_start (&cluster_iter, run, text) : + pango_glyph_item_iter_init_end (&cluster_iter, run, text); + have_cluster; + have_cluster = dir > 0 ? + pango_glyph_item_iter_next_cluster (&cluster_iter) : + pango_glyph_item_iter_prev_cluster (&cluster_iter)) + { + int i; + int width = 0; + + /* don't expand in the middle of graphemes */ + if (!log_attrs[offset + cluster_iter.start_char].is_cursor_position) + continue; + + for (i = cluster_iter.start_glyph; i != cluster_iter.end_glyph; i += dir) + width += glyphs->glyphs[i].geometry.width; + + /* also don't expand zero-width clusters. */ + if (width == 0) + continue; + + gaps_so_far++; + + if (mode == ADJUST) + { + int leftmost, rightmost; + int adjustment, space_left, space_right; + + adjustment = total_remaining_width / total_gaps + residual; + if (is_hinted) + { + int old_adjustment = adjustment; + adjustment = PANGO_UNITS_ROUND (adjustment); + residual = old_adjustment - adjustment; + } + /* distribute to before/after */ + distribute_letter_spacing (adjustment, &space_left, &space_right); + + if (cluster_iter.start_glyph < cluster_iter.end_glyph) + { + /* LTR */ + leftmost = cluster_iter.start_glyph; + rightmost = cluster_iter.end_glyph - 1; + } + else + { + /* RTL */ + leftmost = cluster_iter.end_glyph + 1; + rightmost = cluster_iter.start_glyph; + } + /* Don't add to left-side of left-most glyph of left-most non-zero run. */ + if (leftedge) + leftedge = FALSE; + else + { + glyphs->glyphs[leftmost].geometry.width += space_left ; + glyphs->glyphs[leftmost].geometry.x_offset += space_left ; + added_so_far += space_left; + } + /* Don't add to right-side of right-most glyph of right-most non-zero run. */ + { + /* Save so we can undo later. */ + rightmost_glyphs = glyphs; + rightmost_space = space_right; + + glyphs->glyphs[rightmost].geometry.width += space_right; + added_so_far += space_right; + } + } + } + } if (mode == MEASURE) - { - total_gaps = gaps_so_far - 1; - - if (total_gaps == 0) - { - /* a single cluster, can't really justify it */ - return; - } - } + { + total_gaps = gaps_so_far - 1; + + if (total_gaps == 0) + { + /* a single cluster, can't really justify it */ + return; + } + } else /* mode == ADJUST */ { - if (rightmost_glyphs) - { - rightmost_glyphs->glyphs[rightmost_glyphs->num_glyphs - 1].geometry.width -= rightmost_space; - added_so_far -= rightmost_space; - } - } + if (rightmost_glyphs) + { + rightmost_glyphs->glyphs[rightmost_glyphs->num_glyphs - 1].geometry.width -= rightmost_space; + added_so_far -= rightmost_space; + } + } } state->remaining_width -= added_so_far; @@ -5752,7 +5761,7 @@ justify_clusters (PangoLayoutLine *line, static void justify_words (PangoLayoutLine *line, - ParaBreakState *state) + ParaBreakState *state) { const gchar *text = line->layout->text; const PangoLogAttr *log_attrs = line->layout->log_attrs; @@ -5779,71 +5788,71 @@ justify_words (PangoLayoutLine *line, spaces_so_far = 0; for (run_iter = line->runs; run_iter; run_iter = run_iter->next) - { - PangoLayoutRun *run = run_iter->data; - PangoGlyphString *glyphs = run->glyphs; - PangoGlyphItemIter cluster_iter; - gboolean have_cluster; - int offset; - - /* We need character offset of the start of the run. We don't have this. - * Compute by counting from the beginning of the line. The naming is - * confusing. Note that: - * - * run->item->offset is byte offset of start of run in layout->text. - * state->line_start_index is byte offset of start of line in layout->text. - * state->line_start_offset is character offset of start of line in layout->text. - */ - g_assert (run->item->offset >= state->line_start_index); - offset = state->line_start_offset - + pango_utf8_strlen (text + state->line_start_index, - run->item->offset - state->line_start_index); - - for (have_cluster = pango_glyph_item_iter_init_start (&cluster_iter, run, text); - have_cluster; - have_cluster = pango_glyph_item_iter_next_cluster (&cluster_iter)) - { - int i; - int dir; - - if (!log_attrs[offset + cluster_iter.start_char].is_expandable_space) - continue; - - dir = (cluster_iter.start_glyph < cluster_iter.end_glyph) ? 1 : -1; - for (i = cluster_iter.start_glyph; i != cluster_iter.end_glyph; i += dir) - { - int glyph_width = glyphs->glyphs[i].geometry.width; - - if (glyph_width == 0) - continue; - - spaces_so_far += glyph_width; - - if (mode == ADJUST) - { - int adjustment; - - adjustment = ((guint64) spaces_so_far * total_remaining_width) / total_space_width - added_so_far; - if (is_hinted) - adjustment = PANGO_UNITS_ROUND (adjustment); - - glyphs->glyphs[i].geometry.width += adjustment; - added_so_far += adjustment; - } - } - } - } + { + PangoLayoutRun *run = run_iter->data; + PangoGlyphString *glyphs = run->glyphs; + PangoGlyphItemIter cluster_iter; + gboolean have_cluster; + int offset; + + /* We need character offset of the start of the run. We don't have this. + * Compute by counting from the beginning of the line. The naming is + * confusing. Note that: + * + * run->item->offset is byte offset of start of run in layout->text. + * state->line_start_index is byte offset of start of line in layout->text. + * state->line_start_offset is character offset of start of line in layout->text. + */ + g_assert (run->item->offset >= state->line_start_index); + offset = state->line_start_offset + + pango_utf8_strlen (text + state->line_start_index, + run->item->offset - state->line_start_index); + + for (have_cluster = pango_glyph_item_iter_init_start (&cluster_iter, run, text); + have_cluster; + have_cluster = pango_glyph_item_iter_next_cluster (&cluster_iter)) + { + int i; + int dir; + + if (!log_attrs[offset + cluster_iter.start_char].is_expandable_space) + continue; + + dir = (cluster_iter.start_glyph < cluster_iter.end_glyph) ? 1 : -1; + for (i = cluster_iter.start_glyph; i != cluster_iter.end_glyph; i += dir) + { + int glyph_width = glyphs->glyphs[i].geometry.width; + + if (glyph_width == 0) + continue; + + spaces_so_far += glyph_width; + + if (mode == ADJUST) + { + int adjustment; + + adjustment = ((guint64) spaces_so_far * total_remaining_width) / total_space_width - added_so_far; + if (is_hinted) + adjustment = PANGO_UNITS_ROUND (adjustment); + + glyphs->glyphs[i].geometry.width += adjustment; + added_so_far += adjustment; + } + } + } + } if (mode == MEASURE) - { - total_space_width = spaces_so_far; + { + total_space_width = spaces_so_far; - if (total_space_width == 0) - { - justify_clusters (line, state); - return; - } - } + if (total_space_width == 0) + { + justify_clusters (line, state); + return; + } + } } state->remaining_width -= added_so_far; @@ -5851,8 +5860,8 @@ justify_words (PangoLayoutLine *line, static void pango_layout_line_postprocess (PangoLayoutLine *line, - ParaBreakState *state, - gboolean wrapped) + ParaBreakState *state, + gboolean wrapped) { gboolean ellipsized = FALSE; @@ -5872,7 +5881,7 @@ pango_layout_line_postprocess (PangoLayoutLine *line, /* Ellipsize the line if necessary */ if (G_UNLIKELY (state->line_width >= 0 && - should_ellipsize_current_line (line->layout, state))) + should_ellipsize_current_line (line->layout, state))) { PangoShapeFlags shape_flags = PANGO_SHAPE_NONE; @@ -5902,7 +5911,7 @@ pango_layout_line_postprocess (PangoLayoutLine *line, { /* if we ellipsized, we don't have remaining_width set */ if (state->remaining_width < 0) - state->remaining_width = state->line_width - pango_layout_line_get_width (line); + state->remaining_width = state->line_width - pango_layout_line_get_width (line); justify_words (line, state); } @@ -5915,7 +5924,7 @@ pango_layout_line_postprocess (PangoLayoutLine *line, static void pango_layout_get_item_properties (PangoItem *item, - ItemProperties *properties) + ItemProperties *properties) { GSList *tmp_list = item->analysis.extra_attrs; @@ -5936,8 +5945,8 @@ pango_layout_get_item_properties (PangoItem *item, PangoAttribute *attr = tmp_list->data; switch ((int) attr->klass->type) - { - case PANGO_ATTR_UNDERLINE: + { + case PANGO_ATTR_UNDERLINE: switch (((PangoAttrInt *)attr)->value) { case PANGO_UNDERLINE_NONE: @@ -5961,48 +5970,48 @@ pango_layout_get_item_properties (PangoItem *item, g_assert_not_reached (); break; } - break; + break; - case PANGO_ATTR_OVERLINE: + case PANGO_ATTR_OVERLINE: switch (((PangoAttrInt *)attr)->value) { case PANGO_OVERLINE_SINGLE: - properties->oline_single = TRUE; + properties->oline_single = TRUE; break; default: g_assert_not_reached (); break; } - break; + break; - case PANGO_ATTR_STRIKETHROUGH: - properties->strikethrough = ((PangoAttrInt *)attr)->value; - break; + case PANGO_ATTR_STRIKETHROUGH: + properties->strikethrough = ((PangoAttrInt *)attr)->value; + break; - case PANGO_ATTR_RISE: - properties->rise = ((PangoAttrInt *)attr)->value; - break; + case PANGO_ATTR_RISE: + properties->rise = ((PangoAttrInt *)attr)->value; + break; - case PANGO_ATTR_LETTER_SPACING: - properties->letter_spacing = ((PangoAttrInt *)attr)->value; - break; + case PANGO_ATTR_LETTER_SPACING: + properties->letter_spacing = ((PangoAttrInt *)attr)->value; + break; - case PANGO_ATTR_SHAPE: - properties->shape_set = TRUE; - properties->shape_logical_rect = &((PangoAttrShape *)attr)->logical_rect; - properties->shape_ink_rect = &((PangoAttrShape *)attr)->ink_rect; - break; + case PANGO_ATTR_SHAPE: + properties->shape_set = TRUE; + properties->shape_logical_rect = &((PangoAttrShape *)attr)->logical_rect; + properties->shape_ink_rect = &((PangoAttrShape *)attr)->ink_rect; + break; - default: - break; - } + default: + break; + } tmp_list = tmp_list->next; } } static int next_cluster_start (PangoGlyphString *gs, - int cluster_start) + int cluster_start) { int i; @@ -6010,7 +6019,7 @@ next_cluster_start (PangoGlyphString *gs, while (i < gs->num_glyphs) { if (gs->glyphs[i].attr.is_cluster_start) - return i; + return i; i++; } @@ -6020,7 +6029,7 @@ next_cluster_start (PangoGlyphString *gs, static int cluster_width (PangoGlyphString *gs, - int cluster_start) + int cluster_start) { int i; int width; @@ -6030,7 +6039,7 @@ cluster_width (PangoGlyphString *gs, while (i < gs->num_glyphs) { if (gs->glyphs[i].attr.is_cluster_start) - break; + break; width += gs->glyphs[i].geometry.width; i++; @@ -6041,7 +6050,7 @@ cluster_width (PangoGlyphString *gs, static inline void offset_y (PangoLayoutIter *iter, - int *y) + int *y) { *y += iter->line_extents[iter->line_index].baseline; } @@ -6051,7 +6060,7 @@ offset_y (PangoLayoutIter *iter, */ static void update_cluster (PangoLayoutIter *iter, - int cluster_start_index) + int cluster_start_index) { char *cluster_text; PangoGlyphString *gs; @@ -6069,9 +6078,9 @@ update_cluster (PangoLayoutIter *iter, * since logical and visual runs are in the same direction. */ if (iter->next_cluster_glyph < gs->num_glyphs) - cluster_length = gs->log_clusters[iter->next_cluster_glyph] - cluster_start_index; + cluster_length = gs->log_clusters[iter->next_cluster_glyph] - cluster_start_index; else - cluster_length = iter->run->item->length - cluster_start_index; + cluster_length = iter->run->item->length - cluster_start_index; } else { @@ -6080,12 +6089,12 @@ update_cluster (PangoLayoutIter *iter, */ int i = iter->cluster_start; while (i > 0 && gs->log_clusters[i - 1] == cluster_start_index) - i--; + i--; if (i == 0) - cluster_length = iter->run->item->length - cluster_start_index; + cluster_length = iter->run->item->length - cluster_start_index; else - cluster_length = gs->log_clusters[i - 1] - cluster_start_index; + cluster_length = gs->log_clusters[i - 1] - cluster_start_index; } cluster_text = iter->layout->text + iter->run->item->offset + cluster_start_index; @@ -6099,7 +6108,7 @@ update_cluster (PangoLayoutIter *iter, static void update_run (PangoLayoutIter *iter, - int run_start_index) + int run_start_index) { const Extents *line_ext = &iter->line_extents[iter->line_index]; @@ -6145,16 +6154,16 @@ update_run (PangoLayoutIter *iter, /** * pango_layout_iter_copy: - * @iter: (nullable): a #PangoLayoutIter, may be %NULL + * @iter: (nullable): a `PangoLayoutIter`, may be %NULL * - * Copies a #PangoLayoutIter. + * Copies a `PangoLayoutIter`. * - * Return value: (nullable): the newly allocated #PangoLayoutIter, - * which should be freed with pango_layout_iter_free(), - * or %NULL if @iter was %NULL. + * Return value: (nullable): the newly allocated `PangoLayoutIter`, + * which should be freed with [method@Pango.LayoutIter.free], + * or %NULL if @iter was %NULL. * * Since: 1.20 - **/ + */ PangoLayoutIter * pango_layout_iter_copy (PangoLayoutIter *iter) { @@ -6207,13 +6216,13 @@ G_DEFINE_BOXED_TYPE (PangoLayoutIter, pango_layout_iter, /** * pango_layout_get_iter: - * @layout: a #PangoLayout + * @layout: a `PangoLayout` * * Returns an iterator to iterate over the visual extents of the layout. * - * Return value: the new #PangoLayoutIter that should be freed using - * pango_layout_iter_free(). - **/ + * Return value: the new `PangoLayoutIter` that should be freed using + * [method@Pango.LayoutIter.free]. + */ PangoLayoutIter* pango_layout_get_iter (PangoLayout *layout) { @@ -6293,7 +6302,7 @@ _pango_layout_iter_destroy (PangoLayoutIter *iter) /** * pango_layout_iter_free: - * @iter: (nullable): a #PangoLayoutIter, may be %NULL + * @iter: (nullable): a `PangoLayoutIter`, may be %NULL * * Frees an iterator that's no longer in use. **/ @@ -6309,15 +6318,15 @@ pango_layout_iter_free (PangoLayoutIter *iter) /** * pango_layout_iter_get_index: - * @iter: a #PangoLayoutIter + * @iter: a `PangoLayoutIter` * * Gets the current byte index. Note that iterating forward by char * moves in visual order, not logical order, so indexes may not be * sequential. Also, the index may be equal to the length of the text - * in the layout, if on the %NULL run (see pango_layout_iter_get_run()). + * in the layout, if on the %NULL run (see [method@Pango.LayoutIter.get_run]). * * Return value: current byte index. - **/ + */ int pango_layout_iter_get_index (PangoLayoutIter *iter) { @@ -6329,18 +6338,18 @@ pango_layout_iter_get_index (PangoLayoutIter *iter) /** * pango_layout_iter_get_run: - * @iter: a #PangoLayoutIter + * @iter: a `PangoLayoutIter` * * Gets the current run. When iterating by run, at the end of each * line, there's a position with a %NULL run, so this function can return * %NULL. The %NULL run at the end of each line ensures that all lines have * at least one run, even lines consisting of only a newline. * - * Use the faster pango_layout_iter_get_run_readonly() if you do not plan - * to modify the contents of the run (glyphs, glyph widths, etc.). + * Use the faster [method@Pango.LayoutIter.get_run_readonly] if you do not + * plan to modify the contents of the run (glyphs, glyph widths, etc.). * * Return value: (transfer none) (nullable): the current run. - **/ + */ PangoLayoutRun* pango_layout_iter_get_run (PangoLayoutIter *iter) { @@ -6354,22 +6363,22 @@ pango_layout_iter_get_run (PangoLayoutIter *iter) /** * pango_layout_iter_get_run_readonly: - * @iter: a #PangoLayoutIter + * @iter: a `PangoLayoutIter` * * Gets the current run. When iterating by run, at the end of each * line, there's a position with a %NULL run, so this function can return * %NULL. The %NULL run at the end of each line ensures that all lines have * at least one run, even lines consisting of only a newline. * - * This is a faster alternative to pango_layout_iter_get_run(), - * but the user is not expected - * to modify the contents of the run (glyphs, glyph widths, etc.). + * This is a faster alternative to [method@Pango.LayoutIter.get_run], + * but the user is not expected to modify the contents of the run (glyphs, + * glyph widths, etc.). * * Return value: (transfer none) (nullable): the current run, that * should not be modified. * * Since: 1.16 - **/ + */ PangoLayoutRun* pango_layout_iter_get_run_readonly (PangoLayoutIter *iter) { @@ -6390,15 +6399,16 @@ _pango_layout_iter_get_line (PangoLayoutIter *iter) /** * pango_layout_iter_get_line: - * @iter: a #PangoLayoutIter + * @iter: a `PangoLayoutIter` * * Gets the current line. * - * Use the faster pango_layout_iter_get_line_readonly() if you do not plan - * to modify the contents of the line (glyphs, glyph widths, etc.). + * Use the faster [method@Pango.LayoutIter.get_line_readonly] if + * you do not plan to modify the contents of the line (glyphs, + * glyph widths, etc.). * * Return value: (transfer none): the current line. - **/ + */ PangoLayoutLine* pango_layout_iter_get_line (PangoLayoutIter *iter) { @@ -6412,19 +6422,19 @@ pango_layout_iter_get_line (PangoLayoutIter *iter) /** * pango_layout_iter_get_line_readonly: - * @iter: a #PangoLayoutIter + * @iter: a `PangoLayoutIter` * * Gets the current line for read-only access. * - * This is a faster alternative to pango_layout_iter_get_line(), - * but the user is not expected - * to modify the contents of the line (glyphs, glyph widths, etc.). + * This is a faster alternative to [method@Pango.LayoutIter.get_line], + * but the user is not expected to modify the contents of the line + * (glyphs, glyph widths, etc.). * * Return value: (transfer none): the current line, that should not be * modified. * * Since: 1.16 - **/ + */ PangoLayoutLine* pango_layout_iter_get_line_readonly (PangoLayoutIter *iter) { @@ -6436,12 +6446,12 @@ pango_layout_iter_get_line_readonly (PangoLayoutIter *iter) /** * pango_layout_iter_at_last_line: - * @iter: a #PangoLayoutIter + * @iter: a `PangoLayoutIter` * * Determines whether @iter is on the last line of the layout. * * Return value: %TRUE if @iter is on the last line. - **/ + */ gboolean pango_layout_iter_at_last_line (PangoLayoutIter *iter) { @@ -6453,14 +6463,14 @@ pango_layout_iter_at_last_line (PangoLayoutIter *iter) /** * pango_layout_iter_get_layout: - * @iter: a #PangoLayoutIter + * @iter: a `PangoLayoutIter` * - * Gets the layout associated with a #PangoLayoutIter. + * Gets the layout associated with a `PangoLayoutIter`. * * Return value: (transfer none): the layout associated with @iter. * * Since: 1.20 - **/ + */ PangoLayout* pango_layout_iter_get_layout (PangoLayoutIter *iter) { @@ -6471,7 +6481,6 @@ pango_layout_iter_get_layout (PangoLayoutIter *iter) return iter->layout; } - static gboolean line_is_terminated (PangoLayoutIter *iter) { @@ -6482,7 +6491,7 @@ line_is_terminated (PangoLayoutIter *iter) { PangoLayoutLine *next_line = iter->line_list_link->next->data; if (next_line->is_paragraph_start) - return TRUE; + return TRUE; } return FALSE; @@ -6494,7 +6503,7 @@ line_is_terminated (PangoLayoutIter *iter) */ static gboolean next_nonempty_line (PangoLayoutIter *iter, - gboolean include_terminators) + gboolean include_terminators) { gboolean result; @@ -6502,13 +6511,13 @@ next_nonempty_line (PangoLayoutIter *iter, { result = pango_layout_iter_next_line (iter); if (!result) - break; + break; if (iter->line->runs) - break; + break; if (include_terminators && line_is_terminated (iter)) - break; + break; } return result; @@ -6520,7 +6529,7 @@ next_nonempty_line (PangoLayoutIter *iter, */ static gboolean next_nonempty_run (PangoLayoutIter *iter, - gboolean include_terminators) + gboolean include_terminators) { gboolean result; @@ -6528,13 +6537,13 @@ next_nonempty_run (PangoLayoutIter *iter, { result = pango_layout_iter_next_run (iter); if (!result) - break; + break; if (iter->run) - break; + break; if (include_terminators && line_is_terminated (iter)) - break; + break; } return result; @@ -6546,7 +6555,7 @@ next_nonempty_run (PangoLayoutIter *iter, */ static gboolean next_cluster_internal (PangoLayoutIter *iter, - gboolean include_terminators) + gboolean include_terminators) { PangoGlyphString *gs; int next_start; @@ -6576,13 +6585,13 @@ next_cluster_internal (PangoLayoutIter *iter, /** * pango_layout_iter_next_char: - * @iter: a #PangoLayoutIter + * @iter: a `PangoLayoutIter` * - * Moves @iter forward to the next character in visual order. If @iter was already at - * the end of the layout, returns %FALSE. + * Moves @iter forward to the next character in visual order. + * If @iter was already at the end of the layout, returns %FALSE. * * Return value: whether motion was possible. - **/ + */ gboolean pango_layout_iter_next_char (PangoLayoutIter *iter) { @@ -6595,12 +6604,12 @@ pango_layout_iter_next_char (PangoLayoutIter *iter) { /* We need to fake an iterator position in the middle of a \r\n line terminator */ if (line_is_terminated (iter) && - strncmp (iter->layout->text + iter->line->start_index + iter->line->length, "\r\n", 2) == 0 && - iter->character_position == 0) - { - iter->character_position++; - return TRUE; - } + strncmp (iter->layout->text + iter->line->start_index + iter->line->length, "\r\n", 2) == 0 && + iter->character_position == 0) + { + iter->character_position++; + return TRUE; + } return next_nonempty_line (iter, TRUE); } @@ -6620,13 +6629,13 @@ pango_layout_iter_next_char (PangoLayoutIter *iter) /** * pango_layout_iter_next_cluster: - * @iter: a #PangoLayoutIter + * @iter: a `PangoLayoutIter` * - * Moves @iter forward to the next cluster in visual order. If @iter - * was already at the end of the layout, returns %FALSE. + * Moves @iter forward to the next cluster in visual order. + * If @iter was already at the end of the layout, returns %FALSE. * * Return value: whether motion was possible. - **/ + */ gboolean pango_layout_iter_next_cluster (PangoLayoutIter *iter) { @@ -6635,13 +6644,13 @@ pango_layout_iter_next_cluster (PangoLayoutIter *iter) /** * pango_layout_iter_next_run: - * @iter: a #PangoLayoutIter + * @iter: a `PangoLayoutIter` * - * Moves @iter forward to the next run in visual order. If @iter was - * already at the end of the layout, returns %FALSE. + * Moves @iter forward to the next run in visual order. + * If @iter was already at the end of the layout, returns %FALSE. * * Return value: whether motion was possible. - **/ + */ gboolean pango_layout_iter_next_run (PangoLayoutIter *iter) { @@ -6679,13 +6688,13 @@ pango_layout_iter_next_run (PangoLayoutIter *iter) /** * pango_layout_iter_next_line: - * @iter: a #PangoLayoutIter + * @iter: a `PangoLayoutIter` * - * Moves @iter forward to the start of the next line. If @iter is - * already on the last line, returns %FALSE. + * Moves @iter forward to the start of the next line. + * If @iter is already on the last line, returns %FALSE. * * Return value: whether motion was possible. - **/ + */ gboolean pango_layout_iter_next_line (PangoLayoutIter *iter) { @@ -6723,7 +6732,7 @@ pango_layout_iter_next_line (PangoLayoutIter *iter) /** * pango_layout_iter_get_char_extents: - * @iter: a #PangoLayoutIter + * @iter: a `PangoLayoutIter` * @logical_rect: (out caller-allocates): rectangle to fill with * logical extents * @@ -6731,11 +6740,10 @@ pango_layout_iter_next_line (PangoLayoutIter *iter) * (origin is the top left of the entire layout). Only logical extents * can sensibly be obtained for characters; ink extents make sense only * down to the level of clusters. - * - **/ + */ void pango_layout_iter_get_char_extents (PangoLayoutIter *iter, - PangoRectangle *logical_rect) + PangoRectangle *logical_rect) { PangoRectangle cluster_rect; int x0, x1; @@ -6775,18 +6783,17 @@ pango_layout_iter_get_char_extents (PangoLayoutIter *iter, /** * pango_layout_iter_get_cluster_extents: - * @iter: a #PangoLayoutIter + * @iter: a `PangoLayoutIter` * @ink_rect: (out) (allow-none): rectangle to fill with ink extents, or %NULL * @logical_rect: (out) (allow-none): rectangle to fill with logical extents, or %NULL * * Gets the extents of the current cluster, in layout coordinates * (origin is the top left of the entire layout). - * - **/ + */ void pango_layout_iter_get_cluster_extents (PangoLayoutIter *iter, - PangoRectangle *ink_rect, - PangoRectangle *logical_rect) + PangoRectangle *ink_rect, + PangoRectangle *logical_rect) { if (ITER_IS_INVALID (iter)) return; @@ -6801,11 +6808,11 @@ pango_layout_iter_get_cluster_extents (PangoLayoutIter *iter, } pango_glyph_string_extents_range (iter->run->glyphs, - iter->cluster_start, - iter->next_cluster_glyph, - iter->run->item->analysis.font, - ink_rect, - logical_rect); + iter->cluster_start, + iter->next_cluster_glyph, + iter->run->item->analysis.font, + ink_rect, + logical_rect); if (ink_rect) { @@ -6823,18 +6830,17 @@ pango_layout_iter_get_cluster_extents (PangoLayoutIter *iter, /** * pango_layout_iter_get_run_extents: - * @iter: a #PangoLayoutIter + * @iter: a `PangoLayoutIter` * @ink_rect: (out) (allow-none): rectangle to fill with ink extents, or %NULL * @logical_rect: (out) (allow-none): rectangle to fill with logical extents, or %NULL * * Gets the extents of the current run in layout coordinates * (origin is the top left of the entire layout). - * - **/ + */ void pango_layout_iter_get_run_extents (PangoLayoutIter *iter, - PangoRectangle *ink_rect, - PangoRectangle *logical_rect) + PangoRectangle *ink_rect, + PangoRectangle *logical_rect) { if (G_UNLIKELY (!ink_rect && !logical_rect)) return; @@ -6847,16 +6853,16 @@ pango_layout_iter_get_run_extents (PangoLayoutIter *iter, pango_layout_run_get_extents_and_height (iter->run, ink_rect, logical_rect, NULL); if (ink_rect) - { - offset_y (iter, &ink_rect->y); - ink_rect->x += iter->run_x; - } + { + offset_y (iter, &ink_rect->y); + ink_rect->x += iter->run_x; + } if (logical_rect) - { - offset_y (iter, &logical_rect->y); - logical_rect->x += iter->run_x; - } + { + offset_y (iter, &logical_rect->y); + logical_rect->x += iter->run_x; + } } else { @@ -6865,37 +6871,36 @@ pango_layout_iter_get_run_extents (PangoLayoutIter *iter, pango_layout_iter_get_line_extents (iter, ink_rect, logical_rect); if (ink_rect) - { - ink_rect->x = iter->run_x; - ink_rect->width = 0; - } + { + ink_rect->x = iter->run_x; + ink_rect->width = 0; + } if (logical_rect) - { - logical_rect->x = iter->run_x; - logical_rect->width = 0; - } + { + logical_rect->x = iter->run_x; + logical_rect->width = 0; + } } } /** * pango_layout_iter_get_line_extents: - * @iter: a #PangoLayoutIter + * @iter: a `PangoLayoutIter` * @ink_rect: (out) (allow-none): rectangle to fill with ink extents, or %NULL * @logical_rect: (out) (allow-none): rectangle to fill with logical extents, or %NULL * * Obtains the extents of the current line. @ink_rect or @logical_rect * can be %NULL if you aren't interested in them. Extents are in layout * coordinates (origin is the top-left corner of the entire - * #PangoLayout). Thus the extents returned by this function will be + * `PangoLayout`). Thus the extents returned by this function will be * the same width/height but not at the same x/y as the extents - * returned from pango_layout_line_get_extents(). - * - **/ + * returned from [method@Pango.LayoutLine.get_extents]. + */ void pango_layout_iter_get_line_extents (PangoLayoutIter *iter, - PangoRectangle *ink_rect, - PangoRectangle *logical_rect) + PangoRectangle *ink_rect, + PangoRectangle *logical_rect) { const Extents *ext; @@ -6907,11 +6912,11 @@ pango_layout_iter_get_line_extents (PangoLayoutIter *iter, if (ink_rect) { get_line_extents_layout_coords (iter->layout, iter->line, - iter->layout_width, - ext->logical_rect.y, + iter->layout_width, + ext->logical_rect.y, NULL, - ink_rect, - NULL); + ink_rect, + NULL); } if (logical_rect) @@ -6920,26 +6925,25 @@ pango_layout_iter_get_line_extents (PangoLayoutIter *iter, /** * pango_layout_iter_get_line_yrange: - * @iter: a #PangoLayoutIter + * @iter: a `PangoLayoutIter` * @y0_: (out) (allow-none): start of line, or %NULL * @y1_: (out) (allow-none): end of line, or %NULL * - * Divides the vertical space in the #PangoLayout being iterated over + * Divides the vertical space in the `PangoLayout` being iterated over * between the lines in the layout, and returns the space belonging to - * the current line. A line's range includes the line's logical - * extents, plus half of the spacing above and below the line, if - * pango_layout_set_spacing() has been called to set layout spacing. + * the current line. A line's range includes the line's logical extents, + * plus half of the spacing above and below the line, if + * [method@Pango.Layout.set_spacing] has been called to set layout spacing. * The Y positions are in layout coordinates (origin at top left of the * entire layout). * - * Note: Since 1.44, Pango uses line heights for placing lines, - * and there may be gaps between the ranges returned by this - * function. + * Note: Since 1.44, Pango uses line heights for placing lines, and there + * may be gaps between the ranges returned by this function. */ void pango_layout_iter_get_line_yrange (PangoLayoutIter *iter, - int *y0, - int *y1) + int *y0, + int *y1) { const Extents *ext; int half_spacing; @@ -6960,30 +6964,30 @@ pango_layout_iter_get_line_yrange (PangoLayoutIter *iter, /* No spacing above the first line */ if (iter->line_index == 0) - *y0 = ext->logical_rect.y; + *y0 = ext->logical_rect.y; else - *y0 = ext->logical_rect.y - (iter->layout->spacing - half_spacing); + *y0 = ext->logical_rect.y - (iter->layout->spacing - half_spacing); } if (y1) { /* No spacing below the last line */ if (iter->line_index == iter->layout->line_count - 1) - *y1 = ext->logical_rect.y + ext->logical_rect.height; + *y1 = ext->logical_rect.y + ext->logical_rect.height; else - *y1 = ext->logical_rect.y + ext->logical_rect.height + half_spacing; + *y1 = ext->logical_rect.y + ext->logical_rect.height + half_spacing; } } /** * pango_layout_iter_get_baseline: - * @iter: a #PangoLayoutIter + * @iter: a `PangoLayoutIter` * * Gets the Y position of the current line's baseline, in layout * coordinates (origin at top left of the entire layout). * * Return value: baseline of current line. - **/ + */ int pango_layout_iter_get_baseline (PangoLayoutIter *iter) { @@ -6995,21 +6999,17 @@ pango_layout_iter_get_baseline (PangoLayoutIter *iter) /** * pango_layout_iter_get_layout_extents: - * @iter: a #PangoLayoutIter - * @ink_rect: (out) (allow-none): rectangle to fill with ink extents, - * or %NULL - * @logical_rect: (out) (allow-none): rectangle to fill with logical - * extents, or %NULL - * - * Obtains the extents of the #PangoLayout being iterated - * over. @ink_rect or @logical_rect can be %NULL if you - * aren't interested in them. + * @iter: a `PangoLayoutIter` + * @ink_rect: (out) (allow-none): rectangle to fill with ink extents, or %NULL + * @logical_rect: (out) (allow-none): rectangle to fill with logical extents, or %NULL * - **/ + * Obtains the extents of the `PangoLayout` being iterated over. + * @ink_rect or @logical_rect can be %NULL if you aren't interested in them. + */ void pango_layout_iter_get_layout_extents (PangoLayoutIter *iter, - PangoRectangle *ink_rect, - PangoRectangle *logical_rect) + PangoRectangle *ink_rect, + PangoRectangle *logical_rect) { if (ITER_IS_INVALID (iter)) return; diff --git a/pango/pango-layout.h b/pango/pango-layout.h index d0a4fe8f..4a464230 100644 --- a/pango/pango-layout.h +++ b/pango/pango-layout.h @@ -36,10 +36,10 @@ typedef struct _PangoLayoutLine PangoLayoutLine; /** * PangoLayoutRun: * - * The #PangoLayoutRun structure represents a single run within - * a #PangoLayoutLine; it is simply an alternate name for - * #PangoGlyphItem. - * See the #PangoGlyphItem docs for details on the fields. + * A `PangoLayoutRun` represents a single run within a `PangoLayoutLine`. + * + * It is simply an alternate name for [struct@Pango.GlyphItem]. + * See the [struct@Pango.GlyphItem] docs for details on the fields. */ typedef PangoGlyphItem PangoLayoutRun; @@ -49,9 +49,11 @@ typedef PangoGlyphItem PangoLayoutRun; * @PANGO_ALIGN_CENTER: Center the line within the available space * @PANGO_ALIGN_RIGHT: Put all available space on the left * - * A #PangoAlignment describes how to align the lines of a #PangoLayout within the - * available space. If the #PangoLayout is set to justify - * using pango_layout_set_justify(), this only has effect for partial lines. + * `PangoAlignment` describes how to align the lines of a `PangoLayout` + * within the available space. + * + * If the `PangoLayout` is set to justify using [method@Pango.Layout.set_justify], + * this only has effect for partial lines. */ typedef enum { PANGO_ALIGN_LEFT, @@ -63,10 +65,11 @@ typedef enum { * PangoWrapMode: * @PANGO_WRAP_WORD: wrap lines at word boundaries. * @PANGO_WRAP_CHAR: wrap lines at character boundaries. - * @PANGO_WRAP_WORD_CHAR: wrap lines at word boundaries, but fall back to character boundaries if there is not - * enough space for a full word. + * @PANGO_WRAP_WORD_CHAR: wrap lines at word boundaries, but fall back to + * character boundaries if there is not enough space for a full word. * - * A #PangoWrapMode describes how to wrap the lines of a #PangoLayout to the desired width. + * `PangoWrapMode` describes how to wrap the lines of a `PangoLayout` + * to the desired width. */ typedef enum { PANGO_WRAP_WORD, @@ -81,9 +84,10 @@ typedef enum { * @PANGO_ELLIPSIZE_MIDDLE: Omit characters in the middle of the text * @PANGO_ELLIPSIZE_END: Omit characters at the end of the text * - * The #PangoEllipsizeMode type describes what sort of (if any) - * ellipsization should be applied to a line of text. In - * the ellipsization process characters are removed from the + * `PangoEllipsizeMode` describes what sort of ellipsization + * should be applied to text. + * + * In the ellipsization process characters are removed from the * text in order to make it fit to a given width and replaced * with an ellipsis. */ @@ -104,14 +108,12 @@ typedef enum { * @is_paragraph_start: #TRUE if this is the first line of the paragraph * @resolved_dir: #Resolved PangoDirection of line * - * The #PangoLayoutLine structure represents one of the lines resulting - * from laying out a paragraph via #PangoLayout. #PangoLayoutLine - * structures are obtained by calling pango_layout_get_line() and - * are only valid until the text, attributes, or settings of the - * parent #PangoLayout are modified. + * A `PangoLayoutLine` represents one of the lines resulting from laying + * out a paragraph via `PangoLayout`. * - * Routines for rendering PangoLayout objects are provided in - * code specific to each rendering system. + * `PangoLayoutLine` structures are obtained by calling + * [method@Pango.Layout.get_line] and are only valid until the text, + * attributes, or settings of the parent `PangoLayout` are modified. */ struct _PangoLayoutLine { diff --git a/pango/pango-markup.c b/pango/pango-markup.c index b74c1ad4..eca3e630 100644 --- a/pango/pango-markup.c +++ b/pango/pango-markup.c @@ -30,197 +30,6 @@ #include "pango-impl-utils.h" #include "pango-utils-internal.h" -/** - * SECTION:markup - * @title:Markup - * @short_description:Simple markup language for text with attributes - * - * Frequently, you want to display some text to the user with attributes - * applied to part of the text (for example, you might want bold or - * italicized words). With the base Pango interfaces, you could create a - * #PangoAttrList and apply it to the text; the problem is that you'd - * need to apply attributes to some numeric range of characters, for - * example "characters 12-17." This is broken from an internationalization - * standpoint; once the text is translated, the word you wanted to - * italicize could be in a different position. - * - * The solution is to include the text attributes in the string to be - * translated. Pango provides this feature with a small markup language. - * You can parse a marked-up string into the string text plus a - * #PangoAttrList using either of pango_parse_markup() or - * pango_markup_parser_new(). - * - * A simple example of a marked-up string might be: - * |[ - * <span foreground="blue" size="x-large">Blue text</span> is <i>cool</i>! - * ]| - * - * Pango uses #GMarkup to parse this language, which means that XML - * features such as numeric character entities such as `©` for - * © can be used too. - * - * The root tag of a marked-up document is `<markup>`, but - * pango_parse_markup() allows you to omit this tag, so you will most - * likely never need to use it. The most general markup tag is `<span>`, - * then there are some convenience tags. - * - * ## Span attributes - * - * `<span>` has the following attributes: - * - * * `font_desc`: - * A font description string, such as "Sans Italic 12". - * See pango_font_description_from_string() for a description of the - * format of the string representation . Note that any other span - * attributes will override this description. So if you have "Sans Italic" - * and also a `style="normal"` attribute, you will get Sans normal, - * not italic. - * - * * `font_family`: - * A font family name - * - * * `font_size`, `size`: - * Font size in 1024ths of a point, or one of the absolute - * sizes `xx-small`, `x-small`, `small`, `medium`, `large`, - * `x-large`, `xx-large`, or one of the relative sizes `smaller` - * or `larger`. If you want to specify a absolute size, it's usually - * easier to take advantage of the ability to specify a partial - * font description using `font`; you can use `font='12.5'` - * rather than `size='12800'`. - * - * * `font_style`: - * One of `normal`, `oblique`, `italic` - * - * * `font_weight`: - * One of `ultralight`, `light`, `normal`, `bold`, - * `ultrabold`, `heavy`, or a numeric weight - * - * * `font_variant`: - * One of `normal` or `smallcaps` - * - * * `font_stretch`, `stretch`: - * One of `ultracondensed`, `extracondensed`, `condensed`, - * `semicondensed`, `normal`, `semiexpanded`, `expanded`, - * `extraexpanded`, `ultraexpanded` - * - * * `font_features`: - * A comma-separated list of OpenType font feature - * settings, in the same syntax as accepted by CSS. E.g: - * `font_features='dlig=1, -kern, afrc on'` - * - * * `foreground`, `fgcolor`: - * An RGB color specification such as `#00FF00` or a color - * name such as `red`. Since 1.38, an RGBA color specification such - * as `#00FF007F` will be interpreted as specifying both a foreground - * color and foreground alpha. - * - * * `background`, `bgcolor`: - * An RGB color specification such as `#00FF00` or a color - * name such as `red`. - * Since 1.38, an RGBA color specification such as `#00FF007F` will - * be interpreted as specifying both a background color and - * background alpha. - * - * * `alpha`, `fgalpha`: - * An alpha value for the foreground color, either a plain - * integer between 1 and 65536 or a percentage value like `50%`. - * - * * `background_alpha`, `bgalpha`: - * An alpha value for the background color, either a plain - * integer between 1 and 65536 or a percentage value like `50%`. - * - * * `underline`: - * One of `none`, `single`, `double`, `low`, `error`, - * `single-line`, `double-line` or `error-line`. - * - * * `underline_color`: - * The color of underlines; an RGB color - * specification such as `#00FF00` or a color name such as `red` - * - * * `overline`: - * One of `none` or `single` - * - * * `overline_color`: - * The color of overlines; an RGB color - * specification such as `#00FF00` or a color name such as `red` - * - * * `rise`: - * Vertical displacement, in Pango units. Can be negative for - * subscript, positive for superscript. - * - * * `strikethrough` - * `true` or `false` whether to strike through the text - * - * * `strikethrough_color`: - * The color of strikethrough lines; an RGB - * color specification such as `#00FF00` or a color name such as `red` - * - * * `fallback`: - * `true` or `false` whether to enable fallback. If - * disabled, then characters will only be used from the closest - * matching font on the system. No fallback will be done to other - * fonts on the system that might contain the characters in the text. - * Fallback is enabled by default. Most applications should not - * disable fallback. - * - * * `allow_breaks`: - * `true` or `false` whether to allow line breaks or not. If - * not allowed, the range will be kept in a single run as far - * as possible. Breaks are allowed by default. - * - * * `insert_hyphens`:` - * `true` or `false` whether to insert hyphens when breaking - * lines in the middle of a word. Hyphens are inserted by default. - * - * * `show`: - * A value determining how invisible characters are treated. - * Possible values are `spaces`, `line-breaks`, `ignorables` - * or combinations, such as `spaces|line-breaks`. - * - * * `lang`: - * A language code, indicating the text language - * - * * `letter_spacing`: - * Inter-letter spacing in 1024ths of a point. - * - * * `gravity`: - * One of `south`, `east`, `north`, `west`, `auto`. - * - * * `gravity_hint`: - * One of `natural`, `strong`, `line`. - * - * ## Convenience tags - * - * The following convenience tags are provided: - * - * * `<b>`: - * Bold - * - * * `<big>`: - * Makes font relatively larger, equivalent to `<span size="larger">` - * - * * `<i>`: - * Italic - * - * * `<s>`: - * Strikethrough - * - * * `<sub>`: - * Subscript - * - * * `<sup>`: - * Superscript - * - * * `<small>`: - * Makes font relatively smaller, equivalent to `<span size="smaller">` - * - * * `<tt>`: - * Monospace - * - * * `<u>`: - * Underline - */ - /* FIXME */ #define _(x) x @@ -677,8 +486,21 @@ text_handler (GMarkupParseContext *context G_GNUC_UNUSED, /* The underline should go underneath the char * we're setting as the next range_start */ - uline_index = md->index; - uline_len = g_utf8_next_char (p) - p; + if (md->attr_list != NULL) + { + /* Add the underline indicating the accelerator */ + PangoAttribute *attr; + + attr = pango_attr_underline_new (PANGO_UNDERLINE_LOW); + + uline_index = md->index; + uline_len = g_utf8_next_char (p) - p; + + attr->start_index = uline_index; + attr->end_index = uline_index + uline_len; + + pango_attr_list_change (md->attr_list, attr); + } /* set next range_start to include this char */ range_start = p; @@ -693,35 +515,12 @@ text_handler (GMarkupParseContext *context G_GNUC_UNUSED, } p = g_utf8_next_char (p); - } - - if (range_end) - { - g_string_append_len (md->text, - range_start, - range_end - range_start); - md->index += range_end - range_start; - } - else - { - g_string_append_len (md->text, - range_start, - end - range_start); - md->index += end - range_start; - } - - if (md->attr_list != NULL && uline_index >= 0) - { - /* Add the underline indicating the accelerator */ - PangoAttribute *attr; - - attr = pango_attr_underline_new (PANGO_UNDERLINE_LOW); - - attr->start_index = uline_index; - attr->end_index = uline_index + uline_len; + } - pango_attr_list_change (md->attr_list, attr); - } + g_string_append_len (md->text, + range_start, + end - range_start); + md->index += end - range_start; } } @@ -800,17 +599,18 @@ pango_markup_parser_new_internal (char accel_marker, /** * pango_parse_markup: - * @markup_text: markup to parse (see <link linkend="PangoMarkupFormat">markup format</link>) + * @markup_text: markup to parse (see the Pango Markup docs) * @length: length of @markup_text, or -1 if nul-terminated * @accel_marker: character that precedes an accelerator, or 0 for none - * @attr_list: (out) (allow-none): address of return location for a #PangoAttrList, or %NULL + * @attr_list: (out) (allow-none): address of return location for a `PangoAttrList`, or %NULL * @text: (out) (allow-none): address of return location for text with tags stripped, or %NULL * @accel_char: (out) (allow-none): address of return location for accelerator char, or %NULL * @error: address of return location for errors, or %NULL * - * Parses marked-up text (see - * <link linkend="PangoMarkupFormat">markup format</link>) to create - * a plain-text string and an attribute list. + * Parses marked-up text to create a plain-text string and an attribute list. + * + * See the [Pango Markup](pango_markup.html) docs for details about the + * supported markup. * * If @accel_marker is nonzero, the given character will mark the * character following it as an accelerator. For example, @accel_marker @@ -820,7 +620,7 @@ pango_markup_parser_new_internal (char accel_marker, * Two @accel_marker characters following each other produce a single * literal @accel_marker character. * - * To parse a stream of pango markup incrementally, use pango_markup_parser_new(). + * To parse a stream of pango markup incrementally, use [func@markup_parser_new]. * * If any error happens, none of the output arguments are touched except * for @error. @@ -882,28 +682,30 @@ pango_parse_markup (const char *markup_text, * pango_markup_parser_new: * @accel_marker: character that precedes an accelerator, or 0 for none * - * Parses marked-up text (see - * <link linkend="PangoMarkupFormat">markup format</link>) to create - * a plain-text string and an attribute list. + * Incrementally parses marked-up text to create a plain-text string + * and an attribute list. + * + * See the [Pango Markup](pango_markup.html) docs for details about the + * supported markup. * * If @accel_marker is nonzero, the given character will mark the * character following it as an accelerator. For example, @accel_marker * might be an ampersand or underscore. All characters marked * as an accelerator will receive a %PANGO_UNDERLINE_LOW attribute, * and the first character so marked will be returned in @accel_char, - * when calling finish(). Two @accel_marker characters following each - * other produce a single literal @accel_marker character. + * when calling [func@markup_parser_finish]. Two @accel_marker characters + * following each other produce a single literal @accel_marker character. * * To feed markup to the parser, use g_markup_parse_context_parse() - * on the returned #GMarkupParseContext. When done with feeding markup - * to the parser, use pango_markup_parser_finish() to get the data out + * on the returned `GMarkupParseContext`. When done with feeding markup + * to the parser, use [func@markup_parser_finish] to get the data out * of it, and then use g_markup_parse_context_free() to free it. * - * This function is designed for applications that read pango markup - * from streams. To simply parse a string containing pango markup, - * the simpler pango_parse_markup() API is recommended instead. + * This function is designed for applications that read Pango markup + * from streams. To simply parse a string containing Pango markup, + * the [func@parse_markup] API is recommended instead. * - * Return value: (transfer none): a #GMarkupParseContext that should be + * Return value: (transfer none): a `GMarkupParseContext` that should be * destroyed with g_markup_parse_context_free(). * * Since: 1.31.0 @@ -923,14 +725,16 @@ pango_markup_parser_new (gunichar accel_marker) /** * pango_markup_parser_finish: - * @context: A valid parse context that was returned from pango_markup_parser_new() - * @attr_list: (out) (allow-none): address of return location for a #PangoAttrList, or %NULL + * @context: A valid parse context that was returned from [func@markup_parser_new] + * @attr_list: (out) (allow-none): address of return location for a `PangoAttrList`, or %NULL * @text: (out) (allow-none): address of return location for text with tags stripped, or %NULL * @accel_char: (out) (allow-none): address of return location for accelerator char, or %NULL * @error: address of return location for errors, or %NULL * - * After feeding a pango markup parser some data with g_markup_parse_context_parse(), - * use this function to get the list of pango attributes and text out of the + * Finishes parsing markup. + * + * After feeding a Pango markup parser some data with g_markup_parse_context_parse(), + * use this function to get the list of attributes and text out of the * markup. This function will not free @context, use g_markup_parse_context_free() * to do so. * diff --git a/pango/pango-matrix.c b/pango/pango-matrix.c index 50f8be1a..731c3a26 100644 --- a/pango/pango-matrix.c +++ b/pango/pango-matrix.c @@ -32,16 +32,16 @@ G_DEFINE_BOXED_TYPE (PangoMatrix, pango_matrix, /** * pango_matrix_copy: - * @matrix: (nullable): a #PangoMatrix, may be %NULL + * @matrix: (nullable): a `PangoMatrix`, may be %NULL * - * Copies a #PangoMatrix. + * Copies a `PangoMatrix`. * - * Return value: (nullable): the newly allocated #PangoMatrix, which - * should be freed with pango_matrix_free(), or %NULL if - * @matrix was %NULL. + * Return value: (nullable): the newly allocated `PangoMatrix`, which + * should be freed with [method@Pango.Matrix.free], or %NULL if + * @matrix was %NULL. * * Since: 1.6 - **/ + */ PangoMatrix * pango_matrix_copy (const PangoMatrix *matrix) { @@ -59,12 +59,12 @@ pango_matrix_copy (const PangoMatrix *matrix) /** * pango_matrix_free: - * @matrix: (nullable): a #PangoMatrix, may be %NULL + * @matrix: (nullable): a `PangoMatrix`, may be %NULL * - * Free a #PangoMatrix created with pango_matrix_copy(). + * Free a `PangoMatrix`. * * Since: 1.6 - **/ + */ void pango_matrix_free (PangoMatrix *matrix) { @@ -76,7 +76,7 @@ pango_matrix_free (PangoMatrix *matrix) /** * pango_matrix_translate: - * @matrix: a #PangoMatrix + * @matrix: a `PangoMatrix` * @tx: amount to translate in the X direction * @ty: amount to translate in the Y direction * @@ -85,7 +85,7 @@ pango_matrix_free (PangoMatrix *matrix) * then applying the original transformation. * * Since: 1.6 - **/ + */ void pango_matrix_translate (PangoMatrix *matrix, double tx, @@ -99,7 +99,7 @@ pango_matrix_translate (PangoMatrix *matrix, /** * pango_matrix_scale: - * @matrix: a #PangoMatrix + * @matrix: a `PangoMatrix` * @scale_x: amount to scale by in X direction * @scale_y: amount to scale by in Y direction * @@ -109,7 +109,7 @@ pango_matrix_translate (PangoMatrix *matrix, * transformation. * * Since: 1.6 - **/ + */ void pango_matrix_scale (PangoMatrix *matrix, double scale_x, @@ -125,7 +125,7 @@ pango_matrix_scale (PangoMatrix *matrix, /** * pango_matrix_rotate: - * @matrix: a #PangoMatrix + * @matrix: a `PangoMatrix` * @degrees: degrees to rotate counter-clockwise * * Changes the transformation represented by @matrix to be the @@ -133,7 +133,7 @@ pango_matrix_scale (PangoMatrix *matrix, * counter-clockwise then applying the original transformation. * * Since: 1.6 - **/ + */ void pango_matrix_rotate (PangoMatrix *matrix, double degrees) @@ -159,15 +159,15 @@ pango_matrix_rotate (PangoMatrix *matrix, /** * pango_matrix_concat: - * @matrix: a #PangoMatrix - * @new_matrix: a #PangoMatrix + * @matrix: a `PangoMatrix` + * @new_matrix: a `PangoMatrix` * * Changes the transformation represented by @matrix to be the * transformation given by first applying transformation * given by @new_matrix then applying the original transformation. * * Since: 1.6 - **/ + */ void pango_matrix_concat (PangoMatrix *matrix, const PangoMatrix *new_matrix) @@ -188,18 +188,19 @@ pango_matrix_concat (PangoMatrix *matrix, /** * pango_matrix_get_font_scale_factor: - * @matrix: (allow-none): a #PangoMatrix, may be %NULL + * @matrix: (allow-none): a `PangoMatrix`, may be %NULL * * Returns the scale factor of a matrix on the height of the font. + * * That is, the scale factor in the direction perpendicular to the * vector that the X coordinate is mapped to. If the scale in the X - * coordinate is needed as well, use pango_matrix_get_font_scale_factors(). + * coordinate is needed as well, use [method@Pango.Matrix.get_font_scale_factors]. * * Return value: the scale factor of @matrix on the height of the font, - * or 1.0 if @matrix is %NULL. + * or 1.0 if @matrix is %NULL. * * Since: 1.12 - **/ + */ double pango_matrix_get_font_scale_factor (const PangoMatrix *matrix) { @@ -210,11 +211,12 @@ pango_matrix_get_font_scale_factor (const PangoMatrix *matrix) /** * pango_matrix_get_font_scale_factors: - * @matrix: (nullable): a #PangoMatrix, or %NULL + * @matrix: (nullable): a `PangoMatrix`, or %NULL * @xscale: (out) (allow-none): output scale factor in the x direction, or %NULL * @yscale: (out) (allow-none): output scale factor perpendicular to the x direction, or %NULL * * Calculates the scale factor of a matrix on the width and height of the font. + * * That is, @xscale is the scale factor in the direction of the X coordinate, * and @yscale is the scale factor in the direction perpendicular to the * vector that the X coordinate is mapped to. @@ -264,19 +266,20 @@ pango_matrix_get_font_scale_factors (const PangoMatrix *matrix, /** * pango_matrix_transform_distance: - * @matrix: (nullable): a #PangoMatrix, or %NULL + * @matrix: (nullable): a `PangoMatrix`, or %NULL * @dx: (inout): in/out X component of a distance vector * @dy: (inout): in/out Y component of a distance vector * - * Transforms the distance vector (@dx,@dy) by @matrix. This is - * similar to pango_matrix_transform_point() except that the translation - * components of the transformation are ignored. The calculation of - * the returned vector is as follows: + * Transforms the distance vector (@dx,@dy) by @matrix. + * + * This is similar to [method@Pango.Matrix.transform_point], + * except that the translation components of the transformation + * are ignored. The calculation of the returned vector is as follows: * - * <programlisting> + * ``` * dx2 = dx1 * xx + dy1 * xy; * dy2 = dx1 * yx + dy1 * yy; - * </programlisting> + * ``` * * Affine transformations are position invariant, so the same vector * always transforms to the same vector. If (@x1,@y1) transforms @@ -284,7 +287,7 @@ pango_matrix_get_font_scale_factors (const PangoMatrix *matrix, * (@x1+@dx2,@y1+@dy2) for all values of @x1 and @x2. * * Since: 1.16 - **/ + */ void pango_matrix_transform_distance (const PangoMatrix *matrix, double *dx, @@ -304,7 +307,7 @@ pango_matrix_transform_distance (const PangoMatrix *matrix, /** * pango_matrix_transform_point: - * @matrix: (nullable): a #PangoMatrix, or %NULL + * @matrix: (nullable): a `PangoMatrix`, or %NULL * @x: (inout): in/out X position * @y: (inout): in/out Y position * @@ -328,18 +331,18 @@ pango_matrix_transform_point (const PangoMatrix *matrix, /** * pango_matrix_transform_rectangle: - * @matrix: (nullable): a #PangoMatrix, or %NULL + * @matrix: (nullable): a `PangoMatrix`, or %NULL * @rect: (inout) (allow-none): in/out bounding box in Pango units, or %NULL * * First transforms @rect using @matrix, then calculates the bounding box - * of the transformed rectangle. The rectangle should be in Pango units. + * of the transformed rectangle. * * This function is useful for example when you want to draw a rotated * @PangoLayout to an image buffer, and want to know how large the image * should be and how much you should shift the layout when rendering. * * If you have a rectangle in device units (pixels), use - * pango_matrix_transform_pixel_rectangle(). + * [method@Pango.Matrix.transform_pixel_rectangle]. * * If you have the rectangle in Pango units and want to convert to * transformed pixel bounding box, it is more accurate to transform it first @@ -351,7 +354,7 @@ pango_matrix_transform_point (const PangoMatrix *matrix, * example). * * Since: 1.16 - **/ + */ void pango_matrix_transform_rectangle (const PangoMatrix *matrix, PangoRectangle *rect) @@ -408,23 +411,22 @@ pango_matrix_transform_rectangle (const PangoMatrix *matrix, /** * pango_matrix_transform_pixel_rectangle: - * @matrix: (nullable): a #PangoMatrix, or %NULL + * @matrix: (nullable): a `PangoMatrix`, or %NULL * @rect: (inout) (allow-none): in/out bounding box in device units, or %NULL * * First transforms the @rect using @matrix, then calculates the bounding box - * of the transformed rectangle. The rectangle should be in device units - * (pixels). + * of the transformed rectangle. * * This function is useful for example when you want to draw a rotated * @PangoLayout to an image buffer, and want to know how large the image * should be and how much you should shift the layout when rendering. * - * For better accuracy, you should use pango_matrix_transform_rectangle() on - * original rectangle in Pango units and convert to pixels afterward - * using pango_extents_to_pixels()'s first argument. + * For better accuracy, you should use [method@Pango.Matrix.transform_rectangle] + * on original rectangle in Pango units and convert to pixels afterward + * using [func@extents_to_pixels]'s first argument. * * Since: 1.16 - **/ + */ void pango_matrix_transform_pixel_rectangle (const PangoMatrix *matrix, PangoRectangle *rect) diff --git a/pango/pango-matrix.h b/pango/pango-matrix.h index 9ec37042..c3ff5414 100644 --- a/pango/pango-matrix.h +++ b/pango/pango-matrix.h @@ -38,17 +38,18 @@ typedef struct _PangoMatrix PangoMatrix; * @x0: x translation * @y0: y translation * - * A structure specifying a transformation between user-space - * coordinates and device coordinates. The transformation - * is given by + * A `PangoMatrix` specifies a transformation between user-space + * and device coordinates. * - * <programlisting> + * The transformation is given by + * + * ``` * x_device = x_user * matrix->xx + y_user * matrix->xy + matrix->x0; * y_device = x_user * matrix->yx + y_user * matrix->yy + matrix->y0; - * </programlisting> + * ``` * * Since: 1.6 - **/ + */ struct _PangoMatrix { double xx; @@ -72,10 +73,10 @@ struct _PangoMatrix * Constant that can be used to initialize a PangoMatrix to * the identity transform. * - * <informalexample><programlisting> + * ``` * PangoMatrix matrix = PANGO_MATRIX_INIT; - * pango_matrix_rotate (&matrix, 45.); - * </programlisting></informalexample> + * pango_matrix_rotate (&matrix, 45.); + * ``` * * Since: 1.6 **/ diff --git a/pango/pango-modules.h b/pango/pango-modules.h index 64900a17..54b347a2 100644 --- a/pango/pango-modules.h +++ b/pango/pango-modules.h @@ -26,6 +26,11 @@ G_BEGIN_DECLS +/* All of this is deprecated and entirely useless for bindings. + * Leave it out of the gir file. + */ +#ifndef __GI_SCANNER__ + #ifndef PANGO_DISABLE_DEPRECATED typedef struct _PangoMap PangoMap; @@ -72,6 +77,8 @@ void pango_module_register (PangoIncludedModule *module); #endif /* PANGO_DISABLE_DEPRECATED */ +#endif /* __GI_SCANNER__ */ + G_END_DECLS #endif /* __PANGO_MODULES_H__ */ diff --git a/pango/pango-ot-info.c b/pango/pango-ot-info.c index 2b1b61f4..891ae323 100644 --- a/pango/pango-ot-info.c +++ b/pango/pango-ot-info.c @@ -19,18 +19,6 @@ * Boston, MA 02111-1307, USA. */ -/** - * SECTION:opentype - * @short_description:Obtaining information from OpenType tables - * @title:OpenType Font Handling - * @stability:Unstable - * - * Functions and macros in this section are used to implement - * the OpenType Layout features and algorithms. - * - * They have been superseded by the harfbuzz library, and should - * not be used anymore. - */ #include "config.h" #include "pango-ot-private.h" @@ -76,7 +64,7 @@ pango_ot_info_finalizer (void *object) /** * pango_ot_info_get: - * @face: a <type>FT_Face</type>. + * @face: a FT_Face * * Returns the #PangoOTInfo structure for the given FreeType font face. * diff --git a/pango/pango-ot-private.h b/pango/pango-ot-private.h index d9d86644..7ba44c6a 100644 --- a/pango/pango-ot-private.h +++ b/pango/pango-ot-private.h @@ -40,7 +40,7 @@ typedef struct _PangoOTInfoClass PangoOTInfoClass; * * The #PangoOTInfo struct contains the various * tables associated with an OpenType font. It contains only private fields and - * should only be accessed via the <function>pango_ot_info_*</function> functions + * should only be accessed via the pango_ot_info_… functions * which are documented below. To obtain a #PangoOTInfo, * use pango_ot_info_get(). */ @@ -76,7 +76,7 @@ struct _PangoOTRulesetClass * The #PangoOTBuffer structure is used to store strings of glyphs associated * with a #PangoFcFont, suitable for OpenType layout processing. It contains * only private fields and should only be accessed via the - * <function>pango_ot_buffer_*</function> functions which are documented below. + * pango_ot_buffer_… functions which are documented below. * To obtain a #PangoOTBuffer, use pango_ot_buffer_new(). */ struct _PangoOTBuffer diff --git a/pango/pango-ot-ruleset.c b/pango/pango-ot-ruleset.c index 9df8faef..9cf4cfb0 100644 --- a/pango/pango-ot-ruleset.c +++ b/pango/pango-ot-ruleset.c @@ -120,29 +120,23 @@ pango_ot_ruleset_new (PangoOTInfo *info) * script, language, or feature indices manually. * * In excess to what pango_ot_ruleset_new() does, this function will: - * <itemizedlist> - * <listitem> - * Find the #PangoOTTag script and language tags associated with + * + * * Find the #PangoOTTag script and language tags associated with * @script and @language using pango_ot_tag_from_script() and * pango_ot_tag_from_language(), - * </listitem> - * <listitem> - * For each of table types %PANGO_OT_TABLE_GSUB and %PANGO_OT_TABLE_GPOS, + * + * * For each of table types %PANGO_OT_TABLE_GSUB and %PANGO_OT_TABLE_GPOS, * find the script index of the script tag found and the language * system index of the language tag found in that script system, using * pango_ot_info_find_script() and pango_ot_info_find_language(), - * </listitem> - * <listitem> - * For found language-systems, if they have required feature + * + * * For found language-systems, if they have required feature * index, add that feature to the ruleset using * pango_ot_ruleset_add_feature(), - * </listitem> - * <listitem> - * Remember found script and language indices for both table types, + * + * * Remember found script and language indices for both table types, * and use them in future pango_ot_ruleset_maybe_add_feature() and * pango_ot_ruleset_maybe_add_features(). - * </listitem> - * </itemizedlist> * * Because of the way return values of pango_ot_info_find_script() and * pango_ot_info_find_language() are ignored, this function automatically diff --git a/pango/pango-ot.h b/pango/pango-ot.h index b8c6acc8..6390538b 100644 --- a/pango/pango-ot.h +++ b/pango/pango-ot.h @@ -42,7 +42,7 @@ G_BEGIN_DECLS * * The #PangoOTTag typedef is used to represent TrueType and OpenType * four letter tags inside Pango. Use PANGO_OT_TAG_MAKE() - * or PANGO_OT_TAG_MAKE_FROM_STRING() macros to create <type>PangoOTTag</type>s manually. + * or PANGO_OT_TAG_MAKE_FROM_STRING() macros to create PangoOTTags manually. */ typedef guint32 PangoOTTag; @@ -54,7 +54,7 @@ typedef guint32 PangoOTTag; * @c4: Fourth character. * * Creates a #PangoOTTag from four characters. This is similar and - * compatible with the <function>FT_MAKE_TAG()</function> macro from FreeType. + * compatible with the FT_MAKE_TAG() macro from FreeType. */ /** * PANGO_OT_TAG_MAKE_FROM_STRING: @@ -84,9 +84,9 @@ typedef struct _PangoOTRulesetDescription PangoOTRulesetDescription; * @PANGO_OT_TABLE_GSUB: The GSUB table. * @PANGO_OT_TABLE_GPOS: The GPOS table. * - * The <type>PangoOTTableType</type> enumeration values are used to + * The PangoOTTableType enumeration values are used to * identify the various OpenType tables in the - * <function>pango_ot_info_*</function> functions. + * pango_ot_info_… functions. */ typedef enum { diff --git a/pango/pango-renderer.c b/pango/pango-renderer.c index 432875a4..2d676782 100644 --- a/pango/pango-renderer.c +++ b/pango/pango-renderer.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 @@ -67,37 +67,37 @@ struct _PangoRendererPrivate static void pango_renderer_finalize (GObject *gobject); static void pango_renderer_default_draw_glyphs (PangoRenderer *renderer, - PangoFont *font, - PangoGlyphString *glyphs, - int x, - int y); + PangoFont *font, + PangoGlyphString *glyphs, + int x, + int y); static void pango_renderer_default_draw_glyph_item (PangoRenderer *renderer, - const char *text, - PangoGlyphItem *glyph_item, - int x, - int y); + const char *text, + PangoGlyphItem *glyph_item, + int x, + int y); static void pango_renderer_default_draw_rectangle (PangoRenderer *renderer, - PangoRenderPart part, - int x, - int y, - int width, - int height); + PangoRenderPart part, + int x, + int y, + int width, + int height); static void pango_renderer_default_draw_error_underline (PangoRenderer *renderer, - int x, - int y, - int width, - int height); + int x, + int y, + int width, + int height); static void pango_renderer_default_prepare_run (PangoRenderer *renderer, - PangoLayoutRun *run); + PangoLayoutRun *run); static void pango_renderer_prepare_run (PangoRenderer *renderer, - PangoLayoutRun *run); + PangoLayoutRun *run); static void to_device (PangoMatrix *matrix, - double x, - double y, - Point *result) + double x, + double y, + Point *result) { if (matrix) { @@ -148,22 +148,22 @@ pango_renderer_finalize (GObject *gobject) /** * pango_renderer_draw_layout: - * @renderer: a #PangoRenderer - * @layout: a #PangoLayout + * @renderer: a `PangoRenderer` + * @layout: a `PangoLayout` * @x: X position of left edge of baseline, in user space coordinates * in Pango units. * @y: Y position of left edge of baseline, in user space coordinates * in Pango units. * - * Draws @layout with the specified #PangoRenderer. + * Draws @layout with the specified `PangoRenderer`. * * Since: 1.8 - **/ + */ void -pango_renderer_draw_layout (PangoRenderer *renderer, - PangoLayout *layout, - int x, - int y) +pango_renderer_draw_layout (PangoRenderer *renderer, + PangoLayout *layout, + int x, + int y) { PangoLayoutIter iter; @@ -177,7 +177,7 @@ pango_renderer_draw_layout (PangoRenderer *renderer, { PangoContext *context = pango_layout_get_context (layout); pango_renderer_set_matrix (renderer, - pango_context_get_matrix (context)); + pango_context_get_matrix (context)); } pango_renderer_activate (renderer); @@ -196,9 +196,9 @@ pango_renderer_draw_layout (PangoRenderer *renderer, baseline = pango_layout_iter_get_baseline (&iter); pango_renderer_draw_layout_line (renderer, - line, - x + logical_rect.x, - y + baseline); + line, + x + logical_rect.x, + y + baseline); } while (pango_layout_iter_next_line (&iter)); @@ -209,7 +209,7 @@ pango_renderer_draw_layout (PangoRenderer *renderer, static void draw_underline (PangoRenderer *renderer, - LineState *state) + LineState *state) { PangoRectangle *rect = &state->underline_rect; PangoUnderline underline = state->underline; @@ -223,29 +223,29 @@ draw_underline (PangoRenderer *renderer, case PANGO_UNDERLINE_DOUBLE: case PANGO_UNDERLINE_DOUBLE_LINE: pango_renderer_draw_rectangle (renderer, - PANGO_RENDER_PART_UNDERLINE, - rect->x, - rect->y + 2 * rect->height, - rect->width, - rect->height); + PANGO_RENDER_PART_UNDERLINE, + rect->x, + rect->y + 2 * rect->height, + rect->width, + rect->height); G_GNUC_FALLTHROUGH; case PANGO_UNDERLINE_SINGLE: case PANGO_UNDERLINE_LOW: case PANGO_UNDERLINE_SINGLE_LINE: pango_renderer_draw_rectangle (renderer, - PANGO_RENDER_PART_UNDERLINE, - rect->x, - rect->y, - rect->width, - rect->height); + PANGO_RENDER_PART_UNDERLINE, + rect->x, + rect->y, + rect->width, + rect->height); break; case PANGO_UNDERLINE_ERROR: case PANGO_UNDERLINE_ERROR_LINE: pango_renderer_draw_error_underline (renderer, - rect->x, - rect->y, - rect->width, - 3 * rect->height); + rect->x, + rect->y, + rect->width, + 3 * rect->height); break; } } @@ -265,18 +265,18 @@ draw_overline (PangoRenderer *renderer, break; case PANGO_OVERLINE_SINGLE: pango_renderer_draw_rectangle (renderer, - PANGO_RENDER_PART_OVERLINE, - rect->x, - rect->y, - rect->width, - rect->height); + PANGO_RENDER_PART_OVERLINE, + rect->x, + rect->y, + rect->width, + rect->height); break; } } static void draw_strikethrough (PangoRenderer *renderer, - LineState *state) + LineState *state) { PangoRectangle *rect = &state->strikethrough_rect; gboolean strikethrough = state->strikethrough; @@ -295,7 +295,7 @@ draw_strikethrough (PangoRenderer *renderer, static void handle_line_state_change (PangoRenderer *renderer, - PangoRenderPart part) + PangoRenderPart part) { LineState *state = renderer->priv->line_state; if (!state) @@ -340,12 +340,12 @@ handle_line_state_change (PangoRenderer *renderer, static void add_underline (PangoRenderer *renderer, - LineState *state, - PangoFontMetrics *metrics, - int base_x, - int base_y, - PangoRectangle *ink_rect, - PangoRectangle *logical_rect) + LineState *state, + PangoFontMetrics *metrics, + int base_x, + int base_y, + PangoRectangle *ink_rect, + PangoRectangle *logical_rect) { PangoRectangle *current_rect = &state->underline_rect; PangoRectangle new_rect; @@ -453,12 +453,12 @@ add_overline (PangoRenderer *renderer, static void add_strikethrough (PangoRenderer *renderer, - LineState *state, - PangoFontMetrics *metrics, - int base_x, - int base_y, - PangoRectangle *ink_rect G_GNUC_UNUSED, - PangoRectangle *logical_rect, + LineState *state, + PangoFontMetrics *metrics, + int base_x, + int base_y, + PangoRectangle *ink_rect G_GNUC_UNUSED, + PangoRectangle *logical_rect, int num_glyphs) { PangoRectangle *current_rect = &state->strikethrough_rect; @@ -490,8 +490,8 @@ add_strikethrough (PangoRenderer *renderer, static void get_item_properties (PangoItem *item, - gint *rise, - PangoAttrShape **shape_attr) + gint *rise, + PangoAttrShape **shape_attr) { GSList *l; @@ -506,29 +506,29 @@ get_item_properties (PangoItem *item, PangoAttribute *attr = l->data; switch ((int) attr->klass->type) - { - case PANGO_ATTR_SHAPE: - if (shape_attr) - *shape_attr = (PangoAttrShape *)attr; - break; - - case PANGO_ATTR_RISE: - if (rise) - *rise = ((PangoAttrInt *)attr)->value; - break; - - default: - break; - } + { + case PANGO_ATTR_SHAPE: + if (shape_attr) + *shape_attr = (PangoAttrShape *)attr; + break; + + case PANGO_ATTR_RISE: + if (rise) + *rise = ((PangoAttrInt *)attr)->value; + break; + + default: + break; + } } } static void draw_shaped_glyphs (PangoRenderer *renderer, - PangoGlyphString *glyphs, - PangoAttrShape *attr, - int x, - int y) + PangoGlyphString *glyphs, + PangoAttrShape *attr, + int x, + int y) { PangoRendererClass *class = PANGO_RENDERER_GET_CLASS (renderer); int i; @@ -549,22 +549,22 @@ draw_shaped_glyphs (PangoRenderer *renderer, /** * pango_renderer_draw_layout_line: - * @renderer: a #PangoRenderer - * @line: a #PangoLayoutLine + * @renderer: a `PangoRenderer` + * @line: a `PangoLayoutLine` * @x: X position of left edge of baseline, in user space coordinates * in Pango units. * @y: Y position of left edge of baseline, in user space coordinates * in Pango units. * - * Draws @line with the specified #PangoRenderer. + * Draws @line with the specified `PangoRenderer`. * * Since: 1.8 - **/ + */ void -pango_renderer_draw_layout_line (PangoRenderer *renderer, - PangoLayoutLine *line, - int x, - int y) +pango_renderer_draw_layout_line (PangoRenderer *renderer, + PangoLayoutLine *line, + int x, + int y) { int x_off = 0; int glyph_string_width; @@ -581,10 +581,10 @@ pango_renderer_draw_layout_line (PangoRenderer *renderer, */ if (!renderer->active_count) pango_renderer_set_matrix (renderer, - G_LIKELY (line->layout) ? - pango_context_get_matrix - (pango_layout_get_context (line->layout)) : - NULL); + G_LIKELY (line->layout) ? + pango_context_get_matrix + (pango_layout_get_context (line->layout)) : + NULL); pango_renderer_activate (renderer); @@ -607,118 +607,118 @@ pango_renderer_draw_layout_line (PangoRenderer *renderer, PangoRectangle logical_rect, *logical = NULL; if (run->item->analysis.flags & PANGO_ANALYSIS_FLAG_CENTERED_BASELINE) - logical = &logical_rect; + logical = &logical_rect; pango_renderer_prepare_run (renderer, run); get_item_properties (run->item, &rise, &shape_attr); if (shape_attr) - { - ink = &ink_rect; - logical = &logical_rect; + { + ink = &ink_rect; + logical = &logical_rect; _pango_shape_get_extents (run->glyphs->num_glyphs, - &shape_attr->ink_rect, - &shape_attr->logical_rect, - ink, - logical); - glyph_string_width = logical->width; - } + &shape_attr->ink_rect, + &shape_attr->logical_rect, + ink, + logical); + glyph_string_width = logical->width; + } else - { - if (renderer->underline != PANGO_UNDERLINE_NONE || + { + if (renderer->underline != PANGO_UNDERLINE_NONE || renderer->priv->overline != PANGO_OVERLINE_NONE || - renderer->strikethrough) - { - ink = &ink_rect; - logical = &logical_rect; - } - if (G_UNLIKELY (ink || logical)) - pango_glyph_string_extents (run->glyphs, run->item->analysis.font, - ink, logical); - if (logical) - glyph_string_width = logical_rect.width; - else - glyph_string_width = pango_glyph_string_get_width (run->glyphs); - } + renderer->strikethrough) + { + ink = &ink_rect; + logical = &logical_rect; + } + if (G_UNLIKELY (ink || logical)) + pango_glyph_string_extents (run->glyphs, run->item->analysis.font, + ink, logical); + if (logical) + glyph_string_width = logical_rect.width; + else + glyph_string_width = pango_glyph_string_get_width (run->glyphs); + } state.logical_rect_end = x + x_off + glyph_string_width; if (run->item->analysis.flags & PANGO_ANALYSIS_FLAG_CENTERED_BASELINE) - { - gboolean is_hinted = ((logical_rect.y | logical_rect.height) & (PANGO_SCALE - 1)) == 0; - int adjustment = logical_rect.y + logical_rect.height / 2; + { + gboolean is_hinted = ((logical_rect.y | logical_rect.height) & (PANGO_SCALE - 1)) == 0; + int adjustment = logical_rect.y + logical_rect.height / 2; - if (is_hinted) - adjustment = PANGO_UNITS_ROUND (adjustment); + if (is_hinted) + adjustment = PANGO_UNITS_ROUND (adjustment); - rise += adjustment; - } + rise += adjustment; + } if (renderer->priv->color_set[PANGO_RENDER_PART_BACKGROUND]) - { - if (!got_overall) - { - pango_layout_line_get_extents (line, NULL, &overall_rect); - got_overall = TRUE; - } - - pango_renderer_draw_rectangle (renderer, - PANGO_RENDER_PART_BACKGROUND, - x + x_off, - y + overall_rect.y, - glyph_string_width, - overall_rect.height); - } + { + if (!got_overall) + { + pango_layout_line_get_extents (line, NULL, &overall_rect); + got_overall = TRUE; + } + + pango_renderer_draw_rectangle (renderer, + PANGO_RENDER_PART_BACKGROUND, + x + x_off, + y + overall_rect.y, + glyph_string_width, + overall_rect.height); + } if (shape_attr) - { - draw_shaped_glyphs (renderer, run->glyphs, shape_attr, x + x_off, y - rise); - } + { + draw_shaped_glyphs (renderer, run->glyphs, shape_attr, x + x_off, y - rise); + } else - { - pango_renderer_draw_glyph_item (renderer, - text, - run, - x + x_off, y - rise); - } + { + pango_renderer_draw_glyph_item (renderer, + text, + run, + x + x_off, y - rise); + } if (renderer->underline != PANGO_UNDERLINE_NONE || renderer->priv->overline != PANGO_OVERLINE_NONE || - renderer->strikethrough) - { - metrics = pango_font_get_metrics (run->item->analysis.font, - run->item->analysis.language); + renderer->strikethrough) + { + metrics = pango_font_get_metrics (run->item->analysis.font, + run->item->analysis.language); - if (renderer->underline != PANGO_UNDERLINE_NONE) - add_underline (renderer, &state,metrics, - x + x_off, y - rise, - ink, logical); + if (renderer->underline != PANGO_UNDERLINE_NONE) + add_underline (renderer, &state,metrics, + x + x_off, y - rise, + ink, logical); - if (renderer->priv->overline != PANGO_OVERLINE_NONE) - add_overline (renderer, &state,metrics, - x + x_off, y - rise, - ink, logical); + if (renderer->priv->overline != PANGO_OVERLINE_NONE) + add_overline (renderer, &state,metrics, + x + x_off, y - rise, + ink, logical); - if (renderer->strikethrough) - add_strikethrough (renderer, &state, metrics, - x + x_off, y - rise, - ink, logical, run->glyphs->num_glyphs); + if (renderer->strikethrough) + add_strikethrough (renderer, &state, metrics, + x + x_off, y - rise, + ink, logical, run->glyphs->num_glyphs); - pango_font_metrics_unref (metrics); - } + pango_font_metrics_unref (metrics); + } if (renderer->underline == PANGO_UNDERLINE_NONE && - state.underline != PANGO_UNDERLINE_NONE) - draw_underline (renderer, &state); + state.underline != PANGO_UNDERLINE_NONE) + draw_underline (renderer, &state); if (renderer->priv->overline == PANGO_OVERLINE_NONE && - state.overline != PANGO_OVERLINE_NONE) - draw_overline (renderer, &state); + state.overline != PANGO_OVERLINE_NONE) + draw_overline (renderer, &state); if (!renderer->strikethrough && state.strikethrough) - draw_strikethrough (renderer, &state); + draw_strikethrough (renderer, &state); x_off += glyph_string_width; } @@ -737,24 +737,24 @@ pango_renderer_draw_layout_line (PangoRenderer *renderer, /** * pango_renderer_draw_glyphs: - * @renderer: a #PangoRenderer - * @font: a #PangoFont - * @glyphs: a #PangoGlyphString + * @renderer: a `PangoRenderer` + * @font: a `PangoFont` + * @glyphs: a `PangoGlyphString` * @x: X position of left edge of baseline, in user space coordinates * in Pango units. * @y: Y position of left edge of baseline, in user space coordinates * in Pango units. * - * Draws the glyphs in @glyphs with the specified #PangoRenderer. + * Draws the glyphs in @glyphs with the specified `PangoRenderer`. * * Since: 1.8 - **/ + */ void pango_renderer_draw_glyphs (PangoRenderer *renderer, - PangoFont *font, - PangoGlyphString *glyphs, - int x, - int y) + PangoFont *font, + PangoGlyphString *glyphs, + int x, + int y) { g_return_if_fail (PANGO_IS_RENDERER_FAST (renderer)); @@ -767,10 +767,10 @@ pango_renderer_draw_glyphs (PangoRenderer *renderer, static void pango_renderer_default_draw_glyphs (PangoRenderer *renderer, - PangoFont *font, - PangoGlyphString *glyphs, - int x, - int y) + PangoFont *font, + PangoGlyphString *glyphs, + int x, + int y) { int i; int x_position = 0; @@ -781,9 +781,9 @@ pango_renderer_default_draw_glyphs (PangoRenderer *renderer, Point p; to_device (renderer->matrix, - x + x_position + gi->geometry.x_offset, - y + gi->geometry.y_offset, - &p); + x + x_position + gi->geometry.x_offset, + y + gi->geometry.y_offset, + &p); pango_renderer_draw_glyph (renderer, font, gi->glyph, p.x, p.y); @@ -793,41 +793,43 @@ pango_renderer_default_draw_glyphs (PangoRenderer *renderer, /** * pango_renderer_draw_glyph_item: - * @renderer: a #PangoRenderer + * @renderer: a `PangoRenderer` * @text: (allow-none): the UTF-8 text that @glyph_item refers to, or %NULL - * @glyph_item: a #PangoGlyphItem + * @glyph_item: a `PangoGlyphItem` * @x: X position of left edge of baseline, in user space coordinates * in Pango units. * @y: Y position of left edge of baseline, in user space coordinates * in Pango units. * - * Draws the glyphs in @glyph_item with the specified #PangoRenderer, + * Draws the glyphs in @glyph_item with the specified `PangoRenderer`, * embedding the text associated with the glyphs in the output if the - * output format supports it (PDF for example). + * output format supports it. + * + * This is useful for rendering text in PDF. * * Note that @text is the start of the text for layout, which is then - * indexed by <literal>@glyph_item->item->offset</literal>. + * indexed by `glyph_item->item->offset`. * - * If @text is %NULL, this simply calls pango_renderer_draw_glyphs(). + * If @text is %NULL, this simply calls [method@Pango.Renderer.draw_glyphs]. * * The default implementation of this method simply falls back to - * pango_renderer_draw_glyphs(). + * [method@Pango.Renderer.draw_glyphs]. * * Since: 1.22 - **/ + */ void -pango_renderer_draw_glyph_item (PangoRenderer *renderer, - const char *text, - PangoGlyphItem *glyph_item, - int x, - int y) +pango_renderer_draw_glyph_item (PangoRenderer *renderer, + const char *text, + PangoGlyphItem *glyph_item, + int x, + int y) { if (!text) { pango_renderer_draw_glyphs (renderer, - glyph_item->item->analysis.font, - glyph_item->glyphs, - x, y); + glyph_item->item->analysis.font, + glyph_item->glyphs, + x, y); return; } @@ -841,42 +843,44 @@ pango_renderer_draw_glyph_item (PangoRenderer *renderer, } static void -pango_renderer_default_draw_glyph_item (PangoRenderer *renderer, - const char *text G_GNUC_UNUSED, - PangoGlyphItem *glyph_item, - int x, - int y) +pango_renderer_default_draw_glyph_item (PangoRenderer *renderer, + const char *text G_GNUC_UNUSED, + PangoGlyphItem *glyph_item, + int x, + int y) { pango_renderer_draw_glyphs (renderer, - glyph_item->item->analysis.font, - glyph_item->glyphs, - x, y); + glyph_item->item->analysis.font, + glyph_item->glyphs, + x, y); } /** * pango_renderer_draw_rectangle: - * @renderer: a #PangoRenderer + * @renderer: a `PangoRenderer` * @part: type of object this rectangle is part of - * @x: X position at which to draw rectangle, in user space coordinates in Pango units - * @y: Y position at which to draw rectangle, in user space coordinates in Pango units - * @width: width of rectangle in Pango units in user space coordinates - * @height: height of rectangle in Pango units in user space coordinates + * @x: X position at which to draw rectangle, in user space coordinates + * in Pango units + * @y: Y position at which to draw rectangle, in user space coordinates + * in Pango units + * @width: width of rectangle in Pango units + * @height: height of rectangle in Pango units * * Draws an axis-aligned rectangle in user space coordinates with the - * specified #PangoRenderer. + * specified `PangoRenderer`. * - * This should be called while @renderer is already active. Use - * pango_renderer_activate() to activate a renderer. + * This should be called while @renderer is already active. + * Use [method@Pango.Renderer.activate] to activate a renderer. * * Since: 1.8 - **/ + */ void pango_renderer_draw_rectangle (PangoRenderer *renderer, - PangoRenderPart part, - int x, - int y, - int width, - int height) + PangoRenderPart part, + int x, + int y, + int width, + int height) { g_return_if_fail (PANGO_IS_RENDERER_FAST (renderer)); g_return_if_fail (IS_VALID_PART (part)); @@ -887,7 +891,7 @@ pango_renderer_draw_rectangle (PangoRenderer *renderer, static int compare_points (const void *a, - const void *b) + const void *b) { const Point *pa = a; const Point *pb = b; @@ -906,12 +910,12 @@ compare_points (const void *a, static void draw_rectangle (PangoRenderer *renderer, - PangoMatrix *matrix, - PangoRenderPart part, - int x, - int y, - int width, - int height) + PangoMatrix *matrix, + PangoRenderPart part, + int x, + int y, + int width, + int height) { Point points[4]; @@ -944,8 +948,8 @@ draw_rectangle (PangoRenderer *renderer, { /* Case 1 (pure shear) */ pango_renderer_draw_trapezoid (renderer, part, /* B */ - points[0].y, points[0].x, points[1].x, - points[2].y, points[2].x, points[3].x); + points[0].y, points[0].x, points[1].x, + points[2].y, points[2].x, points[3].x); } else if (points[1].x < points[2].x) { @@ -954,14 +958,14 @@ draw_rectangle (PangoRenderer *renderer, double base_width = tmp_width + points[0].x - points[1].x; pango_renderer_draw_trapezoid (renderer, part, /* A */ - points[0].y, points[0].x, points[0].x, - points[1].y, points[1].x, points[1].x + base_width); + points[0].y, points[0].x, points[0].x, + points[1].y, points[1].x, points[1].x + base_width); pango_renderer_draw_trapezoid (renderer, part, /* B */ - points[1].y, points[1].x, points[1].x + base_width, - points[2].y, points[2].x - base_width, points[2].x); + points[1].y, points[1].x, points[1].x + base_width, + points[2].y, points[2].x - base_width, points[2].x); pango_renderer_draw_trapezoid (renderer, part, /* C */ - points[2].y, points[2].x - base_width, points[2].x, - points[3].y, points[3].x, points[3].x); + points[2].y, points[2].x - base_width, points[2].x, + points[3].y, points[3].x, points[3].x); } else { @@ -970,31 +974,31 @@ draw_rectangle (PangoRenderer *renderer, double base_width = tmp_width + points[1].x - points[0].x; pango_renderer_draw_trapezoid (renderer, part, /* A */ - points[0].y, points[0].x, points[0].x, - points[1].y, points[1].x - base_width, points[1].x); + points[0].y, points[0].x, points[0].x, + points[1].y, points[1].x - base_width, points[1].x); pango_renderer_draw_trapezoid (renderer, part, /* B */ - points[1].y, points[1].x - base_width, points[1].x, - points[2].y, points[2].x, points[2].x + base_width); + points[1].y, points[1].x - base_width, points[1].x, + points[2].y, points[2].x, points[2].x + base_width); pango_renderer_draw_trapezoid (renderer, part, /* C */ - points[2].y, points[2].x, points[2].x + base_width, - points[3].y, points[3].x, points[3].x); + points[2].y, points[2].x, points[2].x + base_width, + points[3].y, points[3].x, points[3].x); } } static void pango_renderer_default_draw_rectangle (PangoRenderer *renderer, - PangoRenderPart part, - int x, - int y, - int width, - int height) + PangoRenderPart part, + int x, + int y, + int width, + int height) { draw_rectangle (renderer, renderer->matrix, part, x, y, width, height); } /** * pango_renderer_draw_error_underline: - * @renderer: a #PangoRenderer + * @renderer: a `PangoRenderer` * @x: X coordinate of underline, in Pango units in user coordinate system * @y: Y coordinate of underline, in Pango units in user coordinate system * @width: width of underline, in Pango units in user coordinate system @@ -1002,21 +1006,22 @@ pango_renderer_default_draw_rectangle (PangoRenderer *renderer, * * Draw a squiggly line that approximately covers the given rectangle * in the style of an underline used to indicate a spelling error. - * (The width of the underline is rounded to an integer number + * + * The width of the underline is rounded to an integer number * of up/down segments and the resulting rectangle is centered - * in the original rectangle) + * in the original rectangle. * - * This should be called while @renderer is already active. Use - * pango_renderer_activate() to activate a renderer. + * This should be called while @renderer is already active. + * Use [method@Pango.Renderer.activate] to activate a renderer. * * Since: 1.8 - **/ + */ void pango_renderer_draw_error_underline (PangoRenderer *renderer, - int x, - int y, - int width, - int height) + int x, + int y, + int width, + int height) { g_return_if_fail (PANGO_IS_RENDERER_FAST (renderer)); g_return_if_fail (renderer->active_count > 0); @@ -1065,10 +1070,10 @@ pango_renderer_draw_error_underline (PangoRenderer *renderer, static void get_total_matrix (PangoMatrix *total, - const PangoMatrix *global, - int x, - int y, - int square) + const PangoMatrix *global, + int x, + int y, + int square) { PangoMatrix local; gdouble scale = 0.5 * square; @@ -1092,10 +1097,10 @@ get_total_matrix (PangoMatrix *total, static void pango_renderer_default_draw_error_underline (PangoRenderer *renderer, - int x, - int y, - int width, - int height) + int x, + int y, + int width, + int height) { int square; int unit_width; @@ -1129,16 +1134,16 @@ pango_renderer_default_draw_error_underline (PangoRenderer *renderer, while (TRUE) { draw_rectangle (renderer, &total, PANGO_RENDER_PART_UNDERLINE, /* A */ - 0, 0, - HEIGHT_SQUARES * 2 - 1, 1); + 0, 0, + HEIGHT_SQUARES * 2 - 1, 1); if (i <= 0) break; i--; draw_rectangle (renderer, &total, PANGO_RENDER_PART_UNDERLINE, /* B */ - HEIGHT_SQUARES * 2 - 2, - (HEIGHT_SQUARES * 2 - 3), - 1, HEIGHT_SQUARES * 2 - 3); + HEIGHT_SQUARES * 2 - 2, - (HEIGHT_SQUARES * 2 - 3), + 1, HEIGHT_SQUARES * 2 - 3); total.x0 += dx0; total.y0 += dy0; @@ -1146,14 +1151,14 @@ pango_renderer_default_draw_error_underline (PangoRenderer *renderer, if (width_units % 2 == 0) { draw_rectangle (renderer, &total, PANGO_RENDER_PART_UNDERLINE, /* C */ - HEIGHT_SQUARES * 2 - 2, - (HEIGHT_SQUARES * 2 - 2), - 1, HEIGHT_SQUARES * 2 - 2); + HEIGHT_SQUARES * 2 - 2, - (HEIGHT_SQUARES * 2 - 2), + 1, HEIGHT_SQUARES * 2 - 2); } } /** * pango_renderer_draw_trapezoid: - * @renderer: a #PangoRenderer + * @renderer: a `PangoRenderer` * @part: type of object this trapezoid is part of * @y1_: Y coordinate of top of trapezoid * @x11: X coordinate of left end of top of trapezoid @@ -1163,32 +1168,32 @@ pango_renderer_default_draw_error_underline (PangoRenderer *renderer, * @x22: X coordinate of right end of bottom of trapezoid * * Draws a trapezoid with the parallel sides aligned with the X axis - * using the given #PangoRenderer; coordinates are in device space. + * using the given `PangoRenderer`; coordinates are in device space. * * Since: 1.8 - **/ + */ void -pango_renderer_draw_trapezoid (PangoRenderer *renderer, - PangoRenderPart part, - double y1_, - double x11, - double x21, - double y2, - double x12, - double x22) +pango_renderer_draw_trapezoid (PangoRenderer *renderer, + PangoRenderPart part, + double y1_, + double x11, + double x21, + double y2, + double x12, + double x22) { g_return_if_fail (PANGO_IS_RENDERER_FAST (renderer)); g_return_if_fail (renderer->active_count > 0); if (PANGO_RENDERER_GET_CLASS (renderer)->draw_trapezoid) PANGO_RENDERER_GET_CLASS (renderer)->draw_trapezoid (renderer, part, - y1_, x11, x21, - y2, x12, x22); + y1_, x11, x21, + y2, x12, x22); } /** * pango_renderer_draw_glyph: - * @renderer: a #PangoRenderer + * @renderer: a `PangoRenderer` * @font: a #PangoFont * @glyph: the glyph index of a single glyph * @x: X coordinate of left edge of baseline of glyph @@ -1197,13 +1202,13 @@ pango_renderer_draw_trapezoid (PangoRenderer *renderer, * Draws a single glyph with coordinates in device space. * * Since: 1.8 - **/ + */ void pango_renderer_draw_glyph (PangoRenderer *renderer, - PangoFont *font, - PangoGlyph glyph, - double x, - double y) + PangoFont *font, + PangoGlyph glyph, + double x, + double y) { g_return_if_fail (PANGO_IS_RENDERER_FAST (renderer)); g_return_if_fail (renderer->active_count > 0); @@ -1217,14 +1222,15 @@ pango_renderer_draw_glyph (PangoRenderer *renderer, /** * pango_renderer_activate: - * @renderer: a #PangoRenderer + * @renderer: a `PangoRenderer` * * Does initial setup before rendering operations on @renderer. - * pango_renderer_deactivate() should be called when done drawing. - * Calls such as pango_renderer_draw_layout() automatically + * + * [method@Pango.Renderer.deactivate] should be called when done drawing. + * Calls such as [method@Pango.Renderer.draw_layout] automatically * activate the layout before drawing on it. Calls to - * pango_renderer_activate() and pango_renderer_deactivate() can - * be nested and the renderer will only be initialized and + * `pango_renderer_activate()` and `pango_renderer_deactivate()` + * can be nested and the renderer will only be initialized and * deinitialized once. * * Since: 1.8 @@ -1238,19 +1244,20 @@ pango_renderer_activate (PangoRenderer *renderer) if (renderer->active_count == 1) { if (PANGO_RENDERER_GET_CLASS (renderer)->begin) - PANGO_RENDERER_GET_CLASS (renderer)->begin (renderer); + PANGO_RENDERER_GET_CLASS (renderer)->begin (renderer); } } /** * pango_renderer_deactivate: - * @renderer: a #PangoRenderer + * @renderer: a `PangoRenderer` + * + * Cleans up after rendering operations on @renderer. * - * Cleans up after rendering operations on @renderer. See - * docs for pango_renderer_activate(). + * See docs for [method@Pango.Renderer.activate]. * * Since: 1.8 - **/ + */ void pango_renderer_deactivate (PangoRenderer *renderer) { @@ -1260,26 +1267,27 @@ pango_renderer_deactivate (PangoRenderer *renderer) if (renderer->active_count == 1) { if (PANGO_RENDERER_GET_CLASS (renderer)->end) - PANGO_RENDERER_GET_CLASS (renderer)->end (renderer); + PANGO_RENDERER_GET_CLASS (renderer)->end (renderer); } renderer->active_count--; } /** * pango_renderer_set_color: - * @renderer: a #PangoRenderer + * @renderer: a `PangoRenderer` * @part: the part to change the color of * @color: (allow-none): the new color or %NULL to unset the current color * * Sets the color for part of the rendering. - * Also see pango_renderer_set_alpha(). + * + * Also see [method@Pango.Renderer.set_alpha]. * * Since: 1.8 - **/ + */ void pango_renderer_set_color (PangoRenderer *renderer, - PangoRenderPart part, - const PangoColor *color) + PangoRenderPart part, + const PangoColor *color) { g_return_if_fail (PANGO_IS_RENDERER_FAST (renderer)); g_return_if_fail (IS_VALID_PART (part)); @@ -1306,7 +1314,7 @@ pango_renderer_set_color (PangoRenderer *renderer, /** * pango_renderer_get_color: - * @renderer: a #PangoRenderer + * @renderer: a `PangoRenderer` * @part: the part to get the color for * * Gets the current rendering color for the specified part. @@ -1316,10 +1324,10 @@ pango_renderer_set_color (PangoRenderer *renderer, * inherited from the environment. * * Since: 1.8 - **/ + */ PangoColor * pango_renderer_get_color (PangoRenderer *renderer, - PangoRenderPart part) + PangoRenderPart part) { g_return_val_if_fail (PANGO_IS_RENDERER_FAST (renderer), NULL); g_return_val_if_fail (IS_VALID_PART (part), NULL); @@ -1332,11 +1340,12 @@ pango_renderer_get_color (PangoRenderer *renderer, /** * pango_renderer_set_alpha: - * @renderer: a #PangoRenderer + * @renderer: a `PangoRenderer` * @part: the part to set the alpha for * @alpha: an alpha value between 1 and 65536, or 0 to unset the alpha * * Sets the alpha for part of the rendering. + * * Note that the alpha may only be used if a color is * specified for @part as well. * @@ -1362,7 +1371,7 @@ pango_renderer_set_alpha (PangoRenderer *renderer, /** * pango_renderer_get_alpha: - * @renderer: a #PangoRenderer + * @renderer: a `PangoRenderer` * @part: the part to get the alpha for * * Gets the current alpha for the specified part. @@ -1385,28 +1394,30 @@ pango_renderer_get_alpha (PangoRenderer *renderer, /** * pango_renderer_part_changed: - * @renderer: a #PangoRenderer + * @renderer: a `PangoRenderer` * @part: the part for which rendering has changed. * * Informs Pango that the way that the rendering is done - * for @part has changed in a way that would prevent multiple - * pieces being joined together into one drawing call. For - * instance, if a subclass of #PangoRenderer was to add a stipple + * for @part has changed. + * + * This should be called if the rendering changes in a way that would + * prevent multiple pieces being joined together into one drawing call. + * For instance, if a subclass of `PangoRenderer` was to add a stipple * option for drawing underlines, it needs to call * - * <informalexample><programlisting> + * ``` * pango_renderer_part_changed (render, PANGO_RENDER_PART_UNDERLINE); - * </programlisting></informalexample> + * ``` * * When the stipple changes or underlines with different stipples * might be joined together. Pango automatically calls this for - * changes to colors. (See pango_renderer_set_color()) + * changes to colors. (See [method@Pango.Renderer.set_color]) * * Since: 1.8 - **/ + */ void -pango_renderer_part_changed (PangoRenderer *renderer, - PangoRenderPart part) +pango_renderer_part_changed (PangoRenderer *renderer, + PangoRenderPart part) { g_return_if_fail (PANGO_IS_RENDERER_FAST (renderer)); g_return_if_fail (IS_VALID_PART (part)); @@ -1420,16 +1431,16 @@ pango_renderer_part_changed (PangoRenderer *renderer, /** * pango_renderer_prepare_run: - * @renderer: a #PangoRenderer - * @run: a #PangoLayoutRun + * @renderer: a `PangoRenderer` + * @run: a `PangoLayoutRun` * - * Set up the state of the #PangoRenderer for rendering @run. + * Set up the state of the `PangoRenderer` for rendering @run. * * Since: 1.8 - **/ + */ static void pango_renderer_prepare_run (PangoRenderer *renderer, - PangoLayoutRun *run) + PangoLayoutRun *run) { g_return_if_fail (PANGO_IS_RENDERER_FAST (renderer)); @@ -1438,7 +1449,7 @@ pango_renderer_prepare_run (PangoRenderer *renderer, static void pango_renderer_default_prepare_run (PangoRenderer *renderer, - PangoLayoutRun *run) + PangoLayoutRun *run) { PangoColor *fg_color = NULL; PangoColor *bg_color = NULL; @@ -1458,50 +1469,50 @@ pango_renderer_default_prepare_run (PangoRenderer *renderer, PangoAttribute *attr = l->data; switch ((int) attr->klass->type) - { - case PANGO_ATTR_UNDERLINE: - renderer->underline = ((PangoAttrInt *)attr)->value; - break; + { + case PANGO_ATTR_UNDERLINE: + renderer->underline = ((PangoAttrInt *)attr)->value; + break; - case PANGO_ATTR_OVERLINE: - renderer->priv->overline = ((PangoAttrInt *)attr)->value; - break; + case PANGO_ATTR_OVERLINE: + renderer->priv->overline = ((PangoAttrInt *)attr)->value; + break; - case PANGO_ATTR_STRIKETHROUGH: - renderer->strikethrough = ((PangoAttrInt *)attr)->value; - break; + case PANGO_ATTR_STRIKETHROUGH: + renderer->strikethrough = ((PangoAttrInt *)attr)->value; + break; - case PANGO_ATTR_FOREGROUND: - fg_color = &((PangoAttrColor *)attr)->color; - break; + case PANGO_ATTR_FOREGROUND: + fg_color = &((PangoAttrColor *)attr)->color; + break; - case PANGO_ATTR_BACKGROUND: - bg_color = &((PangoAttrColor *)attr)->color; - break; + case PANGO_ATTR_BACKGROUND: + bg_color = &((PangoAttrColor *)attr)->color; + break; - case PANGO_ATTR_UNDERLINE_COLOR: - underline_color = &((PangoAttrColor *)attr)->color; - break; + case PANGO_ATTR_UNDERLINE_COLOR: + underline_color = &((PangoAttrColor *)attr)->color; + break; - case PANGO_ATTR_OVERLINE_COLOR: - overline_color = &((PangoAttrColor *)attr)->color; - break; + case PANGO_ATTR_OVERLINE_COLOR: + overline_color = &((PangoAttrColor *)attr)->color; + break; - case PANGO_ATTR_STRIKETHROUGH_COLOR: - strikethrough_color = &((PangoAttrColor *)attr)->color; - break; + case PANGO_ATTR_STRIKETHROUGH_COLOR: + strikethrough_color = &((PangoAttrColor *)attr)->color; + break; - case PANGO_ATTR_FOREGROUND_ALPHA: + case PANGO_ATTR_FOREGROUND_ALPHA: fg_alpha = ((PangoAttrInt *)attr)->value; - break; + break; - case PANGO_ATTR_BACKGROUND_ALPHA: + case PANGO_ATTR_BACKGROUND_ALPHA: bg_alpha = ((PangoAttrInt *)attr)->value; - break; + break; - default: - break; - } + default: + break; + } } if (!underline_color) @@ -1528,17 +1539,17 @@ pango_renderer_default_prepare_run (PangoRenderer *renderer, /** * pango_renderer_set_matrix: - * @renderer: a #PangoRenderer - * @matrix: (allow-none): a #PangoMatrix, or %NULL to unset any existing matrix. + * @renderer: a `PangoRenderer` + * @matrix: (allow-none): a `PangoMatrix`, or %NULL to unset any existing matrix. * (No matrix set is the same as setting the identity matrix.) * * Sets the transformation matrix that will be applied when rendering. * * Since: 1.8 - **/ + */ void pango_renderer_set_matrix (PangoRenderer *renderer, - const PangoMatrix *matrix) + const PangoMatrix *matrix) { g_return_if_fail (PANGO_IS_RENDERER_FAST (renderer)); @@ -1548,17 +1559,19 @@ pango_renderer_set_matrix (PangoRenderer *renderer, /** * pango_renderer_get_matrix: - * @renderer: a #PangoRenderer + * @renderer: a `PangoRenderer` * * Gets the transformation matrix that will be applied when - * rendering. See pango_renderer_set_matrix(). + * rendering. + * + * See [method@Pango.Renderer.set_matrix]. * * Return value: (nullable): the matrix, or %NULL if no matrix has - * been set (which is the same as the identity matrix). The returned - * matrix is owned by Pango and must not be modified or freed. + * been set (which is the same as the identity matrix). The returned + * matrix is owned by Pango and must not be modified or freed. * * Since: 1.8 - **/ + */ const PangoMatrix * pango_renderer_get_matrix (PangoRenderer *renderer) { @@ -1569,9 +1582,10 @@ pango_renderer_get_matrix (PangoRenderer *renderer) /** * pango_renderer_get_layout: - * @renderer: a #PangoRenderer + * @renderer: a `PangoRenderer` * * Gets the layout currently being rendered using @renderer. + * * Calling this function only makes sense from inside a subclass's * methods, like in its draw_shape vfunc, for example. * @@ -1579,10 +1593,10 @@ pango_renderer_get_matrix (PangoRenderer *renderer) * rendered. * * Return value: (transfer none) (nullable): the layout, or %NULL if - * no layout is being rendered using @renderer at this time. + * no layout is being rendered using @renderer at this time. * * Since: 1.20 - **/ + */ PangoLayout * pango_renderer_get_layout (PangoRenderer *renderer) { @@ -1594,9 +1608,10 @@ pango_renderer_get_layout (PangoRenderer *renderer) /** * pango_renderer_get_layout_line: - * @renderer: a #PangoRenderer + * @renderer: a `PangoRenderer` * * Gets the layout line currently being rendered using @renderer. + * * Calling this function only makes sense from inside a subclass's * methods, like in its draw_shape vfunc, for example. * @@ -1607,9 +1622,9 @@ pango_renderer_get_layout (PangoRenderer *renderer) * if no layout line is being rendered using @renderer at this time. * * Since: 1.20 - **/ + */ PangoLayoutLine * -pango_renderer_get_layout_line (PangoRenderer *renderer) +pango_renderer_get_layout_line (PangoRenderer *renderer) { return renderer->priv->line; } diff --git a/pango/pango-renderer.h b/pango/pango-renderer.h index 89107fd1..98c4cfb0 100644 --- a/pango/pango-renderer.h +++ b/pango/pango-renderer.h @@ -65,12 +65,15 @@ typedef enum * the Renderer; may be %NULL, which should be treated the * same as the identity matrix. * - * #PangoRenderer is a base class for objects that are used to - * render Pango objects such as #PangoGlyphString and - * #PangoLayout. + * `PangoRenderer` is a base class for objects that can render text + * provided as `PangoGlyphString` or `PangoLayout`. + * + * By subclassing `PangoRenderer` and overriding operations such as + * @draw_glyphs and @draw_rectangle, renderers for particular font + * backends and destinations can be created. * * Since: 1.8 - **/ + */ struct _PangoRenderer { /*< private >*/ diff --git a/pango/pango-script.c b/pango/pango-script.c index fc95309f..7116a0a4 100644 --- a/pango/pango-script.c +++ b/pango/pango-script.c @@ -53,15 +53,6 @@ * of the copyright holder. */ -/** - * SECTION:scripts - * @short_description:Identifying writing systems and languages - * @title:Scripts and Languages - * - * The functions in this section are used to identify the writing - * system, or <firstterm>script</firstterm> of individual characters - * and of ranges within a larger text string. - */ #include "config.h" #include <stdlib.h> #include <string.h> @@ -73,17 +64,18 @@ * pango_script_for_unichar: * @ch: a Unicode character * - * Looks up the script for a particular character (as defined by - * Unicode Standard Annex \#24). No check is made for @ch being a - * valid Unicode character; if you pass in invalid character, the - * result is undefined. + * Looks up the script for a particular character. + * + * The script of a character is defined by Unicode Standard Annex \#24. + * No check is made for @ch being a valid Unicode character; if you pass + * in invalid character, the result is undefined. * * Note that while the return type of this function is declared - * as PangoScript, as of Pango 1.18, this function simply returns + * as `PangoScript`, as of Pango 1.18, this function simply returns * the return value of g_unichar_get_script(). Callers must be * prepared to handle unknown values. * - * Return value: the #PangoScript for the character. + * Return value: the `PangoScript` for the character. * * Since: 1.4 * Deprecated: 1.44. Use g_unichar_get_script() diff --git a/pango/pango-script.h b/pango/pango-script.h index a7ec3246..c1579982 100644 --- a/pango/pango-script.h +++ b/pango/pango-script.h @@ -29,7 +29,7 @@ G_BEGIN_DECLS /** * PangoScriptIter: * - * A #PangoScriptIter is used to iterate through a string + * A `PangoScriptIter` is used to iterate through a string * and identify ranges in different scripts. **/ typedef struct _PangoScriptIter PangoScriptIter; @@ -156,16 +156,16 @@ typedef struct _PangoScriptIter PangoScriptIter; * @PANGO_SCRIPT_OLD_HUNGARIAN: Old Hungarian. Since: 1.40 * @PANGO_SCRIPT_SIGNWRITING: Signwriting. Since: 1.40 * - * The #PangoScript enumeration identifies different writing - * systems. The values correspond to the names as defined in the - * Unicode standard. See <ulink - * url="http://www.unicode.org/reports/tr24/">Unicode Standard Annex - * #24: Script names</ulink>. + * The `PangoScript` enumeration identifies different writing + * systems. + * + * The values correspond to the names as defined in the Unicode standard. See + * [Unicode Standard Annex 24: Script names](http://www.unicode.org/reports/tr24/) * * Note that this enumeration is deprecated and will not be updated * to include values in newer versions of the Unicode standard. - * Applications should use the GUnicodeScript enumeration instead, - * whose values are interchangeable with PangoScript. + * Applications should use the `GUnicodeScript` enumeration instead, + * whose values are interchangeable with `PangoScript`. */ typedef enum { /* ISO 15924 code */ PANGO_SCRIPT_INVALID_CODE = -1, diff --git a/pango/pango-tabs.c b/pango/pango-tabs.c index 56a34468..2c2717ee 100644 --- a/pango/pango-tabs.c +++ b/pango/pango-tabs.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,14 +19,6 @@ * Boston, MA 02111-1307, USA. */ -/** - * SECTION:tab-stops - * @short_description:Structures for storing tab stops - * @title:Tab Stops - * - * Functions in this section are used to deal with #PangoTabArray objects - * that can be used to set tab stop positions in a #PangoLayout. - */ #include "config.h" #include "pango-tabs.h" #include "pango-impl-utils.h" @@ -36,19 +28,21 @@ typedef struct _PangoTab PangoTab; struct _PangoTab { - gint location; /* Offset in pixels of this tab stop - * from the left margin of the text. - */ + gint location; /* Offset in pixels of this tab stop + * from the left margin of the text. + */ PangoTabAlign alignment; /* Where the tab stop appears relative - * to the text. - */ + * to the text. + */ }; /** * PangoTabArray: * - * A #PangoTabArray struct contains an array - * of tab stops. Each tab stop has an alignment and a position. + * A `PangoTabArray` contains an array of tab stops. + * + * `PangoTabArray` can be used to set tab stops in a `PangoLayout`. + * Each tab stop has an alignment and a position. */ struct _PangoTabArray { @@ -74,16 +68,17 @@ init_tabs (PangoTabArray *array, gint start, gint end) * @initial_size: Initial number of tab stops to allocate, can be 0 * @positions_in_pixels: whether positions are in pixel units * - * Creates an array of @initial_size tab stops. Tab stops are specified in - * pixel units if @positions_in_pixels is %TRUE, otherwise in Pango - * units. All stops are initially at position 0. + * Creates an array of @initial_size tab stops. + * + * Tab stops are specified in pixel units if @positions_in_pixels is %TRUE, + * otherwise in Pango units. All stops are initially at position 0. * - * Return value: the newly allocated #PangoTabArray, which should - * be freed with pango_tab_array_free(). - **/ + * Return value: the newly allocated `PangoTabArray`, which should + * be freed with [method@Pango.TabArray.free]. + */ PangoTabArray* -pango_tab_array_new (gint initial_size, - gboolean positions_in_pixels) +pango_tab_array_new (gint initial_size, + gboolean positions_in_pixels) { PangoTabArray *array; @@ -95,8 +90,7 @@ pango_tab_array_new (gint initial_size, * optimization. */ array = g_slice_new (PangoTabArray); - array->size = initial_size; - array->allocated = initial_size; + array->size = initial_size; array->allocated = initial_size; if (array->allocated > 0) { @@ -119,20 +113,20 @@ pango_tab_array_new (gint initial_size, * @first_position: position of first tab stop * @...: additional alignment/position pairs * - * This is a convenience function that creates a #PangoTabArray - * and allows you to specify the alignment and position of each - * tab stop. You <emphasis>must</emphasis> provide an alignment - * and position for @size tab stops. + * Creates * a `PangoTabArray` and allows you to specify the alignment + * and position of each tab stop. + * + * You **must** provide an alignment and position for @size tab stops. * - * Return value: the newly allocated #PangoTabArray, which should - * be freed with pango_tab_array_free(). - **/ + * Return value: the newly allocated `PangoTabArray`, which should + * be freed with [method@Pango.TabArray.free]. + */ PangoTabArray * pango_tab_array_new_with_positions (gint size, - gboolean positions_in_pixels, - PangoTabAlign first_alignment, - gint first_position, - ...) + gboolean positions_in_pixels, + PangoTabAlign first_alignment, + gint first_position, + ...) { PangoTabArray *array; va_list args; @@ -176,13 +170,13 @@ G_DEFINE_BOXED_TYPE (PangoTabArray, pango_tab_array, /** * pango_tab_array_copy: - * @src: #PangoTabArray to copy + * @src: `PangoTabArray` to copy * - * Copies a #PangoTabArray + * Copies a `PangoTabArray`. * - * Return value: the newly allocated #PangoTabArray, which should - * be freed with pango_tab_array_free(). - **/ + * Return value: the newly allocated `PangoTabArray`, which should + * be freed with [method@Pango.TabArray.free]. + */ PangoTabArray* pango_tab_array_copy (PangoTabArray *src) { @@ -200,13 +194,12 @@ pango_tab_array_copy (PangoTabArray *src) /** * pango_tab_array_free: - * @tab_array: a #PangoTabArray + * @tab_array: a `PangoTabArray` * * Frees a tab array and associated resources. - * - **/ + */ void -pango_tab_array_free (PangoTabArray *tab_array) +pango_tab_array_free (PangoTabArray *tab_array) { g_return_if_fail (tab_array != NULL); @@ -217,12 +210,12 @@ pango_tab_array_free (PangoTabArray *tab_array) /** * pango_tab_array_get_size: - * @tab_array: a #PangoTabArray + * @tab_array: a `PangoTabArray` * * Gets the number of tab stops in @tab_array. * * Return value: the number of tab stops in the array. - **/ + */ gint pango_tab_array_get_size (PangoTabArray *tab_array) { @@ -233,16 +226,17 @@ pango_tab_array_get_size (PangoTabArray *tab_array) /** * pango_tab_array_resize: - * @tab_array: a #PangoTabArray + * @tab_array: a `PangoTabArray` * @new_size: new size of the array * - * Resizes a tab array. You must subsequently initialize any tabs that - * were added as a result of growing the array. + * Resizes a tab array. * - **/ + * You must subsequently initialize any tabs + * that were added as a result of growing the array. + */ void pango_tab_array_resize (PangoTabArray *tab_array, - gint new_size) + gint new_size) { if (new_size > tab_array->allocated) { @@ -250,13 +244,13 @@ pango_tab_array_resize (PangoTabArray *tab_array, /* Ratchet allocated size up above the index. */ if (tab_array->allocated == 0) - tab_array->allocated = 2; + tab_array->allocated = 2; while (new_size > tab_array->allocated) - tab_array->allocated = tab_array->allocated * 2; + tab_array->allocated = tab_array->allocated * 2; tab_array->tabs = g_renew (PangoTab, tab_array->tabs, - tab_array->allocated); + tab_array->allocated); init_tabs (tab_array, current_end, tab_array->allocated); } @@ -266,21 +260,21 @@ pango_tab_array_resize (PangoTabArray *tab_array, /** * pango_tab_array_set_tab: - * @tab_array: a #PangoTabArray + * @tab_array: a `PangoTabArray` * @tab_index: the index of a tab stop * @alignment: tab alignment * @location: tab location in Pango units * * Sets the alignment and location of a tab stop. - * @alignment must always be #PANGO_TAB_LEFT in the current - * implementation. * - **/ + * @alignment must always be %PANGO_TAB_LEFT in the current + * implementation. + */ void -pango_tab_array_set_tab (PangoTabArray *tab_array, - gint tab_index, - PangoTabAlign alignment, - gint location) +pango_tab_array_set_tab (PangoTabArray *tab_array, + gint tab_index, + PangoTabAlign alignment, + gint location) { g_return_if_fail (tab_array != NULL); g_return_if_fail (tab_index >= 0); @@ -296,19 +290,18 @@ pango_tab_array_set_tab (PangoTabArray *tab_array, /** * pango_tab_array_get_tab: - * @tab_array: a #PangoTabArray + * @tab_array: a `PangoTabArray` * @tab_index: tab stop index * @alignment: (out) (allow-none): location to store alignment, or %NULL * @location: (out) (allow-none): location to store tab position, or %NULL * * Gets the alignment and position of a tab stop. - * - **/ + */ void -pango_tab_array_get_tab (PangoTabArray *tab_array, - gint tab_index, - PangoTabAlign *alignment, - gint *location) +pango_tab_array_get_tab (PangoTabArray *tab_array, + gint tab_index, + PangoTabAlign *alignment, + gint *location) { g_return_if_fail (tab_array != NULL); g_return_if_fail (tab_index < tab_array->size); @@ -323,21 +316,22 @@ pango_tab_array_get_tab (PangoTabArray *tab_array, /** * pango_tab_array_get_tabs: - * @tab_array: a #PangoTabArray + * @tab_array: a `PangoTabArray` * @alignments: (out) (allow-none): location to store an array of tab * stop alignments, or %NULL * @locations: (out) (allow-none) (array): location to store an array * of tab positions, or %NULL * * If non-%NULL, @alignments and @locations are filled with allocated - * arrays of length pango_tab_array_get_size(). You must free the - * returned array. + * arrays. * - **/ + * The arrays are of length [method@Pango.TabArray.get_size]. + * You must free the returned array. + */ void pango_tab_array_get_tabs (PangoTabArray *tab_array, - PangoTabAlign **alignments, - gint **locations) + PangoTabAlign **alignments, + gint **locations) { gint i; @@ -353,9 +347,9 @@ pango_tab_array_get_tabs (PangoTabArray *tab_array, while (i < tab_array->size) { if (alignments) - (*alignments)[i] = tab_array->tabs[i].alignment; + (*alignments)[i] = tab_array->tabs[i].alignment; if (locations) - (*locations)[i] = tab_array->tabs[i].location; + (*locations)[i] = tab_array->tabs[i].location; ++i; } @@ -363,13 +357,13 @@ pango_tab_array_get_tabs (PangoTabArray *tab_array, /** * pango_tab_array_get_positions_in_pixels: - * @tab_array: a #PangoTabArray + * @tab_array: a `PangoTabArray` * - * Returns %TRUE if the tab positions are in pixels, %FALSE if they are - * in Pango units. + * Returns %TRUE if the tab positions are in pixels, + * %FALSE if they are in Pango units. * * Return value: whether positions are in pixels. - **/ + */ gboolean pango_tab_array_get_positions_in_pixels (PangoTabArray *tab_array) { diff --git a/pango/pango-tabs.h b/pango/pango-tabs.h index 664cedbb..893132ed 100644 --- a/pango/pango-tabs.h +++ b/pango/pango-tabs.h @@ -32,7 +32,7 @@ typedef struct _PangoTabArray PangoTabArray; * PangoTabAlign: * @PANGO_TAB_LEFT: the tab stop appears to the left of the text. * - * A #PangoTabAlign specifies where a tab stop appears relative to the text. + * `PangoTabAlign` specifies where a tab stop appears relative to the text. */ typedef enum { @@ -47,11 +47,6 @@ typedef enum */ } PangoTabAlign; -/** - * PANGO_TYPE_TAB_ARRAY: - * - * The #GObject type for #PangoTabArray. - */ #define PANGO_TYPE_TAB_ARRAY (pango_tab_array_get_type ()) PANGO_AVAILABLE_IN_ALL diff --git a/pango/pango-types.h b/pango/pango-types.h index 4662c71e..2998d8ec 100644 --- a/pango/pango-types.h +++ b/pango/pango-types.h @@ -31,8 +31,10 @@ G_BEGIN_DECLS typedef struct _PangoLogAttr PangoLogAttr; +#ifndef __GI_SCANNER__ typedef struct _PangoEngineLang PangoEngineLang; typedef struct _PangoEngineShape PangoEngineShape; +#endif typedef struct _PangoFont PangoFont; typedef struct _PangoFontMap PangoFontMap; @@ -45,7 +47,7 @@ typedef struct _PangoRectangle PangoRectangle; /** * PangoGlyph: * - * A #PangoGlyph represents a single glyph in the output form of a string. + * A `PangoGlyph` represents a single glyph in the output form of a string. */ typedef guint32 PangoGlyph; @@ -54,11 +56,11 @@ typedef guint32 PangoGlyph; /** * PANGO_SCALE: * - * The %PANGO_SCALE macro represents the scale between dimensions used - * for Pango distances and device units. (The definition of device - * units is dependent on the output device; it will typically be pixels - * for a screen, and points for a printer.) %PANGO_SCALE is currently - * 1024, but this may be changed in the future. + * The scale between dimensions used for Pango distances and device units. + * + * The definition of device units is dependent on the output device; it will + * typically be pixels for a screen, and points for a printer. %PANGO_SCALE is + * currently 1024, but this may be changed in the future. * * When setting font sizes, device units are always considered to be * points (as in "12 point font"), rather than pixels. @@ -130,10 +132,11 @@ double pango_units_to_double (int i) G_GNUC_CONST; * @width: width of the rectangle. * @height: height of the rectangle. * - * The #PangoRectangle structure represents a rectangle. It is frequently - * used to represent the logical or ink extents of a single glyph or section - * of text. (See, for instance, pango_font_get_glyph_extents()) + * The `PangoRectangle` structure represents a rectangle. * + * `PangoRectangle` is frequently used to represent the logical or ink + * extents of a single glyph or section of text. (See, for instance, + * [method@Pango.Font.get_glyph_extents].) */ struct _PangoRectangle { @@ -149,7 +152,7 @@ struct _PangoRectangle * PANGO_ASCENT: * @rect: a #PangoRectangle * - * Extracts the <firstterm>ascent</firstterm> from a #PangoRectangle + * Extracts the *ascent* from a #PangoRectangle * representing glyph extents. The ascent is the distance from the * baseline to the highest point of the character. This is positive if the * glyph ascends above the baseline. @@ -158,7 +161,7 @@ struct _PangoRectangle * PANGO_DESCENT: * @rect: a #PangoRectangle * - * Extracts the <firstterm>descent</firstterm> from a #PangoRectangle + * Extracts the *descent* from a #PangoRectangle * representing glyph extents. The descent is the distance from the * baseline to the lowest point of the character. This is positive if the * glyph descends below the baseline. @@ -167,7 +170,7 @@ struct _PangoRectangle * PANGO_LBEARING: * @rect: a #PangoRectangle * - * Extracts the <firstterm>left bearing</firstterm> from a #PangoRectangle + * Extracts the *left bearing* from a #PangoRectangle * representing glyph extents. The left bearing is the distance from the * horizontal origin to the farthest left point of the character. * This is positive for characters drawn completely to the right of the @@ -177,7 +180,7 @@ struct _PangoRectangle * PANGO_RBEARING: * @rect: a #PangoRectangle * - * Extracts the <firstterm>right bearing</firstterm> from a #PangoRectangle + * Extracts the *right bearing* from a #PangoRectangle * representing glyph extents. The right bearing is the distance from the * horizontal origin to the farthest right point of the character. * This is positive except for characters drawn completely to the left of the diff --git a/pango/pango-utils.c b/pango/pango-utils.c index 6f48c62c..5283da35 100644 --- a/pango/pango-utils.c +++ b/pango/pango-utils.c @@ -19,24 +19,6 @@ * Boston, MA 02111-1307, USA. */ -/** - * SECTION:pango-version - * @short_description:Tools for checking Pango version at compile- and run-time. - * @title:Version Checking - * - * The capital-letter macros defined here can be used to check the version of Pango - * at compile-time, and to <firstterm>encode</firstterm> Pango versions into integers. - * - * The functions can be used to check the version of the linked Pango library at run-time. - */ -/** - * SECTION:utils - * @short_description:Various convenience and utility functions - * @title: Miscellaneous Utilities - * - * The functions and utilities in this section are mostly used from Pango - * backends and modules, but may be useful for other purposes too. - */ #include "config.h" #include <errno.h> #include <string.h> @@ -70,15 +52,13 @@ /** * pango_version: * - * This is similar to the macro %PANGO_VERSION except that - * it returns the encoded version of Pango available at run-time, - * as opposed to the version available at compile-time. + * Returns the encoded version of Pango available at run-time. * - * A version number can be encoded into an integer using - * PANGO_VERSION_ENCODE(). + * This is similar to the macro %PANGO_VERSION except that the macro + * returns the encoded version available at compile-time. A version + * number can be encoded into an integer using PANGO_VERSION_ENCODE(). * - * Returns: The encoded version of Pango library - * available at run time. + * Returns: The encoded version of Pango library available at run time. * * Since: 1.16 **/ @@ -91,14 +71,14 @@ pango_version (void) /** * pango_version_string: * - * This is similar to the macro %PANGO_VERSION_STRING except that - * it returns the version of Pango available at run-time, as opposed to - * the version available at compile-time. + * Returns the version of Pango available at run-time. + * + * This is similar to the macro %PANGO_VERSION_STRING except that the + * macro returns the version available at compile-time. * - * Returns: A string containing the version of Pango library - * available at run time. - * The returned string is owned by Pango and should not be modified - * or freed. + * Returns: A string containing the version of Pango library available + * at run time. The returned string is owned by Pango and should not + * be modified or freed. * * Since: 1.16 **/ @@ -115,11 +95,13 @@ pango_version_string (void) * @required_micro: the required major version. * * Checks that the Pango library in use is compatible with the - * given version. Generally you would pass in the constants - * %PANGO_VERSION_MAJOR, %PANGO_VERSION_MINOR, %PANGO_VERSION_MICRO - * as the three arguments to this function; that produces - * a check that the library in use at run-time is compatible with - * the version of Pango the application or module was compiled against. + * given version. + * + * Generally you would pass in the constants %PANGO_VERSION_MAJOR, + * %PANGO_VERSION_MINOR, %PANGO_VERSION_MICRO as the three arguments + * to this function; that produces a check that the library in use at + * run-time is compatible with the version of Pango the application or + * module was compiled against. * * Compatibility is defined by two things: first the version * of the running library is newer than the version @@ -258,17 +240,18 @@ pango_split_file_list (const char *str) * @stream: a stdio stream * @str: #GString buffer into which to write the result * - * Reads an entire line from a file into a buffer. Lines may - * be delimited with '\n', '\r', '\n\r', or '\r\n'. The delimiter + * Reads an entire line from a file into a buffer. + * + * Lines may be delimited with '\n', '\r', '\n\r', or '\r\n'. The delimiter * is not written into the buffer. Text after a '#' character is treated as * a comment and skipped. '\' can be used to escape a # character. * '\' proceeding a line delimiter combines adjacent lines. A '\' proceeding * any other character is ignored and written into the output buffer * unmodified. * - * Return value: 0 if the stream was already at an %EOF character, otherwise - * the number of lines read (this is useful for maintaining - * a line number counter which doesn't combine lines with '\') + * Return value: 0 if the stream was already at an %EOF character, + * otherwise the number of lines read (this is useful for maintaining + * a line number counter which doesn't combine lines with '\') * * Deprecated: 1.38 **/ @@ -394,9 +377,10 @@ pango_skip_space (const char **pos) * @pos: (inout): in/out string position * @out: a #GString into which to write the result * - * Scans a word into a #GString buffer. A word consists - * of [A-Za-z_] followed by zero or more [A-Za-z_0-9] - * Leading white space is skipped. + * Scans a word into a #GString buffer. + * + * A word consists of [A-Za-z_] followed by zero or more + * [A-Za-z_0-9]. Leading white space is skipped. * * Return value: %FALSE if a parse error occurred. * @@ -438,9 +422,10 @@ pango_scan_word (const char **pos, GString *out) * @pos: (inout): in/out string position * @out: a #GString into which to write the result * - * Scans a string into a #GString buffer. The string may either - * be a sequence of non-white-space characters, or a quoted - * string with '"'. Instead a quoted string, '\"' represents + * Scans a string into a #GString buffer. + * + * The string may either be a sequence of non-white-space characters, + * or a quoted string with '"'. Instead a quoted string, '\"' represents * a literal quote. Leading white space outside of quotes is skipped. * * Return value: %FALSE if a parse error occurred. @@ -531,6 +516,7 @@ pango_scan_string (const char **pos, GString *out) * @out: (out): an int into which to write the result * * Scans an integer. + * * Leading white space is skipped. * * Return value: %FALSE if a parse error occurred. @@ -842,6 +828,7 @@ pango_parse_flags (GType type, * @n_families: (out): will be set to the length of the @families array. * * Look up all user defined aliases for the alias @fontname. + * * The resulting font family names will be stored in @families, * and the number of families in @n_families. * @@ -903,11 +890,11 @@ pango_find_base_dir (const gchar *text, * pango_is_zero_width: * @ch: a Unicode character * - * Checks @ch to see if it is a character that should not be - * normally rendered on the screen. This includes all Unicode characters - * with "ZERO WIDTH" in their name, as well as <firstterm>bidi</firstterm> formatting characters, and - * a few other ones. This is totally different from g_unichar_iszerowidth() - * and is at best misnamed. + * Checks if a character that should not be normally rendered. + * + * This includes all Unicode characters with "ZERO WIDTH" in their name, + * as well as *bidi* formatting characters, and a few other ones. This is + * totally different from g_unichar_iszerowidth() and is at best misnamed. * * Return value: %TRUE if @ch is a zero-width character, %FALSE otherwise * @@ -957,10 +944,10 @@ pango_is_zero_width (gunichar ch) * @thickness: (inout): pointer to the thickness of a line, in Pango units * @position: (inout): corresponding position * - * Quantizes the thickness and position of a line, typically an - * underline or strikethrough, to whole device pixels, that is integer - * multiples of %PANGO_SCALE. The purpose of this function is to avoid - * such lines looking blurry. + * Quantizes the thickness and position of a line to whole device pixels. + * + * This is typically used for underline or strikethrough. The purpose of + * this function is to avoid such lines looking blurry. * * Care is taken to make sure @thickness is at least one pixel when this * function returns, but returned @position may become zero as a result @@ -994,8 +981,10 @@ pango_quantize_line_geometry (int *thickness, * pango_units_from_double: * @d: double floating-point value * - * Converts a floating-point number to Pango units: multiplies - * it by %PANGO_SCALE and rounds to nearest integer. + * Converts a floating-point number to Pango units. + * + * The conversion is done by multiplying @d by %PANGO_SCALE and + * rounding the result to nearest integer. * * Return value: the value in Pango units. * @@ -1011,8 +1000,9 @@ pango_units_from_double (double d) * pango_units_to_double: * @i: value in Pango units * - * Converts a number in Pango units to floating-point: divides - * it by %PANGO_SCALE. + * Converts a number in Pango units to floating-point. + * + * The conversion is done by dividing @i by %PANGO_SCALE. * * Return value: the double value. * @@ -1029,19 +1019,21 @@ pango_units_to_double (int i) * @inclusive: (allow-none): rectangle to round to pixels inclusively, or %NULL. * @nearest: (allow-none): rectangle to round to nearest pixels, or %NULL. * - * Converts extents from Pango units to device units, dividing by the - * %PANGO_SCALE factor and performing rounding. + * Converts extents from Pango units to device units. + * + * The conversion is done by dividing by the %PANGO_SCALE factor and + * performing rounding. * - * The @inclusive rectangle is converted by flooring the x/y coordinates and extending - * width/height, such that the final rectangle completely includes the original - * rectangle. + * The @inclusive rectangle is converted by flooring the x/y coordinates + * and extending width/height, such that the final rectangle completely + * includes the original rectangle. * * The @nearest rectangle is converted by rounding the coordinates * of the rectangle to the nearest device unit (pixel). * * The rule to which argument to use is: if you want the resulting device-space - * rectangle to completely contain the original rectangle, pass it in as @inclusive. - * If you want two touching-but-not-overlapping rectangles stay + * rectangle to completely contain the original rectangle, pass it in as + * @inclusive. If you want two touching-but-not-overlapping rectangles stay * touching-but-not-overlapping after rounding to device units, pass them in * as @nearest. * diff --git a/pango/pangocairo-context.c b/pango/pangocairo-context.c index 1b8bfbba..d880f1b3 100644 --- a/pango/pangocairo-context.c +++ b/pango/pangocairo-context.c @@ -158,16 +158,18 @@ _pango_cairo_update_context (cairo_t *cr, /** * pango_cairo_update_context: * @cr: a Cairo context - * @context: a #PangoContext, from a pangocairo font map + * @context: a `PangoContext`, from a pangocairo font map * - * Updates a #PangoContext previously created for use with Cairo to + * Updates a `PangoContext` previously created for use with Cairo to * match the current transformation and target surface of a Cairo - * context. If any layouts have been created for the context, - * it's necessary to call pango_layout_context_changed() on those + * context. + * + * If any layouts have been created for the context, + * it's necessary to call [method@Pango.Layout.context_changed] on those * layouts. * * Since: 1.10 - **/ + */ void pango_cairo_update_context (cairo_t *cr, PangoContext *context) @@ -180,18 +182,20 @@ pango_cairo_update_context (cairo_t *cr, /** * pango_cairo_context_set_resolution: - * @context: a #PangoContext, from a pangocairo font map + * @context: a `PangoContext`, from a pangocairo font map * @dpi: the resolution in "dots per inch". (Physical inches aren't actually * involved; the terminology is conventional.) A 0 or negative value * means to use the resolution from the font map. * - * Sets the resolution for the context. This is a scale factor between - * points specified in a #PangoFontDescription and Cairo units. The + * Sets the resolution for the context. + * + * This is a scale factor between + * points specified in a `PangoFontDescription` and Cairo units. The * default value is 96, meaning that a 10 point font will be 13 * units high. (10 * 96. / 72. = 13.3). * * Since: 1.10 - **/ + */ void pango_cairo_context_set_resolution (PangoContext *context, double dpi) @@ -202,15 +206,16 @@ pango_cairo_context_set_resolution (PangoContext *context, /** * pango_cairo_context_get_resolution: - * @context: a #PangoContext, from a pangocairo font map + * @context: a `PangoContext`, from a pangocairo font map * - * Gets the resolution for the context. See pango_cairo_context_set_resolution() + * Gets the resolution for the context. + * See [func@PangoCairo.context_set_resolution] * * Return value: the resolution in "dots per inch". A negative value will - * be returned if no resolution has previously been set. + * be returned if no resolution has previously been set. * * Since: 1.10 - **/ + */ double pango_cairo_context_get_resolution (PangoContext *context) { @@ -224,12 +229,13 @@ pango_cairo_context_get_resolution (PangoContext *context) /** * pango_cairo_context_set_font_options: - * @context: a #PangoContext, from a pangocairo font map - * @options: (nullable): a #cairo_font_options_t, or %NULL to unset - * any previously set options. A copy is made. + * @context: a `PangoContext`, from a pangocairo font map + * @options: (nullable): a `cairo_font_options_t`, or %NULL to unset + * any previously set options. A copy is made. * * Sets the font options used when rendering text with this context. - * These options override any options that pango_cairo_update_context() + * + * These options override any options that [func@update_context] * derives from the target surface. * * Since: 1.10 @@ -278,18 +284,21 @@ pango_cairo_context_set_font_options (PangoContext *context, /** * pango_cairo_context_get_font_options: - * @context: a #PangoContext, from a pangocairo font map + * @context: a `PangoContext`, from a pangocairo font map * * Retrieves any font rendering options previously set with - * pango_cairo_context_set_font_options(). This function does not report options - * that are derived from the target surface by pango_cairo_update_context() + * [func@PangoCairo.context_set_font_options]. + * + * This function + * does not report options that are derived from the target + * surface by [func@update_context]. * * Return value: (nullable): the font options previously set on the * context, or %NULL if no options have been set. This value is * owned by the context and must not be modified or freed. * * Since: 1.10 - **/ + */ const cairo_font_options_t * pango_cairo_context_get_font_options (PangoContext *context) { @@ -307,15 +316,15 @@ pango_cairo_context_get_font_options (PangoContext *context) /** * _pango_cairo_context_merge_font_options: - * @context: a #PangoContext - * @options: a #cairo_font_options_t + * @context: a `PangoContext` + * @options: a `cairo_font_options_t` * * Merge together options from the target surface and explicitly set * on the context. * * Return value: the combined set of font options. This value is owned - * by the context and must not be modified or freed. - **/ + * by the context and must not be modified or freed. + */ const cairo_font_options_t * _pango_cairo_context_get_merged_font_options (PangoContext *context) { @@ -336,7 +345,7 @@ _pango_cairo_context_get_merged_font_options (PangoContext *context) /** * pango_cairo_context_set_shape_renderer: - * @context: a #PangoContext, from a pangocairo font map + * @context: a `PangoContext`, from a pangocairo font map * @func: (nullable): Callback function for rendering attributes of * type %PANGO_ATTR_SHAPE, or %NULL to disable shape rendering. * @data: User data that will be passed to @func. @@ -344,8 +353,9 @@ _pango_cairo_context_get_merged_font_options (PangoContext *context) * context is freed to release @data, or %NULL. * * Sets callback function for context to use for rendering attributes - * of type %PANGO_ATTR_SHAPE. See #PangoCairoShapeRendererFunc for - * details. + * of type %PANGO_ATTR_SHAPE. + * + * See `PangoCairoShapeRendererFunc` for details. * * Since: 1.18 */ @@ -371,26 +381,27 @@ pango_cairo_context_set_shape_renderer (PangoContext *context, /** * pango_cairo_context_get_shape_renderer: (skip) - * @context: a #PangoContext, from a pangocairo font map + * @context: a `PangoContext`, from a pangocairo font map * @data: Pointer to #gpointer to return user data * * Sets callback function for context to use for rendering attributes - * of type %PANGO_ATTR_SHAPE. See #PangoCairoShapeRendererFunc for - * details. + * of type %PANGO_ATTR_SHAPE. + * + * See `PangoCairoShapeRendererFunc` for details. * * Retrieves callback function and associated user data for rendering * attributes of type %PANGO_ATTR_SHAPE as set by - * pango_cairo_context_set_shape_renderer(), if any. + * [func@PangoCairo.context_set_shape_renderer], if any. * - * Return value: (transfer none) (nullable): the shape rendering callback previously - * set on the context, or %NULL if no shape rendering callback have - * been set. + * Return value: (transfer none) (nullable): the shape rendering callback + * previously set on the context, or %NULL if no shape rendering callback + * have been set. * * Since: 1.18 */ PangoCairoShapeRendererFunc -pango_cairo_context_get_shape_renderer (PangoContext *context, - gpointer *data) +pango_cairo_context_get_shape_renderer (PangoContext *context, + gpointer *data) { PangoCairoContextInfo *info; @@ -417,19 +428,21 @@ pango_cairo_context_get_shape_renderer (PangoContext *context, * @cr: a Cairo context * * Creates a context object set up to match the current transformation - * and target surface of the Cairo context. This context can then be - * used to create a layout using pango_layout_new(). + * and target surface of the Cairo context. + * + * This context can then be + * used to create a layout using [ctor@Pango.Layout.new]. * * This function is a convenience function that creates a context using - * the default font map, then updates it to @cr. If you just need to - * create a layout for use with @cr and do not need to access #PangoContext - * directly, you can use pango_cairo_create_layout() instead. + * the default font map, then updates it to @cr. If you just need to + * create a layout for use with @cr and do not need to access `PangoContext` + * directly, you can use [func@create_layout] instead. * - * Return value: (transfer full): the newly created #PangoContext. Free with - * g_object_unref(). + * Return value: (transfer full): the newly created `PangoContext`. + * Free with g_object_unref(). * * Since: 1.22 - **/ + */ PangoContext * pango_cairo_create_context (cairo_t *cr) { @@ -450,24 +463,26 @@ pango_cairo_create_context (cairo_t *cr) * @cr: a Cairo context * * Creates a layout object set up to match the current transformation - * and target surface of the Cairo context. This layout can then be + * and target surface of the Cairo context. + * + * This layout can then be * used for text measurement with functions like - * pango_layout_get_size() or drawing with functions like - * pango_cairo_show_layout(). If you change the transformation - * or target surface for @cr, you need to call pango_cairo_update_layout() + * [method@Pango.Layout.get_size] or drawing with functions like + * [func@show_layout]. If you change the transformation or target + * surface for @cr, you need to call [func@update_layout]. * * This function is the most convenient way to use Cairo with Pango, * however it is slightly inefficient since it creates a separate - * #PangoContext object for each layout. This might matter in an + * `PangoContext` object for each layout. This might matter in an * application that was laying out large amounts of text. * - * Return value: (transfer full): the newly created #PangoLayout. Free with - * g_object_unref(). + * Return value: (transfer full): the newly created `PangoLayout`. + * Free with g_object_unref(). * * Since: 1.10 - **/ + */ PangoLayout * -pango_cairo_create_layout (cairo_t *cr) +pango_cairo_create_layout (cairo_t *cr) { PangoContext *context; PangoLayout *layout; @@ -484,14 +499,14 @@ pango_cairo_create_layout (cairo_t *cr) /** * pango_cairo_update_layout: * @cr: a Cairo context - * @layout: a #PangoLayout, from pango_cairo_create_layout() + * @layout: a `PangoLayout`, from [func@create_layout] * - * Updates the private #PangoContext of a #PangoLayout created with - * pango_cairo_create_layout() to match the current transformation - * and target surface of a Cairo context. + * Updates the private `PangoContext` of a `PangoLayout` created with + * [func@create_layout] to match the current transformation and target + * surface of a Cairo context. * * Since: 1.10 - **/ + */ void pango_cairo_update_layout (cairo_t *cr, PangoLayout *layout) diff --git a/pango/pangocairo-font.c b/pango/pangocairo-font.c index 1cadd005..c4155f68 100644 --- a/pango/pangocairo-font.c +++ b/pango/pangocairo-font.c @@ -137,17 +137,17 @@ done: /** * pango_cairo_font_get_scaled_font: - * @font: a #PangoFont from a #PangoCairoFontMap + * @font: a `PangoFont` from a `PangoCairoFontMap` * - * Gets the #cairo_scaled_font_t used by @font. + * Gets the `cairo_scaled_font_t` used by @font. * The scaled font can be referenced and kept using * cairo_scaled_font_reference(). * - * Return value: (transfer none) (nullable): the #cairo_scaled_font_t used by @font, - * or %NULL if @font is %NULL. + * Return value: (transfer none) (nullable): the `cairo_scaled_font_t` + * used by @font, or %NULL if @font is %NULL. * * Since: 1.18 - **/ + */ cairo_scaled_font_t * pango_cairo_font_get_scaled_font (PangoCairoFont *cfont) { @@ -163,14 +163,14 @@ pango_cairo_font_get_scaled_font (PangoCairoFont *cfont) /** * _pango_cairo_font_install: - * @font: a #PangoCairoFont + * @font: a `PangoCairoFont` * @cr: a #cairo_t * * Makes @font the current font for rendering in the specified * Cairo context. * * Return value: %TRUE if font was installed successfully, %FALSE otherwise. - **/ + */ gboolean _pango_cairo_font_install (PangoFont *font, cairo_t *cr) diff --git a/pango/pangocairo-fontmap.c b/pango/pangocairo-fontmap.c index 120ccb89..524102ba 100644 --- a/pango/pangocairo-fontmap.c +++ b/pango/pangocairo-fontmap.c @@ -47,29 +47,30 @@ pango_cairo_font_map_default_init (PangoCairoFontMapIface *iface) /** * pango_cairo_font_map_new: * - * Creates a new #PangoCairoFontMap object; a fontmap is used - * to cache information about available fonts, and holds - * certain global parameters such as the resolution. - * In most cases, you can use pango_cairo_font_map_get_default() + * Creates a new `PangoCairoFontMap` object. + * + * A fontmap is used to cache information about available fonts, + * and holds certain global parameters such as the resolution. + * In most cases, you can use `func@PangoCairo.font_map_get_default] * instead. * * Note that the type of the returned object will depend * on the particular font backend Cairo was compiled to use; - * You generally should only use the #PangoFontMap and - * #PangoCairoFontMap interfaces on the returned object. + * You generally should only use the `PangoFontMap` and + * `PangoCairoFontMap` interfaces on the returned object. * * You can override the type of backend returned by using an - * environment variable %PANGOCAIRO_BACKEND. Supported types, + * environment variable %PANGOCAIRO_BACKEND. Supported types, * based on your build, are fc (fontconfig), win32, and coretext. * If requested type is not available, NULL is returned. Ie. * this is only useful for testing, when at least two backends * are compiled in. * - * Return value: (transfer full): the newly allocated #PangoFontMap, - * which should be freed with g_object_unref(). + * Return value: (transfer full): the newly allocated `PangoFontMap`, + * which should be freed with g_object_unref(). * * Since: 1.10 - **/ + */ PangoFontMap * pango_cairo_font_map_new (void) { @@ -110,20 +111,19 @@ pango_cairo_font_map_new (void) * pango_cairo_font_map_new_for_font_type: * @fonttype: desired #cairo_font_type_t * - * Creates a new #PangoCairoFontMap object of the type suitable + * Creates a new `PangoCairoFontMap` object of the type suitable * to be used with cairo font backend of type @fonttype. * - * In most cases one should simply use @pango_cairo_font_map_new(), - * or in fact in most of those cases, just use - * @pango_cairo_font_map_get_default(). + * In most cases one should simply use [type_func@PangoCairo.FontMap.new], or + * in fact in most of those cases, just use [func@PangoCairo.FontMap.get_default]. * * Return value: (transfer full) (nullable): the newly allocated - * #PangoFontMap of suitable type which should be freed - * with g_object_unref(), or %NULL if the requested - * cairo font backend is not supported / compiled in. + * `PangoFontMap` of suitable type which should be freed with + * g_object_unref(), or %NULL if the requested cairo font backend + * is not supported / compiled in. * * Since: 1.18 - **/ + */ PangoFontMap * pango_cairo_font_map_new_for_font_type (cairo_font_type_t fonttype) { @@ -151,27 +151,28 @@ static GPrivate default_font_map = G_PRIVATE_INIT (g_object_unref); /* MT-safe * /** * pango_cairo_font_map_get_default: * - * Gets a default #PangoCairoFontMap to use with Cairo. + * Gets a default `PangoCairoFontMap` to use with Cairo. * - * Note that the type of the returned object will depend - * on the particular font backend Cairo was compiled to use; - * You generally should only use the #PangoFontMap and - * #PangoCairoFontMap interfaces on the returned object. + * Note that the type of the returned object will depend on the + * particular font backend Cairo was compiled to use; you generally + * should only use the `PangoFontMap` and `PangoCairoFontMap` + * interfaces on the returned object. * * The default Cairo fontmap can be changed by using - * pango_cairo_font_map_set_default(). This can be used to - * change the Cairo font backend that the default fontmap - * uses for example. + * [method@PangoCairo.FontMap.set_default]. This can be used to + * change the Cairo font backend that the default fontmap uses + * for example. * * Note that since Pango 1.32.6, the default fontmap is per-thread. - * Each thread gets its own default fontmap. In this way, - * PangoCairo can be used safely from multiple threads. + * Each thread gets its own default fontmap. In this way, PangoCairo + * can be used safely from multiple threads. * * Return value: (transfer none): the default PangoCairo fontmap - * for the current thread. This object is owned by Pango and must not be freed. + * for the current thread. This object is owned by Pango and must + * not be freed. * * Since: 1.10 - **/ + */ PangoFontMap * pango_cairo_font_map_get_default (void) { @@ -190,24 +191,24 @@ pango_cairo_font_map_get_default (void) * pango_cairo_font_map_set_default: * @fontmap: (nullable): The new default font map, or %NULL * - * Sets a default #PangoCairoFontMap to use with Cairo. + * Sets a default `PangoCairoFontMap` to use with Cairo. * * This can be used to change the Cairo font backend that the - * default fontmap uses for example. The old default font map + * default fontmap uses for example. The old default font map * is unreffed and the new font map referenced. * * Note that since Pango 1.32.6, the default fontmap is per-thread. * This function only changes the default fontmap for - * the current thread. Default fontmaps of existing threads + * the current thread. Default fontmaps of existing threads * are not changed. Default fontmaps of any new threads will - * still be created using pango_cairo_font_map_new(). + * still be created using [type_func@PangoCairo.FontMap.new]. * * A value of %NULL for @fontmap will cause the current default - * font map to be released and a new default font - * map to be created on demand, using pango_cairo_font_map_new(). + * font map to be released and a new default font map to be created + * on demand, using [type_func@PangoCairo.FontMap.new]. * * Since: 1.22 - **/ + */ void pango_cairo_font_map_set_default (PangoCairoFontMap *fontmap) { @@ -221,20 +222,22 @@ pango_cairo_font_map_set_default (PangoCairoFontMap *fontmap) /** * pango_cairo_font_map_set_resolution: - * @fontmap: a #PangoCairoFontMap + * @fontmap: a `PangoCairoFontMap` * @dpi: the resolution in "dots per inch". (Physical inches aren't actually * involved; the terminology is conventional.) * - * Sets the resolution for the fontmap. This is a scale factor between - * points specified in a #PangoFontDescription and Cairo units. The + * Sets the resolution for the fontmap. + * + * This is a scale factor between + * points specified in a `PangoFontDescription` and Cairo units. The * default value is 96, meaning that a 10 point font will be 13 * units high. (10 * 96. / 72. = 13.3). * * Since: 1.10 - **/ + */ void pango_cairo_font_map_set_resolution (PangoCairoFontMap *fontmap, - double dpi) + double dpi) { g_return_if_fail (PANGO_IS_CAIRO_FONT_MAP (fontmap)); @@ -243,9 +246,11 @@ pango_cairo_font_map_set_resolution (PangoCairoFontMap *fontmap, /** * pango_cairo_font_map_get_resolution: - * @fontmap: a #PangoCairoFontMap + * @fontmap: a `PangoCairoFontMap` + * + * Gets the resolution for the fontmap. * - * Gets the resolution for the fontmap. See pango_cairo_font_map_set_resolution() + * See [method@PangoCairo.FontMap.set_resolution]. * * Return value: the resolution in "dots per inch" * @@ -261,16 +266,16 @@ pango_cairo_font_map_get_resolution (PangoCairoFontMap *fontmap) /** * pango_cairo_font_map_create_context: (skip) - * @fontmap: a #PangoCairoFontMap + * @fontmap: a `PangoCairoFontMap` * - * Create a #PangoContext for the given fontmap. + * Create a `PangoContext` for the given fontmap. * * Return value: the newly created context; free with g_object_unref(). * * Since: 1.10 * * Deprecated: 1.22: Use pango_font_map_create_context() instead. - **/ + */ PangoContext * pango_cairo_font_map_create_context (PangoCairoFontMap *fontmap) { @@ -281,14 +286,14 @@ pango_cairo_font_map_create_context (PangoCairoFontMap *fontmap) /** * pango_cairo_font_map_get_font_type: - * @fontmap: a #PangoCairoFontMap + * @fontmap: a `PangoCairoFontMap` * - * Gets the type of Cairo font backend that @fontmap uses. + * Gets the type of Cairo font backend that @fontmap uses. * - * Return value: the #cairo_font_type_t cairo font backend type + * Return value: the `cairo_font_type_t` cairo font backend type * * Since: 1.18 - **/ + */ cairo_font_type_t pango_cairo_font_map_get_font_type (PangoCairoFontMap *fontmap) { diff --git a/pango/pangocairo-render.c b/pango/pangocairo-render.c index 614a3a44..9e3cfab8 100644 --- a/pango/pangocairo-render.c +++ b/pango/pangocairo-render.c @@ -19,139 +19,6 @@ * Boston, MA 02111-1307, USA. */ -/** - * SECTION:pangocairo - * @short_description:Font handling and rendering with Cairo - * @title:Cairo Fonts and Rendering - * - * The <ulink url="http://cairographics.org">Cairo library</ulink> is a - * vector graphics library with a powerful rendering model. It has such - * features as anti-aliased primitives, alpha-compositing, and - * gradients. Multiple backends for Cairo are available, to allow - * rendering to images, to PDF files, and to the screen on X and on other - * windowing systems. The functions in this section allow using Pango - * to render to Cairo surfaces. - * - * Using Pango with Cairo is straightforward. A #PangoContext created - * with pango_cairo_font_map_create_context() can be used on any - * Cairo context (cairo_t), but needs to be updated to match the - * current transformation matrix and target surface of the Cairo context - * using pango_cairo_update_context(). The convenience functions - * pango_cairo_create_layout() and pango_cairo_update_layout() handle - * the common case where the program doesn't need to manipulate the - * properties of the #PangoContext. - * - * When you get the metrics of a layout or of a piece of a layout using - * functions such as pango_layout_get_extents(), the reported metrics - * are in user-space coordinates. If a piece of text is 10 units long, - * and you call cairo_scale (cr, 2.0), it still is more-or-less 10 - * units long. However, the results will be affected by hinting - * (that is, the process of adjusting the text to look good on the - * pixel grid), so you shouldn't assume they are completely independent - * of the current transformation matrix. Note that the basic metrics - * functions in Pango report results in integer Pango units. To get - * to the floating point units used in Cairo divide by %PANGO_SCALE. - * - * ## Using Pango with Cairo ## {#rotated-example} - * - * |[<!-- language="C" --> - * #include <math.h> - * #include <pango/pangocairo.h> - * - * static void - * draw_text (cairo_t *cr) - * { - * #define RADIUS 150 - * #define N_WORDS 10 - * #define FONT "Sans Bold 27" - * - * PangoLayout *layout; - * PangoFontDescription *desc; - * int i; - * - * /* Center coordinates on the middle of the region we are drawing - * */ - * cairo_translate (cr, RADIUS, RADIUS); - * - * /* Create a PangoLayout, set the font and text */ - * layout = pango_cairo_create_layout (cr); - * - * pango_layout_set_text (layout, "Text", -1); - * desc = pango_font_description_from_string (FONT); - * pango_layout_set_font_description (layout, desc); - * pango_font_description_free (desc); - * - * /* Draw the layout N_WORDS times in a circle */ - * for (i = 0; i < N_WORDS; i++) - * { - * int width, height; - * double angle = (360. * i) / N_WORDS; - * double red; - * - * cairo_save (cr); - * - * /* Gradient from red at angle == 60 to blue at angle == 240 */ - * red = (1 + cos ((angle - 60) * G_PI / 180.)) / 2; - * cairo_set_source_rgb (cr, red, 0, 1.0 - red); - * - * cairo_rotate (cr, angle * G_PI / 180.); - * - * /* Inform Pango to re-layout the text with the new transformation */ - * pango_cairo_update_layout (cr, layout); - * - * pango_layout_get_size (layout, &width, &height); - * cairo_move_to (cr, - ((double)width / PANGO_SCALE) / 2, - RADIUS); - * pango_cairo_show_layout (cr, layout); - * - * cairo_restore (cr); - * } - * - * /* free the layout object */ - * g_object_unref (layout); - * } - * - * int main (int argc, char **argv) - * { - * cairo_t *cr; - * char *filename; - * cairo_status_t status; - * cairo_surface_t *surface; - * - * if (argc != 2) - * { - * g_printerr ("Usage: cairosimple OUTPUT_FILENAME\n"); - * return 1; - * } - * - * filename = argv[1]; - * - * surface = cairo_image_surface_create (CAIRO_FORMAT_ARGB32, - * 2 * RADIUS, 2 * RADIUS); - * cr = cairo_create (surface); - * - * cairo_set_source_rgb (cr, 1.0, 1.0, 1.0); - * cairo_paint (cr); - * draw_text (cr); - * cairo_destroy (cr); - * - * status = cairo_surface_write_to_png (surface, filename); - * cairo_surface_destroy (surface); - * - * if (status != CAIRO_STATUS_SUCCESS) - * { - * g_printerr ("Could not save png to '%s'\n", filename); - * return 1; - * } - * - * return 0; - * } - * ]| - * - * Once you build and run the example code above, you should see the - * following result: - * - *  - */ #include "config.h" #include <math.h> @@ -1174,15 +1041,16 @@ _pango_cairo_do_error_underline (cairo_t *cr, /** * pango_cairo_show_glyph_string: * @cr: a Cairo context - * @font: a #PangoFont from a #PangoCairoFontMap - * @glyphs: a #PangoGlyphString + * @font: a `PangoFont` from a `PangoCairoFontMap` + * @glyphs: a `PangoGlyphString` * * Draws the glyphs in @glyphs in the specified cairo context. + * * The origin of the glyphs (the left edge of the baseline) will * be drawn at the current point of the cairo context. * * Since: 1.10 - **/ + */ void pango_cairo_show_glyph_string (cairo_t *cr, PangoFont *font, @@ -1199,21 +1067,22 @@ pango_cairo_show_glyph_string (cairo_t *cr, * pango_cairo_show_glyph_item: * @cr: a Cairo context * @text: the UTF-8 text that @glyph_item refers to - * @glyph_item: a #PangoGlyphItem + * @glyph_item: a `PangoGlyphItem` * * Draws the glyphs in @glyph_item in the specified cairo context, + * * embedding the text associated with the glyphs in the output if the * output format supports it (PDF for example), otherwise it acts - * similar to pango_cairo_show_glyph_string(). + * similar to [func@show_glyph_string]. * * The origin of the glyphs (the left edge of the baseline) will * be drawn at the current point of the cairo context. * * Note that @text is the start of the text for layout, which is then - * indexed by <literal>@glyph_item->item->offset</literal>. + * indexed by `glyph_item->item->offset`. * * Since: 1.22 - **/ + */ void pango_cairo_show_glyph_item (cairo_t *cr, const char *text, @@ -1229,14 +1098,15 @@ pango_cairo_show_glyph_item (cairo_t *cr, /** * pango_cairo_show_layout_line: * @cr: a Cairo context - * @line: a #PangoLayoutLine + * @line: a `PangoLayoutLine` + * + * Draws a `PangoLayoutLine` in the specified cairo context. * - * Draws a #PangoLayoutLine in the specified cairo context. * The origin of the glyphs (the left edge of the line) will * be drawn at the current point of the cairo context. * * Since: 1.10 - **/ + */ void pango_cairo_show_layout_line (cairo_t *cr, PangoLayoutLine *line) @@ -1252,12 +1122,13 @@ pango_cairo_show_layout_line (cairo_t *cr, * @cr: a Cairo context * @layout: a Pango layout * - * Draws a #PangoLayout in the specified cairo context. - * The top-left corner of the #PangoLayout will be drawn + * Draws a `PangoLayout` in the specified cairo context. + * + * The top-left corner of the `PangoLayout` will be drawn * at the current point of the cairo context. * * Since: 1.10 - **/ + */ void pango_cairo_show_layout (cairo_t *cr, PangoLayout *layout) @@ -1278,12 +1149,14 @@ pango_cairo_show_layout (cairo_t *cr, * * Draw a squiggly line in the specified cairo context that approximately * covers the given rectangle in the style of an underline used to indicate a - * spelling error. (The width of the underline is rounded to an integer + * spelling error. + * + * The width of the underline is rounded to an integer * number of up/down segments and the resulting rectangle is centered in the - * original rectangle) + * original rectangle. * * Since: 1.14 - **/ + */ void pango_cairo_show_error_underline (cairo_t *cr, double x, @@ -1300,15 +1173,17 @@ pango_cairo_show_error_underline (cairo_t *cr, /** * pango_cairo_glyph_string_path: * @cr: a Cairo context - * @font: a #PangoFont from a #PangoCairoFontMap - * @glyphs: a #PangoGlyphString + * @font: a `PangoFont` from a `PangoCairoFontMap` + * @glyphs: a `PangoGlyphString` * * Adds the glyphs in @glyphs to the current path in the specified - * cairo context. The origin of the glyphs (the left edge of the baseline) + * cairo context. + * + * The origin of the glyphs (the left edge of the baseline) * will be at the current point of the cairo context. * * Since: 1.10 - **/ + */ void pango_cairo_glyph_string_path (cairo_t *cr, PangoFont *font, @@ -1323,14 +1198,16 @@ pango_cairo_glyph_string_path (cairo_t *cr, /** * pango_cairo_layout_line_path: * @cr: a Cairo context - * @line: a #PangoLayoutLine + * @line: a `PangoLayoutLine` * - * Adds the text in #PangoLayoutLine to the current path in the - * specified cairo context. The origin of the glyphs (the left edge + * Adds the text in `PangoLayoutLine` to the current path in the + * specified cairo context. + * + * The origin of the glyphs (the left edge * of the line) will be at the current point of the cairo context. * * Since: 1.10 - **/ + */ void pango_cairo_layout_line_path (cairo_t *cr, PangoLayoutLine *line) @@ -1346,12 +1223,14 @@ pango_cairo_layout_line_path (cairo_t *cr, * @cr: a Cairo context * @layout: a Pango layout * - * Adds the text in a #PangoLayout to the current path in the - * specified cairo context. The top-left corner of the #PangoLayout + * Adds the text in a `PangoLayout` to the current path in the + * specified cairo context. + * + * The top-left corner of the `PangoLayout` * will be at the current point of the cairo context. * * Since: 1.10 - **/ + */ void pango_cairo_layout_path (cairo_t *cr, PangoLayout *layout) @@ -1372,12 +1251,14 @@ pango_cairo_layout_path (cairo_t *cr, * * Add a squiggly line to the current path in the specified cairo context that * approximately covers the given rectangle in the style of an underline used - * to indicate a spelling error. (The width of the underline is rounded to an + * to indicate a spelling error. + * + * The width of the underline is rounded to an * integer number of up/down segments and the resulting rectangle is centered - * in the original rectangle) + * in the original rectangle. * * Since: 1.14 - **/ + */ void pango_cairo_error_underline_path (cairo_t *cr, double x, diff --git a/pango/pangocairo.h b/pango/pangocairo.h index 633ccf9d..7e860554 100644 --- a/pango/pangocairo.h +++ b/pango/pangocairo.h @@ -30,9 +30,11 @@ G_BEGIN_DECLS /** * PangoCairoFont: * - * #PangoCairoFont is an interface exported by fonts for - * use with Cairo. The actual type of the font will depend - * on the particular font technology Cairo was compiled to use. + * `PangoCairoFont` is an interface exported by fonts for + * use with Cairo. + * + * The actual type of the font will depend on the particular + * font technology Cairo was compiled to use. * * Since: 1.18 **/ @@ -55,9 +57,11 @@ typedef struct _PangoCairoFont PangoCairoFont; /** * PangoCairoFontMap: * - * #PangoCairoFontMap is an interface exported by font maps for - * use with Cairo. The actual type of the font map will depend - * on the particular font technology Cairo was compiled to use. + * `PangoCairoFontMap` is an interface exported by font maps for + * use with Cairo. + * + * The actual type of the font map will depend on the particular + * font technology Cairo was compiled to use. * * Since: 1.10 **/ diff --git a/pango/pangocoretext.c b/pango/pangocoretext.c index b6941c05..5f9cf2df 100644 --- a/pango/pangocoretext.c +++ b/pango/pangocoretext.c @@ -20,14 +20,6 @@ * Boston, MA 02111-1307, USA. */ -/** - * SECTION:coretext-fonts - * @short_description:Font handling and rendering on OS X - * @title:CoreText Fonts and Rendering - * - * The macros and functions in this section are used to access fonts natively on - * OS X using the CoreText text rendering subsystem. - */ #include "config.h" #include "pangocoretext.h" diff --git a/pango/pangofc-decoder.c b/pango/pangofc-decoder.c index 7af4cdfc..0d3b00a0 100644 --- a/pango/pangofc-decoder.c +++ b/pango/pangofc-decoder.c @@ -19,14 +19,6 @@ * Boston, MA 02111-1307, USA. */ -/** - * SECTION:pangofc-decoder - * @short_description:Custom font encoding handling - * @title:PangoFcDecoder - * - * PangoFcDecoder represents a decoder that an application provides - * for handling a font that is encoded in a custom way. - */ #include "config.h" #include "pangofc-decoder.h" @@ -44,15 +36,17 @@ pango_fc_decoder_class_init (PangoFcDecoderClass *klass G_GNUC_UNUSED) /** * pango_fc_decoder_get_charset: - * @decoder: a #PangoFcDecoder - * @fcfont: the #PangoFcFont to query. + * @decoder: a `PangoFcDecoder` + * @fcfont: the `PangoFcFont` to query. * - * Generates an #FcCharSet of supported characters for the fcfont - * given. The returned #FcCharSet will be a reference to an - * internal value stored by the #PangoFcDecoder and must not + * Generates an `FcCharSet` of supported characters for the @fcfont + * given. + * + * The returned `FcCharSet` will be a reference to an + * internal value stored by the `PangoFcDecoder` and must not * be modified or freed. * - * Returns: (transfer none): the #FcCharset for @fcfont; must not + * Returns: (transfer none): the `FcCharset` for @fcfont; must not * be modified or freed. * * Since: 1.6 @@ -68,12 +62,14 @@ pango_fc_decoder_get_charset (PangoFcDecoder *decoder, /** * pango_fc_decoder_get_glyph: - * @decoder: a #PangoFcDecoder - * @fcfont: a #PangoFcFont to query. - * @wc: the Unicode code point to convert to a single #PangoGlyph. + * @decoder: a `PangoFcDecoder` + * @fcfont: a `PangoFcFont` to query. + * @wc: the Unicode code point to convert to a single `PangoGlyph`. + * + * Generates a `PangoGlyph` for the given Unicode point using the + * custom decoder. * - * Generates a #PangoGlyph for the given Unicode point using the - * custom decoder. For complex scripts where there can be multiple + * For complex scripts where there can be multiple * glyphs for a single character, the decoder will return whatever * glyph is most convenient for it. (Usually whatever glyph is directly * in the fonts character map table.) diff --git a/pango/pangofc-decoder.h b/pango/pangofc-decoder.h index 7c78958c..6268c428 100644 --- a/pango/pangofc-decoder.h +++ b/pango/pangofc-decoder.h @@ -48,13 +48,14 @@ typedef struct _PangoFcDecoderClass PangoFcDecoderClass; /** * PangoFcDecoder: * - * #PangoFcDecoder is a virtual base class that implementations will - * inherit from. It's the interface that is used to define a custom - * encoding for a font. These objects are created in your code from a - * function callback that was originally registered with - * pango_fc_font_map_add_decoder_find_func(). Pango requires - * information about the supported charset for a font as well as the - * individual character to glyph conversions. Pango gets that + * `PangoFcDecoder` is a virtual base class that implementations will + * inherit from. + * + * It's the interface that is used to define a custom encoding for a font. + * These objects are created in your code from a function callback that was + * originally registered with [method@PangoFc.FontMap.add_decoder_find_func]. + * Pango requires information about the supported charset for a font as well + * as the individual character to glyph conversions. Pango gets that * information via the #get_charset and #get_glyph callbacks into your * object implementation. * @@ -68,16 +69,16 @@ struct _PangoFcDecoder /** * PangoFcDecoderClass: - * @get_charset: This returns an #FcCharset given a #PangoFcFont that + * @get_charset: This returns an `FcCharset` given a `PangoFcFont` that * includes a list of supported characters in the font. The * #FcCharSet that is returned should be an internal reference to your * code. Pango will not free this structure. It is important that * you make this callback fast because this callback is called * separately for each character to determine Unicode coverage. - * @get_glyph: This returns a single #PangoGlyph for a given Unicode + * @get_glyph: This returns a single `PangoGlyph` for a given Unicode * code point. * - * Class structure for #PangoFcDecoder. + * Class structure for `PangoFcDecoder`. * * Since: 1.6 **/ diff --git a/pango/pangofc-font.c b/pango/pangofc-font.c index cf6b427f..5a164343 100644 --- a/pango/pangofc-font.c +++ b/pango/pangofc-font.c @@ -19,24 +19,6 @@ * Boston, MA 02111-1307, USA. */ -/** - * SECTION:pangofc-font - * @short_description:Base font class for Fontconfig-based backends - * @title:PangoFcFont - * @see_also: - * <variablelist><varlistentry><term>#PangoFcFontMap</term> <listitem>The base class for font maps; creating a new - * Fontconfig-based backend involves deriving from both - * #PangoFcFontMap and #PangoFcFont.</listitem></varlistentry></variablelist> - * - * #PangoFcFont is a base class for font implementation using the - * Fontconfig and FreeType libraries. It is used in the - * <link linkend="pango-Xft-Fonts-and-Rendering">Xft</link> and - * <link linkend="pango-FreeType-Fonts-and-Rendering">FreeType</link> - * backends shipped with Pango, but can also be used when creating - * new backends. Any backend deriving from this base class will - * take advantage of the wide range of shapers implemented using - * FreeType that come with Pango. - */ #include "config.h" #include "pangofc-font-private.h" @@ -116,12 +98,23 @@ pango_fc_font_class_init (PangoFcFontClass *class) font_class->create_hb_font = pango_fc_font_create_hb_font; font_class->get_features = pango_fc_font_get_features; + /** + * PangoFcFont:pattern: + * + * The fontconfig pattern for this font. + */ g_object_class_install_property (object_class, PROP_PATTERN, g_param_spec_pointer ("pattern", "Pattern", "The fontconfig pattern for this font", G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS)); + + /** + * PangoFcFont:fontmap: + * + * The PangoFc font map this font is associated with. + */ g_object_class_install_property (object_class, PROP_FONTMAP, g_param_spec_object ("fontmap", "Font Map", @@ -534,17 +527,18 @@ pango_fc_font_real_get_glyph (PangoFcFont *font, /** * pango_fc_font_lock_face: (skip) - * @font: a #PangoFcFont. + * @font: a `PangoFcFont`. + * + * Gets the FreeType `FT_Face` associated with a font. * - * Gets the FreeType `FT_Face` associated with a font, * This face will be kept around until you call - * pango_fc_font_unlock_face(). + * [method@PangoFc.Font.unlock_face]. * * Return value: the FreeType `FT_Face` associated with @font. * * Since: 1.4 * Deprecated: 1.44: Use pango_font_get_hb_font() instead - **/ + */ FT_Face pango_fc_font_lock_face (PangoFcFont *font) { @@ -555,14 +549,14 @@ pango_fc_font_lock_face (PangoFcFont *font) /** * pango_fc_font_unlock_face: - * @font: a #PangoFcFont. + * @font: a `PangoFcFont`. * * Releases a font previously obtained with - * pango_fc_font_lock_face(). + * [method@PangoFc.Font.lock_face]. * * Since: 1.4 * Deprecated: 1.44: Use pango_font_get_hb_font() instead - **/ + */ void pango_fc_font_unlock_face (PangoFcFont *font) { @@ -582,7 +576,7 @@ pango_fc_font_unlock_face (PangoFcFont *font) * * Since: 1.4 * Deprecated: 1.44: Use pango_font_has_char() - **/ + */ gboolean pango_fc_font_has_char (PangoFcFont *font, gunichar wc) @@ -607,14 +601,16 @@ pango_fc_font_has_char (PangoFcFont *font, * @wc: Unicode character to look up * * Gets the glyph index for a given Unicode character - * for @font. If you only want to determine - * whether the font has the glyph, use pango_fc_font_has_char(). + * for @font. + * + * If you only want to determine whether the font has + * the glyph, use [method@PangoFc.Font.has_char]. * * Return value: the glyph index, or 0, if the Unicode * character doesn't exist in the font. * * Since: 1.4 - **/ + */ PangoGlyph pango_fc_font_get_glyph (PangoFcFont *font, gunichar wc) @@ -647,7 +643,7 @@ pango_fc_font_get_glyph (PangoFcFont *font, * Return value: a glyph index into @font. * * Since: 1.4 - **/ + */ PangoGlyph pango_fc_font_get_unknown_glyph (PangoFcFont *font, gunichar wc) @@ -670,17 +666,16 @@ _pango_fc_font_shutdown (PangoFcFont *font) /** * pango_fc_font_kern_glyphs: * @font: a #PangoFcFont - * @glyphs: a #PangoGlyphString + * @glyphs: a `PangoGlyphString` * * This function used to adjust each adjacent pair of glyphs * in @glyphs according to kerning information in @font. * * Since 1.44, it does nothing. * - * * Since: 1.4 * Deprecated: 1.32 - **/ + */ void pango_fc_font_kern_glyphs (PangoFcFont *font, PangoGlyphString *glyphs) @@ -689,15 +684,14 @@ pango_fc_font_kern_glyphs (PangoFcFont *font, /** * _pango_fc_font_get_decoder: - * @font: a #PangoFcFont + * @font: a `PangoFcFont` * * This will return any custom decoder set on this font. * * Return value: The custom decoder * * Since: 1.6 - **/ - + */ PangoFcDecoder * _pango_fc_font_get_decoder (PangoFcFont *font) { @@ -708,15 +702,15 @@ _pango_fc_font_get_decoder (PangoFcFont *font) /** * _pango_fc_font_set_decoder: - * @font: a #PangoFcFont - * @decoder: a #PangoFcDecoder to set for this font + * @font: a `PangoFcFont` + * @decoder: a `PangoFcDecoder` to set for this font + * + * This sets a custom decoder for this font. * - * This sets a custom decoder for this font. Any previous decoder - * will be released before this one is set. + * Any previous decoder will be released before this one is set. * * Since: 1.6 - **/ - + */ void _pango_fc_font_set_decoder (PangoFcFont *font, PangoFcDecoder *decoder) @@ -751,16 +745,17 @@ _pango_fc_font_set_font_key (PangoFcFont *fcfont, /** * pango_fc_font_get_raw_extents: - * @fcfont: a #PangoFcFont + * @fcfont: a `PangoFcFont` * @glyph: the glyph index to load * @ink_rect: (out) (optional): location to store ink extents of the * glyph, or %NULL * @logical_rect: (out) (optional): location to store logical extents * of the glyph or %NULL * - * Gets the extents of a single glyph from a font. The extents are in - * user space; that is, they are not transformed by any matrix in effect - * for the font. + * Gets the extents of a single glyph from a font. + * + * The extents are in user space; that is, they are not transformed + * by any matrix in effect for the font. * * Long term, this functionality probably belongs in the default * implementation of the get_glyph_extents() virtual function. @@ -769,7 +764,7 @@ _pango_fc_font_set_font_key (PangoFcFont *fcfont, * caching functionality similar to pango_ft2_font_set_glyph_info(). * * Since: 1.6 - **/ + */ void pango_fc_font_get_raw_extents (PangoFcFont *fcfont, PangoGlyph glyph, @@ -1038,7 +1033,7 @@ done: /** * pango_fc_font_get_languages: - * @font: a #PangoFcFont + * @font: a `PangoFcFont` * * Returns the languages that are supported by @font. * @@ -1048,7 +1043,7 @@ done: * and its fontmap are valid. * * Returns: (transfer none) (nullable): a %NULL-terminated - * array of PangoLanguage* + * array of `PangoLanguage`* * * Since: 1.48 */ @@ -1070,7 +1065,7 @@ pango_fc_font_get_languages (PangoFcFont *font) /** * pango_fc_font_get_pattern: (skip) - * @font: a #PangoFcFont + * @font: a `PangoFcFont` * * Returns the FcPattern that @font is based on. * diff --git a/pango/pangofc-font.h b/pango/pangofc-font.h index fbae5e10..b4aa399e 100644 --- a/pango/pangofc-font.h +++ b/pango/pangofc-font.h @@ -60,13 +60,14 @@ typedef struct _PangoFcFontClass PangoFcFontClass; /** * PangoFcFont: * - * #PangoFcFont is a base class for font implementations - * using the Fontconfig and FreeType libraries and is used in - * conjunction with #PangoFcFontMap. When deriving from this - * class, you need to implement all of its virtual functions - * other than shutdown() along with the get_glyph_extents() - * virtual function from #PangoFont. - **/ + * `PangoFcFont` is a base class for font implementations + * using the Fontconfig and FreeType libraries. + * + * It is used in onjunction with [class@PangoFc.FontMap]. + * When deriving from this class, you need to implement all + * of its virtual functions other than shutdown() along with + * the get_glyph_extents() virtual function from `PangoFont`. + */ struct _PangoFcFont { PangoFont parent_instance; diff --git a/pango/pangofc-fontmap.c b/pango/pangofc-fontmap.c index fef3394a..358b33fb 100644 --- a/pango/pangofc-fontmap.c +++ b/pango/pangofc-fontmap.c @@ -20,25 +20,15 @@ */ /** - * SECTION:pangofc-fontmap - * @short_description:Base fontmap class for Fontconfig-based backends - * @title:PangoFcFontMap - * @see_also: - * <variablelist><varlistentry> - * <term>#PangoFcFont</term> - * <listitem>The base class for fonts; creating a new - * Fontconfig-based backend involves deriving from both - * #PangoFcFontMap and #PangoFcFont.</listitem> - * </varlistentry></variablelist> - * - * PangoFcFontMap is a base class for font map implementations using the - * Fontconfig and FreeType libraries. It is used in the - * <link linkend="pango-Xft-Fonts-and-Rendering">Xft</link> and - * <link linkend="pango-FreeType-Fonts-and-Rendering">FreeType</link> - * backends shipped with Pango, but can also be used when creating - * new backends. Any backend deriving from this base class will - * take advantage of the wide range of shapers implemented using - * FreeType that come with Pango. + * PangoFcFontMap: + * + * `PangoFcFontMap` is a base class for font map implementations using the + * Fontconfig and FreeType libraries. + * + * It is used in the Xft and FreeType backends shipped with Pango, + * but can also be used when creating new backends. Any backend + * deriving from this base class will take advantage of the wide + * range of shapers implemented using FreeType that come with Pango. */ #define FONTSET_CACHE_SIZE 256 @@ -514,7 +504,7 @@ pango_fc_fontset_key_copy (const PangoFcFontsetKey *old) * Returns: the language * * Since: 1.24 - **/ + */ PangoLanguage * pango_fc_fontset_key_get_language (const PangoFcFontsetKey *key) { @@ -530,7 +520,7 @@ pango_fc_fontset_key_get_language (const PangoFcFontsetKey *key) * Returns: the font description, which is owned by @key and should not be modified. * * Since: 1.24 - **/ + */ const PangoFontDescription * pango_fc_fontset_key_get_description (const PangoFcFontsetKey *key) { @@ -546,9 +536,9 @@ pango_fc_fontset_key_get_description (const PangoFcFontsetKey *key) * Returns: the matrix, which is owned by @key and should not be modified. * * Since: 1.24 - **/ + */ const PangoMatrix * -pango_fc_fontset_key_get_matrix (const PangoFcFontsetKey *key) +pango_fc_fontset_key_get_matrix (const PangoFcFontsetKey *key) { return &key->matrix; } @@ -557,15 +547,16 @@ pango_fc_fontset_key_get_matrix (const PangoFcFontsetKey *key) * pango_fc_fontset_key_get_absolute_size: * @key: the fontset key * - * Gets the absolute font size of @key in Pango units. This is adjusted - * for both resolution and transformation matrix. + * Gets the absolute font size of @key in Pango units. + * + * This is adjusted for both resolution and transformation matrix. * * Returns: the pixel size of @key. * * Since: 1.24 - **/ + */ double -pango_fc_fontset_key_get_absolute_size (const PangoFcFontsetKey *key) +pango_fc_fontset_key_get_absolute_size (const PangoFcFontsetKey *key) { return key->pixelsize; } @@ -579,9 +570,9 @@ pango_fc_fontset_key_get_absolute_size (const PangoFcFontsetKey *key) * Returns: the resolution of @key * * Since: 1.24 - **/ + */ double -pango_fc_fontset_key_get_resolution (const PangoFcFontsetKey *key) +pango_fc_fontset_key_get_resolution (const PangoFcFontsetKey *key) { return key->resolution; } @@ -595,7 +586,7 @@ pango_fc_fontset_key_get_resolution (const PangoFcFontsetKey *key) * Returns: the context key, which is owned by @key and should not be modified. * * Since: 1.24 - **/ + */ gpointer pango_fc_fontset_key_get_context_key (const PangoFcFontsetKey *key) { @@ -702,7 +693,7 @@ pango_fc_font_key_init (PangoFcFontKey *key, * Returns: the pattern, which is owned by @key and should not be modified. * * Since: 1.24 - **/ + */ const FcPattern * pango_fc_font_key_get_pattern (const PangoFcFontKey *key) { @@ -718,7 +709,7 @@ pango_fc_font_key_get_pattern (const PangoFcFontKey *key) * Returns: the matrix, which is owned by @key and should not be modified. * * Since: 1.24 - **/ + */ const PangoMatrix * pango_fc_font_key_get_matrix (const PangoFcFontKey *key) { @@ -734,7 +725,7 @@ pango_fc_font_key_get_matrix (const PangoFcFontKey *key) * Returns: the context key, which is owned by @key and should not be modified. * * Since: 1.24 - **/ + */ gpointer pango_fc_font_key_get_context_key (const PangoFcFontKey *key) { @@ -1483,21 +1474,22 @@ pango_fc_font_map_class_init (PangoFcFontMapClass *class) /** * pango_fc_font_map_add_decoder_find_func: - * @fcfontmap: The #PangoFcFontMap to add this method to. - * @findfunc: The #PangoFcDecoderFindFunc callback function + * @fcfontmap: The `PangoFcFontMap` to add this method to. + * @findfunc: The `PangoFcDecoderFindFunc` callback function * @user_data: User data. - * @dnotify: A #GDestroyNotify callback that will be called when the - * fontmap is finalized and the decoder is released. - * - * This function saves a callback method in the #PangoFcFontMap that - * will be called whenever new fonts are created. If the - * function returns a #PangoFcDecoder, that decoder will be used to - * determine both coverage via a #FcCharSet and a one-to-one mapping of - * characters to glyphs. This will allow applications to have + * @dnotify: A `GDestroyNotify` callback that will be called when the + * fontmap is finalized and the decoder is released. + * + * This function saves a callback method in the `PangoFcFontMap` that + * will be called whenever new fonts are created. + * + * If the function returns a `PangoFcDecoder`, that decoder will be used + * to determine both coverage via a `FcCharSet` and a one-to-one mapping + * of characters to glyphs. This will allow applications to have * application-specific encodings for various fonts. * * Since: 1.6 - **/ + */ void pango_fc_font_map_add_decoder_find_func (PangoFcFontMap *fcfontmap, PangoFcDecoderFindFunc findfunc, @@ -1522,20 +1514,22 @@ pango_fc_font_map_add_decoder_find_func (PangoFcFontMap *fcfontmap, /** * pango_fc_font_map_find_decoder: - * @fcfontmap: The #PangoFcFontMap to use. - * @pattern: The #FcPattern to find the decoder for. + * @fcfontmap: The `PangoFcFontMap` to use. + * @pattern: The `FcPattern` to find the decoder for. * - * Finds the decoder to use for @pattern. Decoders can be added to - * a font map using pango_fc_font_map_add_decoder_find_func(). + * Finds the decoder to use for @pattern. * - * Returns: (transfer full) (nullable): a newly created #PangoFcDecoder + * Decoders can be added to a font map using + * [method@PangoFc.FontMap.add_decoder_find_func]. + * + * Returns: (transfer full) (nullable): a newly created `PangoFcDecoder` * object or %NULL if no decoder is set for @pattern. * * Since: 1.26 - **/ + */ PangoFcDecoder * -pango_fc_font_map_find_decoder (PangoFcFontMap *fcfontmap, - FcPattern *pattern) +pango_fc_font_map_find_decoder (PangoFcFontMap *fcfontmap, + FcPattern *pattern) { GSList *l; @@ -2222,16 +2216,17 @@ pango_fc_font_map_load_fontset (PangoFontMap *fontmap, /** * pango_fc_font_map_cache_clear: - * @fcfontmap: a #PangoFcFontMap + * @fcfontmap: a `PangoFcFontMap` * - * Clear all cached information and fontsets for this font map; - * this should be called whenever there is a change in the + * Clear all cached information and fontsets for this font map. + * + * This should be called whenever there is a change in the * output of the default_substitute() virtual function of the * font map, or if fontconfig has been reinitialized to new * configuration. * * Since: 1.4 - **/ + */ void pango_fc_font_map_cache_clear (PangoFcFontMap *fcfontmap) { @@ -2262,15 +2257,17 @@ pango_fc_font_map_changed (PangoFontMap *fontmap) /** * pango_fc_font_map_config_changed: - * @fcfontmap: a #PangoFcFontMap + * @fcfontmap: a `PangoFcFontMap` + * + * Informs font map that the fontconfig configuration (i.e., FcConfig + * object) used by this font map has changed. * - * Informs font map that the fontconfig configuration (ie, FcConfig object) - * used by this font map has changed. This currently calls - * pango_fc_font_map_cache_clear() which ensures that list of fonts, etc - * will be regenerated using the updated configuration. + * This currently calls [method@PangoFc.FontMap.cache_clear] which + * ensures that list of fonts, etc will be regenerated using the + * updated configuration. * * Since: 1.38 - **/ + */ void pango_fc_font_map_config_changed (PangoFcFontMap *fcfontmap) { @@ -2279,26 +2276,28 @@ pango_fc_font_map_config_changed (PangoFcFontMap *fcfontmap) /** * pango_fc_font_map_set_config: (skip) - * @fcfontmap: a #PangoFcFontMap + * @fcfontmap: a `PangoFcFontMap` * @fcconfig: (nullable): a `FcConfig`, or %NULL * - * Set the FcConfig for this font map to use. The default value + * Set the `FcConfig` for this font map to use. + * + * The default value * is %NULL, which causes Fontconfig to use its global "current config". - * You can create a new FcConfig object and use this API to attach it + * You can create a new `FcConfig` object and use this API to attach it * to a font map. * * This is particularly useful for example, if you want to use application - * fonts with Pango. For that, you would create a fresh FcConfig, add your + * fonts with Pango. For that, you would create a fresh `FcConfig`, add your * app fonts to it, and attach it to a new Pango font map. * * If @fcconfig is different from the previous config attached to the font map, - * pango_fc_font_map_config_changed() is called. + * [method@PangoFc.FontMap.config_changed] is called. * - * This function acquires a reference to the FcConfig object; the caller - * does NOT need to retain a reference. + * This function acquires a reference to the `FcConfig` object; the caller + * does **not** need to retain a reference. * * Since: 1.38 - **/ + */ void pango_fc_font_map_set_config (PangoFcFontMap *fcfontmap, FcConfig *fcconfig) @@ -2328,17 +2327,17 @@ pango_fc_font_map_set_config (PangoFcFontMap *fcfontmap, /** * pango_fc_font_map_get_config: (skip) - * @fcfontmap: a #PangoFcFontMap + * @fcfontmap: a `PangoFcFontMap` * * Fetches the `FcConfig` attached to a font map. * - * See also: pango_fc_font_map_set_config() + * See also: [method@PangoFc.FontMap.set_config]. * - * Returns: (nullable): the `FcConfig` object attached to @fcfontmap, which - * might be %NULL. + * Returns: (nullable): the `FcConfig` object attached to + * @fcfontmap, which might be %NULL. * * Since: 1.38 - **/ + */ FcConfig * pango_fc_font_map_get_config (PangoFcFontMap *fcfontmap) { @@ -2502,13 +2501,14 @@ _pango_fc_font_map_get_coverage (PangoFcFontMap *fcfontmap, /** * _pango_fc_font_map_fc_to_coverage: - * @charset: #FcCharSet to convert to a #PangoCoverage object. + * @charset: `FcCharSet` to convert to a `PangoCoverage` object. * - * Convert the given #FcCharSet into a new #PangoCoverage object. The - * caller is responsible for freeing the newly created object. + * Convert the given `FcCharSet` into a new `PangoCoverage` object. + * + * The caller is responsible for freeing the newly created object. * * Since: 1.6 - **/ + */ PangoCoverage * _pango_fc_font_map_fc_to_coverage (FcCharSet *charset) { @@ -2571,22 +2571,24 @@ _pango_fc_font_map_get_languages (PangoFcFontMap *fcfontmap, return data->languages; } + /** * pango_fc_font_map_create_context: - * @fcfontmap: a #PangoFcFontMap + * @fcfontmap: a `PangoFcFontMap` + * + * Creates a new context for this fontmap. * - * Creates a new context for this fontmap. This function is intended - * only for backend implementations deriving from #PangoFcFontMap; - * it is possible that a backend will store additional information - * needed for correct operation on the #PangoContext after calling - * this function. + * This function is intended only for backend implementations deriving + * from `PangoFcFontMap`; it is possible that a backend will store + * additional information needed for correct operation on the `PangoContext` + * after calling this function. * - * Return value: (transfer full): a new #PangoContext + * Return value: (transfer full): a new `PangoContext` * * Since: 1.4 * * Deprecated: 1.22: Use pango_font_map_create_context() instead. - **/ + */ PangoContext * pango_fc_font_map_create_context (PangoFcFontMap *fcfontmap) { @@ -2608,17 +2610,20 @@ shutdown_font (gpointer key, /** * pango_fc_font_map_shutdown: - * @fcfontmap: a #PangoFcFontMap + * @fcfontmap: a `PangoFcFontMap` * * Clears all cached information for the fontmap and marks - * all fonts open for the fontmap as dead. (See the shutdown() - * virtual function of #PangoFcFont.) This function might be used - * by a backend when the underlying windowing system for the font - * map exits. This function is only intended to be called - * only for backend implementations deriving from #PangoFcFontMap. + * all fonts open for the fontmap as dead. + * + * See the shutdown() virtual function of `PangoFcFont`. + * + * This function might be used by a backend when the underlying + * windowing system for the font map exits. This function is only + * intended to be called only for backend implementations deriving + * from `PangoFcFontMap`. * * Since: 1.4 - **/ + */ void pango_fc_font_map_shutdown (PangoFcFontMap *fcfontmap) { @@ -2704,21 +2709,23 @@ pango_fc_convert_width_to_pango (int fc_stretch) /** * pango_fc_font_description_from_pattern: - * @pattern: a #FcPattern + * @pattern: a `FcPattern` * @include_size: if %TRUE, the pattern will include the size from * the @pattern; otherwise the resulting pattern will be unsized. * (only %FC_SIZE is examined, not %FC_PIXEL_SIZE) * - * Creates a #PangoFontDescription that matches the specified - * Fontconfig pattern as closely as possible. Many possible Fontconfig - * pattern values, such as %FC_RASTERIZER or %FC_DPI, don't make sense in - * the context of #PangoFontDescription, so will be ignored. + * Creates a `PangoFontDescription` that matches the specified + * Fontconfig pattern as closely as possible. * - * Return value: a new #PangoFontDescription. Free with - * pango_font_description_free(). + * Many possible Fontconfig pattern values, such as %FC_RASTERIZER + * or %FC_DPI, don't make sense in the context of `PangoFontDescription`, + * so will be ignored. + * + * Return value: a new `PangoFontDescription`. Free with + * pango_font_description_free(). * * Since: 1.4 - **/ + */ PangoFontDescription * pango_fc_font_description_from_pattern (FcPattern *pattern, gboolean include_size) { @@ -3347,12 +3354,13 @@ pango_fc_family_init (PangoFcFamily *fcfamily) /** * pango_fc_font_map_get_hb_face: (skip) - * @fcfontmap: a #PangoFcFontMap - * @fcfont: a #PangoFcFont + * @fcfontmap: a `PangoFcFontMap` + * @fcfont: a `PangoFcFont` * - * Retrieves the `hb_face_t` for the given #PangoFcFont. + * Retrieves the `hb_face_t` for the given `PangoFcFont`. * - * Returns: (transfer none) (nullable): the `hb_face_t` for the given Pango font + * Returns: (transfer none) (nullable): the `hb_face_t` + * for the given font * * Since: 1.44 */ diff --git a/pango/pangofc-fontmap.h b/pango/pangofc-fontmap.h index 6fdf32d2..8ae9250e 100644 --- a/pango/pangofc-fontmap.h +++ b/pango/pangofc-fontmap.h @@ -69,10 +69,11 @@ pango_fc_font_map_get_config (PangoFcFontMap *fcfontmap); /** * PangoFcDecoderFindFunc: - * @pattern: a fully resolved #FcPattern specifying the font on the system - * @user_data: user data passed to pango_fc_font_map_add_decoder_find_func() + * @pattern: a fully resolved `FcPattern` specifying the font on the system + * @user_data: user data passed to + * [method@PangoFc.FontMap.add_decoder_find_func] * - * Callback function passed to pango_fc_font_map_add_decoder_find_func(). + * Callback function passed to [method@PangoFc.FontMap.add_decoder_find_func]. * * Return value: a new reference to a custom decoder for this pattern, * or %NULL if the default decoder handling should be used. @@ -110,22 +111,24 @@ hb_face_t * pango_fc_font_map_get_hb_face (PangoFcFontMap *fcfontmap, * @pattern: the FcPattern to tweak. * @data: user data. * - * Function type for doing final config tweaking on prepared FcPatterns. + * Function type for doing final config tweaking on prepared `FcPattern`s. */ typedef void (*PangoFcSubstituteFunc) (FcPattern *pattern, gpointer data); /** * pango_fc_font_map_set_default_substitute: - * @fontmap: a #PangoFcFontMap + * @fontmap: a `PangoFcFontMap` * @func: function to call to to do final config tweaking - * on #FcPattern objects. + * on `FcPattern` objects. * @data: data to pass to @func * @notify: function to call when @data is no longer used. * * Sets a function that will be called to do final configuration - * substitution on a #FcPattern before it is used to load - * the font. This function can be used to do things like set + * substitution on a `FcPattern` before it is used to load + * the font. + * + * This function can be used to do things like set * hinting and antialiasing options. * * Since: 1.48 @@ -138,11 +141,12 @@ void pango_fc_font_map_set_default_substitute (PangoFcFontMap *fontmap, /** * pango_fc_font_map_substitute_changed: - * @fontmap: a #PangoFcFontMap + * @fontmap: a `PangoFcFontMap` + * + * Call this function any time the results of the default + * substitution function set with + * [method@PangoFc.FontMap.set_default_substitute] change. * - * Call this function any time the results of the - * default substitution function set with - * pango_fc_font_map_set_default_substitute() change. * That is, if your substitution function will return different * results for the same input pattern, you must call this function. * @@ -154,13 +158,15 @@ void pango_fc_font_map_substitute_changed (PangoFcFontMap *fontmap); /** * PANGO_FC_GRAVITY: * - * String representing a fontconfig property name that Pango sets on any - * fontconfig pattern it passes to fontconfig if a #PangoGravity other - * than %PANGO_GRAVITY_SOUTH is desired. + * Fontconfig property that Pango sets on any + * fontconfig pattern it passes to fontconfig + * if a `PangoGravity` other than %PANGO_GRAVITY_SOUTH + * is desired. * - * The property will have a #PangoGravity value as a string, like "east". - * This can be used to write fontconfig configuration rules to choose - * different fonts for horizontal and vertical writing directions. + * The property will have a `PangoGravity` value as a string, + * like "east". This can be used to write fontconfig configuration + * rules to choose different fonts for horizontal and vertical + * writing directions. * * Since: 1.20 */ @@ -169,13 +175,13 @@ void pango_fc_font_map_substitute_changed (PangoFcFontMap *fontmap); /** * PANGO_FC_VERSION: * - * String representing a fontconfig property name that Pango sets on any + * Fontconfig property that Pango sets on any * fontconfig pattern it passes to fontconfig. * * The property will have an integer value equal to what - * pango_version() returns. - * This can be used to write fontconfig configuration rules that only affect - * certain pango versions (or only pango-using applications, or only + * [func@Pango.version] returns. This can be used to write + * fontconfig configuration rules that only affect certain + * pango versions (or only pango-using applications, or only * non-pango-using applications). * * Since: 1.20 @@ -185,15 +191,16 @@ void pango_fc_font_map_substitute_changed (PangoFcFontMap *fontmap); /** * PANGO_FC_PRGNAME: * - * String representing a fontconfig property name that Pango sets on any + * Fontconfig property that Pango sets on any * fontconfig pattern it passes to fontconfig. * * The property will have a string equal to what - * g_get_prgname() returns. - * This can be used to write fontconfig configuration rules that only affect + * g_get_prgname() returns. This can be used to write + * fontconfig configuration rules that only affect * certain applications. * - * This is equivalent to FC_PRGNAME in versions of fontconfig that have that. + * This is equivalent to FC_PRGNAME in versions of + * fontconfig that have that. * * Since: 1.24 */ @@ -202,14 +209,16 @@ void pango_fc_font_map_substitute_changed (PangoFcFontMap *fontmap); /** * PANGO_FC_FONT_FEATURES: * - * String representing a fontconfig property name that Pango reads from font - * patterns to populate list of OpenType features to be enabled for the font - * by default. + * Fontconfig property that Pango reads from font + * patterns to populate list of OpenType features + * to be enabled for the font by default. * - * The property will have a number of string elements, each of which is the - * OpenType feature tag of one feature to enable. + * The property will have a number of string elements, + * each of which is the OpenType feature tag of one feature + * to enable. * - * This is equivalent to FC_FONT_FEATURES in versions of fontconfig that have that. + * This is equivalent to FC_FONT_FEATURES in versions of + * fontconfig that have that. * * Since: 1.34 */ @@ -218,11 +227,13 @@ void pango_fc_font_map_substitute_changed (PangoFcFontMap *fontmap); /** * PANGO_FC_FONT_VARIATIONS: * - * String representing a fontconfig property name that Pango reads from font - * patterns to populate list of OpenType font variations to be used for a font. + * Fontconfig property that Pango reads from font + * patterns to populate list of OpenType font variations + * to be used for a font. * - * The property will have a string elements, each of which a comma-separated - * list of OpenType axis setting of the form AXIS=VALUE. + * The property will have a string elements, each of which + * a comma-separated list of OpenType axis setting of the + * form AXIS=VALUE. */ #define PANGO_FC_FONT_VARIATIONS "fontvariations" diff --git a/pango/pangoft2-fontmap.c b/pango/pangoft2-fontmap.c index 4fb64616..ca09a2ad 100644 --- a/pango/pangoft2-fontmap.c +++ b/pango/pangoft2-fontmap.c @@ -40,7 +40,7 @@ typedef struct _PangoFT2FontMapClass PangoFT2FontMapClass; /** * PangoFT2FontMap: * - * The #PangoFT2FontMap is the #PangoFontMap implementation for FreeType fonts. + * The `PangoFT2FontMap` is the `PangoFontMap` implementation for FreeType fonts. */ struct _PangoFT2FontMap { @@ -118,11 +118,12 @@ pango_ft2_font_map_finalize (GObject *object) /** * pango_ft2_font_map_new: * - * Create a new #PangoFT2FontMap object; a fontmap is used - * to cache information about available fonts, and holds - * certain global parameters such as the resolution and + * Create a new `PangoFT2FontMap` object. + * + * A fontmap is used to cache information about available fonts, + * and holds certain global parameters such as the resolution and * the default substitute function (see - * pango_ft2_font_map_set_default_substitute()). + * [method@PangoFT2.FontMap.set_default_substitute]). * * Return value: the newly created fontmap object. Unref * with g_object_unref() when you are finished with it. @@ -155,18 +156,20 @@ pango_ft2_font_map_changed (PangoFontMap *fontmap) /** * pango_ft2_font_map_set_default_substitute: - * @fontmap: a #PangoFT2FontMap + * @fontmap: a `PangoFT2FontMap` * @func: function to call to to do final config tweaking * on #FcPattern objects. * @data: data to pass to @func * @notify: function to call when @data is no longer used. * * Sets a function that will be called to do final configuration - * substitution on a #FcPattern before it is used to load - * the font. This function can be used to do things like set + * substitution on a `FcPattern` before it is used to load + * the font. + * + * This function can be used to do things like set * hinting and antialiasing options. * - * Deprecated: 1.46: Use pango_fc_font_map_set_default_substitute() + * Deprecated: 1.46: Use [method@PangoFc.FontMap.set_default_substitute] * instead. * * Since: 1.2 @@ -183,15 +186,16 @@ pango_ft2_font_map_set_default_substitute (PangoFT2FontMap *fontmap, /** * pango_ft2_font_map_substitute_changed: - * @fontmap: a #PangoFT2FontMap + * @fontmap: a `PangoFT2FontMap` * * Call this function any time the results of the * default substitution function set with * pango_ft2_font_map_set_default_substitute() change. + * * That is, if your substitution function will return different * results for the same input pattern, you must call this function. * - * Deprecated: 1.46: Use pango_fc_font_map_substitute_changed() + * Deprecated: 1.46: Use [method@PangoFc.FontMap.substitute_changed] * instead. * * Since: 1.2 @@ -204,7 +208,7 @@ pango_ft2_font_map_substitute_changed (PangoFT2FontMap *fontmap) /** * pango_ft2_font_map_set_resolution: - * @fontmap: a #PangoFT2FontMap + * @fontmap: a `PangoFT2FontMap` * @dpi_x: dots per inch in the X direction * @dpi_y: dots per inch in the Y direction * @@ -227,16 +231,16 @@ pango_ft2_font_map_set_resolution (PangoFT2FontMap *fontmap, /** * pango_ft2_font_map_create_context: (skip) - * @fontmap: a #PangoFT2FontMap + * @fontmap: a `PangoFT2FontMap` * - * Create a #PangoContext for the given fontmap. + * Create a `PangoContext` for the given fontmap. * * Return value: (transfer full): the newly created context; free with * g_object_unref(). * * Since: 1.2 * - * Deprecated: 1.22: Use pango_font_map_create_context() instead. + * Deprecated: 1.22: Use [method@Pango.FontMap.create_context] instead. **/ PangoContext * pango_ft2_font_map_create_context (PangoFT2FontMap *fontmap) @@ -251,13 +255,13 @@ pango_ft2_font_map_create_context (PangoFT2FontMap *fontmap) * @dpi_x: the horizontal DPI of the target device * @dpi_y: the vertical DPI of the target device * - * Retrieves a #PangoContext for the default PangoFT2 fontmap + * Retrieves a `PangoContext` for the default PangoFT2 fontmap * (see pango_ft2_font_map_for_display()) and sets the resolution * for the default fontmap to @dpi_x by @dpi_y. * - * Return value: (transfer full): the new #PangoContext + * Return value: (transfer full): the new `PangoContext` * - * Deprecated: 1.22: Use pango_font_map_create_context() instead. + * Deprecated: 1.22: Use [method@Pango.FontMap.create_context] instead. **/ G_GNUC_BEGIN_IGNORE_DEPRECATIONS PangoContext * @@ -275,13 +279,15 @@ G_GNUC_END_IGNORE_DEPRECATIONS /** * pango_ft2_font_map_for_display: (skip) * - * Returns a #PangoFT2FontMap. This font map is cached and should + * Returns a `PangoFT2FontMap`. + * + * This font map is cached and should * not be freed. If the font map is no longer needed, it can * be released with pango_ft2_shutdown_display(). Use of the * global PangoFT2 fontmap is deprecated; use pango_ft2_font_map_new() * instead. * - * Return value: (transfer none): a #PangoFT2FontMap. + * Return value: (transfer none): a `PangoFT2FontMap`. **/ PangoFontMap * pango_ft2_font_map_for_display (void) @@ -322,7 +328,7 @@ _pango_ft2_font_map_get_library (PangoFontMap *fontmap) /** * _pango_ft2_font_map_get_renderer: - * @fontmap: a #PangoFT2FontMap + * @fontmap: a `PangoFT2FontMap` * * Gets the singleton PangoFT2Renderer for this fontmap. * diff --git a/pango/pangoft2-render.c b/pango/pangoft2-render.c index 6d299392..45230fdb 100644 --- a/pango/pangoft2-render.c +++ b/pango/pangoft2-render.c @@ -20,17 +20,6 @@ * Boston, MA 02111-1307, USA. */ -/** - * SECTION:pango-renderer - * @short_description:Rendering driver base class - * @title:PangoRenderer - * - * #PangoRenderer is a base class that contains the necessary logic for - * rendering a #PangoLayout or #PangoLayoutLine. By subclassing - * #PangoRenderer and overriding operations such as @draw_glyphs and - * @draw_rectangle, renderers for particular font backends and - * destinations can be created. - */ #include "config.h" #include <math.h> @@ -589,7 +578,7 @@ pango_ft2_renderer_draw_trapezoid (PangoRenderer *renderer, /** * pango_ft2_render_layout_subpixel: - * @bitmap: a <type>FT_Bitmap</type> to render the layout onto + * @bitmap: a FT_Bitmap to render the layout onto * @layout: a #PangoLayout * @x: the X position of the left of the layout (in Pango units) * @y: the Y position of the top of the layout (in Pango units) @@ -626,7 +615,7 @@ pango_ft2_render_layout_subpixel (FT_Bitmap *bitmap, /** * pango_ft2_render_layout: - * @bitmap: a <type>FT_Bitmap</type> to render the layout onto + * @bitmap: a FT_Bitmap to render the layout onto * @layout: a #PangoLayout * @x: the X position of the left of the layout (in pixels) * @y: the Y position of the top of the layout (in pixels) @@ -644,7 +633,7 @@ pango_ft2_render_layout (FT_Bitmap *bitmap, /** * pango_ft2_render_layout_line_subpixel: - * @bitmap: a <type>FT_Bitmap</type> to render the line onto + * @bitmap: a FT_Bitmap to render the line onto * @line: a #PangoLayoutLine * @x: the x position of start of string (in Pango units) * @y: the y position of baseline (in Pango units) @@ -681,7 +670,7 @@ pango_ft2_render_layout_line_subpixel (FT_Bitmap *bitmap, /** * pango_ft2_render_layout_line: - * @bitmap: a <type>FT_Bitmap</type> to render the line onto + * @bitmap: a FT_Bitmap to render the line onto * @line: a #PangoLayoutLine * @x: the x position of start of string (in pixels) * @y: the y position of baseline (in pixels) diff --git a/pango/pangoft2.c b/pango/pangoft2.c index 2fe49171..efaf853d 100644 --- a/pango/pangoft2.c +++ b/pango/pangoft2.c @@ -20,14 +20,6 @@ * Boston, MA 02111-1307, USA. */ -/** - * SECTION:freetype-fonts - * @short_description:Font handling and rendering with FreeType - * @title:FreeType Fonts and Rendering - * - * The macros and functions in this section are used to access fonts and render - * text to bitmaps using the FreeType 2 library. - */ #include "config.h" #include <string.h> diff --git a/pango/pangoft2.h b/pango/pangoft2.h index 96228316..239eb05e 100644 --- a/pango/pangoft2.h +++ b/pango/pangoft2.h @@ -62,7 +62,7 @@ typedef struct _PangoFT2FontMap PangoFT2FontMap; /** * PangoFT2SubstituteFunc: - * @pattern: the <type>FcPattern</type> to tweak. + * @pattern: the FcPattern to tweak. * @data: user data. * * Function type for doing final config tweaking on prepared FcPatterns. diff --git a/pango/pangowin32-fontmap.c b/pango/pangowin32-fontmap.c index 6bc10a7a..f69ce1f9 100644 --- a/pango/pangowin32-fontmap.c +++ b/pango/pangowin32-fontmap.c @@ -816,7 +816,7 @@ _pango_win32_font_map_class_init (PangoWin32FontMapClass *class) /** * pango_win32_font_map_for_display: * - * Returns a <type>PangoWin32FontMap</type>. Font maps are cached and should + * Returns a PangoWin32FontMap. Font maps are cached and should * not be freed. If the font map is no longer needed, it can * be released with pango_win32_shutdown_display(). * @@ -1800,7 +1800,7 @@ pango_win32_face_list_sizes (PangoFontFace *face, /** * pango_win32_font_map_get_font_cache: - * @font_map: a <type>PangoWin32FontMap</type>. + * @font_map: a PangoWin32FontMap * * Obtains the font cache associated with the given font map. * diff --git a/pango/pangowin32.c b/pango/pangowin32.c index 213a665e..0a90182f 100644 --- a/pango/pangowin32.c +++ b/pango/pangowin32.c @@ -22,14 +22,6 @@ * Boston, MA 02111-1307, USA. */ -/** - * SECTION:win32-fonts - * @short_description:Font handling and rendering on Windows - * @title:Win32 Fonts and Rendering - * - * The macros and functions in this section are used to access fonts natively on - * Win32 systems and to render text in conjunction with Win32 APIs. - */ #include "config.h" #include <string.h> diff --git a/pango/pangoxft-font.c b/pango/pangoxft-font.c index 38198bc0..ac4e6f39 100644 --- a/pango/pangoxft-font.c +++ b/pango/pangoxft-font.c @@ -19,36 +19,6 @@ * Boston, MA 02111-1307, USA. */ -/** - * SECTION:xft-fonts - * @short_description:Font handling and rendering with the Xft backend - * @title:Xft Fonts and Rendering - * - * The Xft library is a library for displaying fonts on the X window - * system; internally it uses the fontconfig library to locate font - * files, and the FreeType library to load and render fonts. The - * Xft backend is the recommended Pango font backend for screen - * display with X. (The <link linkend="pango-Cairo-Rendering">Cairo back end</link> is another possibility.) - * - * Using the Xft backend is generally straightforward; - * pango_xft_get_context() creates a context for a specified display - * and screen. You can then create a #PangoLayout with that context - * and render it with pango_xft_render_layout(). At a more advanced - * level, the low-level fontconfig options used for rendering fonts - * can be affected using pango_xft_set_default_substitute(), and - * pango_xft_substitute_changed(). - * - * A range of functions for drawing pieces of a layout, such as - * individual layout lines and glyphs strings are provided. You can also - * directly create a #PangoXftRenderer. Finally, in some advanced cases, it - * is useful to derive from #PangoXftRenderer. Deriving from - * #PangoXftRenderer is useful for two reasons. One reason is be to - * support custom attributes by overriding #PangoRendererClass virtual - * functions like 'prepare_run' or 'draw_shape'. The reason is to - * customize exactly how the final bits are drawn to the destination by - * overriding the #PangoXftRendererClass virtual functions - * 'composite_glyphs' and 'composite_trapezoids'. - */ #include "config.h" #include <stdlib.h> diff --git a/pango/pangoxft-render.c b/pango/pangoxft-render.c index 2e862dd5..a2584f3c 100644 --- a/pango/pangoxft-render.c +++ b/pango/pangoxft-render.c @@ -828,14 +828,14 @@ pango_xft_render_transformed (XftDraw *draw, /** * pango_xft_render: - * @draw: the <type>XftDraw</type> object. + * @draw: the XftDraw object. * @color: the color in which to draw the string * @font: the font in which to draw the string * @glyphs: the glyph string to draw * @x: the x position of start of string (in pixels) * @y: the y position of baseline (in pixels) * - * Renders a #PangoGlyphString onto an <type>XftDraw</type> object wrapping an X drawable. + * Renders a #PangoGlyphString onto an XftDraw object wrapping an X drawable. */ void pango_xft_render (XftDraw *draw, @@ -864,7 +864,7 @@ pango_xft_render (XftDraw *draw, * @x: the x position of start of string (in pixels) * @y: the y position of baseline (in pixels) * - * Renders a #PangoGlyphString onto an Xrender <type>Picture</type> object. + * Renders a #PangoGlyphString onto an Xrender Picture object. */ void pango_xft_picture_render (Display *display, diff --git a/pango/reorder-items.c b/pango/reorder-items.c index 62a6a8f9..d00fee4c 100644 --- a/pango/reorder-items.c +++ b/pango/reorder-items.c @@ -31,11 +31,13 @@ static GList *reorder_items_recurse (GList *items, int n_items); /** * pango_reorder_items: - * @logical_items: (element-type Pango.Item): a #GList of #PangoItem in logical order. + * @logical_items: (element-type Pango.Item): a `GList` of `PangoItem` + * in logical order. * - * From a list of items in logical order and the associated - * directional levels, produce a list in visual order. - * The original list is unmodified. + * Reorder items from logical order to visual order. + * + * The visual order is determined from the associated directional + * levels of the items. The original list is unmodified. * * Returns: (transfer full) (element-type Pango.Item): a #GList * of #PangoItem structures in visual order. diff --git a/pango/shape.c b/pango/shape.c index 04624b00..1b2986c4 100644 --- a/pango/shape.c +++ b/pango/shape.c @@ -19,16 +19,6 @@ * Boston, MA 02111-1307, USA. */ -/** - * SECTION:glyphs - * @short_description:Structures for storing information about glyphs - * @title:Glyphs - * - * pango_shape() produces a string of glyphs which - * can be measured or drawn to the screen. The following - * structures are used to store information about - * glyphs. - */ #include "config.h" #include "pango-impl-utils.h" @@ -40,23 +30,25 @@ /** * pango_shape: - * @text: the text to process - * @length: the length (in bytes) of @text - * @analysis: #PangoAnalysis structure from pango_itemize() - * @glyphs: glyph string in which to store results + * @text: the text to process + * @length: the length (in bytes) of @text + * @analysis: `PangoAnalysis` structure from [func@itemize] + * @glyphs: glyph string in which to store results * - * Given a segment of text and the corresponding #PangoAnalysis structure - * returned from pango_itemize(), convert the characters into glyphs. You - * may also pass in only a substring of the item from pango_itemize(). + * Convert the characters in @text into glyphs. * - * It is recommended that you use pango_shape_full() instead, since + * Given a segment of text and the corresponding `PangoAnalysis` structure + * returned from [func@itemize], convert the characters into glyphs. You + * may also pass in only a substring of the item from [func@itemize]. + * + * It is recommended that you use [func@shape_full] instead, since * that API allows for shaping interaction happening across text item * boundaries. * * Note that the extra attributes in the @analyis that is returned from - * pango_itemize() have indices that are relative to the entire paragraph, + * [func@itemize] have indices that are relative to the entire paragraph, * so you need to subtract the item offset from their indices before - * calling pango_shape(). + * calling [func@shape]. */ void pango_shape (const gchar *text, @@ -69,28 +61,29 @@ pango_shape (const gchar *text, /** * pango_shape_full: - * @item_text: valid UTF-8 text to shape. - * @item_length: the length (in bytes) of @item_text. -1 means nul-terminated text. + * @item_text: valid UTF-8 text to shape. + * @item_length: the length (in bytes) of @item_text. -1 means nul-terminated text. * @paragraph_text: (allow-none): text of the paragraph (see details). May be %NULL. * @paragraph_length: the length (in bytes) of @paragraph_text. -1 means nul-terminated text. - * @analysis: #PangoAnalysis structure from pango_itemize(). - * @glyphs: glyph string in which to store results. + * @analysis: `PangoAnalysis` structure from [func@itemize]. + * @glyphs: glyph string in which to store results. + * + * Convert the characters in @text into glyphs. * - * Given a segment of text and the corresponding - * #PangoAnalysis structure returned from pango_itemize(), - * convert the characters into glyphs. You may also pass - * in only a substring of the item from pango_itemize(). + * Given a segment of text and the corresponding `PangoAnalysis` structure + * returned from [func@itemize], convert the characters into glyphs. You may + * also pass in only a substring of the item from [func@itemize]. * - * This is similar to pango_shape(), except it also can optionally take + * This is similar to [func@shape], except it also can optionally take * the full paragraph text as input, which will then be used to perform - * certain cross-item shaping interactions. If you have access to the broader + * certain cross-item shaping interactions. If you have access to the broader * text of which @item_text is part of, provide the broader text as - * @paragraph_text. If @paragraph_text is %NULL, item text is used instead. + * @paragraph_text. If @paragraph_text is %NULL, item text is used instead. * * Note that the extra attributes in the @analyis that is returned from - * pango_itemize() have indices that are relative to the entire paragraph, + * [func@itemize] have indices that are relative to the entire paragraph, * so you do not pass the full paragraph text as @paragraph_text, you need - * to subtract the item offset from their indices before calling pango_shape_full(). + * to subtract the item offset from their indices before calling [func@shape_full]. * * Since: 1.32 */ @@ -167,23 +160,24 @@ fallback_shape (const char *text, * May be %NULL. * @paragraph_length: the length (in bytes) of @paragraph_text. * -1 means nul-terminated text. - * @analysis: #PangoAnalysis structure from pango_itemize() + * @analysis: `PangoAnalysis` structure from [func@itemize] * @glyphs: glyph string in which to store results * @flags: flags influencing the shaping process * - * Given a segment of text and the corresponding - * #PangoAnalysis structure returned from pango_itemize(), - * convert the characters into glyphs. You may also pass - * in only a substring of the item from pango_itemize(). + * Convert the characters in @text into glyphs. + * + * Given a segment of text and the corresponding `PangoAnalysis` structure + * returned from [func@itemize], convert the characters into glyphs. You may + * also pass in only a substring of the item from [func@itemize]. * - * This is similar to pango_shape_full(), except it also takes - * flags that can influence the shaping process. + * This is similar to [func@shape_full], except it also takes flags that can + * influence the shaping process. * * Note that the extra attributes in the @analyis that is returned from - * pango_itemize() have indices that are relative to the entire paragraph, + * [func@itemize] have indices that are relative to the entire paragraph, * so you do not pass the full paragraph text as @paragraph_text, you need * to subtract the item offset from their indices before calling - * pango_shape_with_flags(). + * [func@shape_with_flags]. * * Since: 1.44 */ |