summaryrefslogtreecommitdiff
path: root/pango
diff options
context:
space:
mode:
Diffstat (limited to 'pango')
-rw-r--r--pango/break.c51
-rw-r--r--pango/fonts.c1177
-rw-r--r--pango/glyphstring.c96
-rw-r--r--pango/modules.c13
-rw-r--r--pango/pango-attributes.c851
-rw-r--r--pango/pango-attributes.h203
-rw-r--r--pango/pango-bidi-type.c57
-rw-r--r--pango/pango-bidi-type.h2
-rw-r--r--pango/pango-break.h63
-rw-r--r--pango/pango-color.c77
-rw-r--r--pango/pango-context.c687
-rw-r--r--pango/pango-coverage.c50
-rw-r--r--pango/pango-coverage.h13
-rw-r--r--pango/pango-direction.h33
-rw-r--r--pango/pango-engine.c38
-rw-r--r--pango/pango-engine.h45
-rw-r--r--pango/pango-font.h214
-rw-r--r--pango/pango-fontmap.c193
-rw-r--r--pango/pango-fontmap.h14
-rw-r--r--pango/pango-fontset.c28
-rw-r--r--pango/pango-fontset.h27
-rw-r--r--pango/pango-glyph-item.c90
-rw-r--r--pango/pango-glyph-item.h62
-rw-r--r--pango/pango-glyph.h44
-rw-r--r--pango/pango-gravity.c88
-rw-r--r--pango/pango-gravity.h30
-rw-r--r--pango/pango-item.c78
-rw-r--r--pango/pango-item.h25
-rw-r--r--pango/pango-language.c186
-rw-r--r--pango/pango-layout.c3674
-rw-r--r--pango/pango-layout.h42
-rw-r--r--pango/pango-markup.c238
-rw-r--r--pango/pango-matrix.c88
-rw-r--r--pango/pango-matrix.h19
-rw-r--r--pango/pango-modules.h7
-rw-r--r--pango/pango-ot-info.c14
-rw-r--r--pango/pango-ot-private.h4
-rw-r--r--pango/pango-ot-ruleset.c22
-rw-r--r--pango/pango-ot.h8
-rw-r--r--pango/pango-renderer.c787
-rw-r--r--pango/pango-renderer.h11
-rw-r--r--pango/pango-script.c22
-rw-r--r--pango/pango-script.h16
-rw-r--r--pango/pango-tabs.c160
-rw-r--r--pango/pango-tabs.h7
-rw-r--r--pango/pango-types.h29
-rw-r--r--pango/pango-utils.c128
-rw-r--r--pango/pangocairo-context.c133
-rw-r--r--pango/pangocairo-font.c14
-rw-r--r--pango/pangocairo-fontmap.c107
-rw-r--r--pango/pangocairo-render.c207
-rw-r--r--pango/pangocairo.h16
-rw-r--r--pango/pangocoretext.c8
-rw-r--r--pango/pangofc-decoder.c34
-rw-r--r--pango/pangofc-decoder.h21
-rw-r--r--pango/pangofc-font.c95
-rw-r--r--pango/pangofc-font.h15
-rw-r--r--pango/pangofc-fontmap.c220
-rw-r--r--pango/pangofc-fontmap.h83
-rw-r--r--pango/pangoft2-fontmap.c48
-rw-r--r--pango/pangoft2-render.c19
-rw-r--r--pango/pangoft2.c8
-rw-r--r--pango/pangoft2.h2
-rw-r--r--pango/pangowin32-fontmap.c4
-rw-r--r--pango/pangowin32.c8
-rw-r--r--pango/pangoxft-font.c30
-rw-r--r--pango/pangoxft-render.c6
-rw-r--r--pango/reorder-items.c10
-rw-r--r--pango/shape.c78
69 files changed, 5270 insertions, 5707 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 8f23fe77..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,29 +1741,30 @@ pango_attr_list_update (PangoAttrList *list,
/**
* pango_attr_list_splice:
- * @list: a #PangoAttrList
- * @other: another #PangoAttrList
+ * @list: a `PangoAttrList`
+ * @other: another `PangoAttrList`
* @pos: the position in @list at which to insert @other
* @len: the length of the spliced segment. (Note that this
- * must be specified since the attributes in @other
- * may only be present at some subsection of this range)
+ * must be specified since the attributes in @other may only
+ * be present at some subsection of this range)
*
- * This function opens up a hole in @list, fills it in with attributes from
- * the left, and then merges @other on top of the hole.
+ * This function opens up a hole in @list, fills it in with attributes
+ * from the left, and then merges @other on top of the hole.
*
* This operation is equivalent to stretching every attribute
* that applies at position @pos in @list by an amount @len,
- * and then calling pango_attr_list_change() with a copy
- * of each attribute in @other in sequence (offset in position by @pos).
+ * and then calling [method@Pango.AttrList.change] with a copy
+ * of each attribute in @other in sequence (offset in position
+ * by @pos).
*
* This operation proves useful for, for instance, inserting
* a pre-edit string in the middle of an edit buffer.
- **/
+ */
void
pango_attr_list_splice (PangoAttrList *list,
- PangoAttrList *other,
- gint pos,
- gint len)
+ PangoAttrList *other,
+ gint pos,
+ gint len)
{
guint i, p;
guint upos, ulen;
@@ -1827,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
@@ -1861,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
@@ -1956,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)
@@ -1985,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);
@@ -2004,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)
{
@@ -2074,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)
{
@@ -2110,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)
{
@@ -2125,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;
@@ -2161,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;
@@ -2208,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)
@@ -2308,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)
@@ -2325,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;
@@ -2378,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)
{
@@ -2407,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>&num;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 '&num;rgb' '&num;rrggbb' '&num;rrrgggbbb' or '&num;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 '&num;fff' '&num;ffffff' '&num;fffffffff' and '&num;ffffffffffff')
+ * Fill in the fields of a color from a string specification.
*
- * Additionally, parse strings of the form
- * '&num;rgba', '&num;rrggbbaa', '&num;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 '&num;rgb' '&num;rrggbb' '&num;rrrgggbbb' or '&num;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 '&num;fff' '&num;ffffff' '&num;fffffffff' and '&num;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.
- *
- * ![](pipeline.png)
- */
#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 (&amp;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 (&amp;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):
+ *
+ * ![Pango Layout Parameters](layout.png)
+ *
+ * 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 d0b47016..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 `&#169;` 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
@@ -790,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
@@ -810,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.
@@ -872,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
@@ -913,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 (&amp;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;
- *
- * /&ast; Center coordinates on the middle of the region we are drawing
- * &ast;/
- * cairo_translate (cr, RADIUS, RADIUS);
- *
- * /&ast; Create a PangoLayout, set the font and text &ast;/
- * 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);
- *
- * /&ast; Draw the layout N_WORDS times in a circle &ast;/
- * for (i = 0; i &lt; N_WORDS; i++)
- * {
- * int width, height;
- * double angle = (360. * i) / N_WORDS;
- * double red;
- *
- * cairo_save (cr);
- *
- * /&ast; Gradient from red at angle == 60 to blue at angle == 240 &ast;/
- * 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.);
- *
- * /&ast; Inform Pango to re-layout the text with the new transformation &ast;/
- * pango_cairo_update_layout (cr, layout);
- *
- * pango_layout_get_size (layout, &amp;width, &amp;height);
- * cairo_move_to (cr, - ((double)width / PANGO_SCALE) / 2, - RADIUS);
- * pango_cairo_show_layout (cr, layout);
- *
- * cairo_restore (cr);
- * }
- *
- * /&ast; free the layout object &ast;/
- * 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:
- *
- * ![Output of rotated-example](rotated-text.png)
- */
#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
*/