Pango.GlyphString

Fields

Name

Type

Access

Description

glyphs

[Pango.GlyphInfo]

r/w

array of glyph information

log_clusters

int

r/w

logical cluster info, indexed by the byte index within the text corresponding to the glyph string

num_glyphs

int

r/w

number of glyphs in this glyph string

space

int

r

Methods

class

new ()

copy ()

extents (font)

extents_range (start, end, font)

free ()

get_logical_widths (text, length, embedding_level, logical_widths)

get_width ()

index_to_x (text, length, analysis, index_, trailing)

index_to_x_full (text, length, analysis, attrs, index_, trailing)

set_size (new_len)

x_to_index (text, length, analysis, x_pos)

Details

class Pango.GlyphString

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.

classmethod new()[source]
Returns:

the newly allocated PangoGlyphString, which should be freed with [method`Pango`.GlyphString.free].

Return type:

Pango.GlyphString

Create a new PangoGlyphString.

copy()[source]
Returns:

the newly allocated PangoGlyphString

Return type:

Pango.GlyphString or None

Copy a glyph string and associated storage.

extents(font)[source]
Parameters:

font (Pango.Font) – a PangoFont

Returns:

ink_rect:

rectangle used to store the extents of the glyph string as drawn

logical_rect:

rectangle used to store the logical extents of the glyph string

Return type:

(ink_rect: Pango.Rectangle, logical_rect: Pango.Rectangle)

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:

extents_range(start, end, font)[source]
Parameters:

  • start (int) – start index

  • end (int) – end index (the range is the set of bytes with indices such that start <= index < end)

  • font (Pango.Font) – a PangoFont

Returns:

ink_rect:

rectangle used to store the extents of the glyph string range as drawn

logical_rect:

rectangle used to store the logical extents of the glyph string range

Return type:

(ink_rect: Pango.Rectangle, logical_rect: Pango.Rectangle)

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).

free()[source]

Free a glyph string and associated storage.

get_logical_widths(text, length, embedding_level, logical_widths)[source]
Parameters:

  • text (str) – the text corresponding to the glyphs

  • length (int) – the length of text, in bytes

  • embedding_level (int) – the embedding level of the string

  • logical_widths ([int]) – an array whose length is the number of characters in text (equal to g_utf8_strlen (text, length) unless text has NUL bytes) to be filled in with the resulting character widths.

Given a PangoGlyphString and 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 [method`Pango`.GlyphItem.get_logical_widths].

get_width()[source]
Returns:

the logical width of the glyph string.

Return type:

int

Computes the logical width of the glyph string.

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 self.

New in version 1.14.

index_to_x(text, length, analysis, index_, trailing)[source]
Parameters:

  • text (str) – the text for the run

  • length (int) – the number of bytes (not characters) in text.

  • analysis (Pango.Analysis) – the analysis information return from [func`itemize`]

  • index (int) – the byte index within text

  • trailing (bool) – whether we should compute the result for the beginning (False) or end (True) of the character.

Returns:

location to store result

Return type:

x_pos: int

Converts from character position to x position.

The X position is measured from the left edge of the run. Character positions are obtained using font metrics for ligatures where available, and computed by dividing up each cluster into equal portions, otherwise.

<picture> <source srcset=”glyphstring-positions-dark.png” media=”(prefers-color-scheme: dark)”> <img alt=”Glyph positions” src=”glyphstring-positions-light.png”> </picture>

index_to_x_full(text, length, analysis, attrs, index_, trailing)[source]
Parameters:

  • text (str) – the text for the run

  • length (int) – the number of bytes (not characters) in text.

  • analysis (Pango.Analysis) – the analysis information return from [func`itemize`]

  • attrs (Pango.LogAttr or None) – PangoLogAttr array for text

  • index (int) – the byte index within text

  • trailing (bool) – whether we should compute the result for the beginning (False) or end (True) of the character.

Returns:

location to store result

Return type:

x_pos: int

Converts from character position to x position.

This variant of [method`Pango`.GlyphString.index_to_x] additionally accepts a PangoLogAttr array. The grapheme boundary information in it can be used to disambiguate positioning inside some complex clusters.

New in version 1.50.

set_size(new_len)[source]
Parameters:

new_len (int) – the new length of the string

Resize a glyph string to the given length.

x_to_index(text, length, analysis, x_pos)[source]
Parameters:

  • text (str) – the text for the run

  • length (int) – the number of bytes (not characters) in text.

  • analysis (Pango.Analysis) – the analysis information return from [func`itemize`]

  • x_pos (int) – the x offset (in Pango units)

Returns:

index_:

location to store calculated byte index within text

trailing:

location to store a boolean indicating whether the user clicked on the leading or trailing edge of the character

Return type:

(index_: int, trailing: int)

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.