Functions#

attr_allow_breaks_new(allow_breaks: bool) → Attribute#

Create a new allow-breaks attribute.

If breaks are disabled, the range will be kept in a single run, as far as possible.

Added in version 1.44.

Parameters:: allow_breaks – True if we line breaks are allowed
Returns:: the newly allocated PangoAttribute, which should be freed with destroy

attr_background_alpha_new(alpha: int) → Attribute#

Create a new background alpha attribute.

Added in version 1.38.

Parameters:: alpha – the alpha value, between 1 and 65536
Returns:: the newly allocated PangoAttribute, which should be freed with destroy

attr_background_new(red: int, green: int, blue: int) → Attribute#

Create a new background color attribute.

Parameters:

red – the red value (ranging from 0 to 65535)
green – the green value
blue – the blue value

Returns:

the newly allocated PangoAttribute, which should be freed with destroy

attr_baseline_shift_new(shift: int) → Attribute#

Create a new baseline displacement attribute.

The effect of this attribute is to shift the baseline of a run, relative to the run of preceding run.

https://docs.gtk.org/Pango/baseline-shift-light.png

Added in version 1.50.

Parameters:: shift – either a PangoBaselineShift enumeration value or an absolute value (> 1024) in Pango units, relative to the baseline of the previous run. Positive values displace the text upwards.
Returns:: the newly allocated PangoAttribute, which should be freed with destroy

attr_break(text: str, length: int, attr_list: AttrList, offset: int) → list[LogAttr]#

Apply customization from attributes to the breaks in attrs.

The line breaks are assumed to have been produced by default_break and tailor_break.

Added in version 1.50.

Parameters:

text – text to break. Must be valid UTF-8
length – length of text in bytes (may be -1 if text is nul-terminated)
attr_list – PangoAttrList to apply
offset – Byte offset of text from the beginning of the paragraph

attr_fallback_new(enable_fallback: bool) → Attribute#

Create a new font fallback attribute.

If fallback is disabled, 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.

Added in version 1.4.

Parameters:: enable_fallback – True if we should fall back on other fonts for characters the active font is missing
Returns:: the newly allocated PangoAttribute, which should be freed with destroy

attr_family_new(family: str) → Attribute#

Create a new font family attribute.

Parameters:: family – the family or comma-separated list of families
Returns:: the newly allocated PangoAttribute, which should be freed with destroy

attr_font_desc_new(desc: FontDescription) → Attribute#

Parameters:: desc

attr_font_features_new(features: str) → Attribute#

Parameters:: features

attr_font_scale_new(scale: FontScale) → Attribute#

Create a new font scale attribute.

The effect of this attribute is to change the font size of a run, relative to the size of preceding run.

Added in version 1.50.

Parameters:: scale – a PangoFontScale value, which indicates font size change relative to the size of the previous run.
Returns:: the newly allocated PangoAttribute, which should be freed with destroy

attr_foreground_alpha_new(alpha: int) → Attribute#

Create a new foreground alpha attribute.

Added in version 1.38.

Parameters:: alpha – the alpha value, between 1 and 65536
Returns:: the newly allocated PangoAttribute, which should be freed with destroy

attr_foreground_new(red: int, green: int, blue: int) → Attribute#

Create a new foreground color attribute.

Parameters:

red – the red value (ranging from 0 to 65535)
green – the green value
blue – the blue value

Returns:

the newly allocated PangoAttribute, which should be freed with destroy

attr_gravity_hint_new(hint: GravityHint) → Attribute#

Create a new gravity hint attribute.

Added in version 1.16.

Parameters:: hint – the gravity hint value
Returns:: the newly allocated PangoAttribute, which should be freed with destroy

attr_gravity_new(gravity: Gravity) → Attribute#

Create a new gravity attribute.

Added in version 1.16.

Parameters:: gravity – the gravity value; should not be AUTO
Returns:: the newly allocated PangoAttribute, which should be freed with destroy

attr_insert_hyphens_new(insert_hyphens: bool) → Attribute#

Create a new insert-hyphens attribute.

Pango will insert hyphens when breaking lines in the middle of a word. This attribute can be used to suppress the hyphen.

Added in version 1.44.

Parameters:: insert_hyphens – True if hyphens should be inserted
Returns:: the newly allocated PangoAttribute, which should be freed with destroy

attr_language_new(language: Language) → Attribute#

Parameters:: language

attr_letter_spacing_new(letter_spacing: int) → Attribute#

Create a new letter-spacing attribute.

Added in version 1.6.

Parameters:: letter_spacing – amount of extra space to add between graphemes of the text, in Pango units
Returns:: the newly allocated PangoAttribute, which should be freed with destroy

attr_line_height_new(factor: float) → Attribute#

Modify the height of logical line extents by a factor.

This affects the values returned by get_extents, get_pixel_extents and get_line_extents.

Added in version 1.50.

Parameters:: factor – the scaling factor to apply to the logical height

attr_line_height_new_absolute(height: int) → Attribute#

Override the height of logical line extents to be height.

This affects the values returned by get_extents, get_pixel_extents and get_line_extents.

Added in version 1.50.

Parameters:: height – the line height, in SCALE-ths of a point

attr_list_from_string(text: str) → AttrList | None#

Parameters:: text

attr_overline_color_new(red: int, green: int, blue: int) → Attribute#

Create a new overline color attribute.

This attribute modifies the color of overlines. If not set, overlines will use the foreground color.

Added in version 1.46.

Parameters:

red – the red value (ranging from 0 to 65535)
green – the green value
blue – the blue value

Returns:

the newly allocated PangoAttribute, which should be freed with destroy

attr_overline_new(overline: Overline) → Attribute#

Create a new overline-style attribute.

Added in version 1.46.

Parameters:: overline – the overline style
Returns:: the newly allocated PangoAttribute, which should be freed with destroy

attr_rise_new(rise: int) → Attribute#

Create a new baseline displacement attribute.

Parameters:: rise – the amount that the text should be displaced vertically, in Pango units. Positive values displace the text upwards.
Returns:: the newly allocated PangoAttribute, which should be freed with destroy

attr_scale_new(scale_factor: float) → Attribute#

Create a new font size scale attribute.

The base font for the affected text will have its size multiplied by scale_factor.

Parameters:: scale_factor – factor to scale the font
Returns:: the newly allocated PangoAttribute, which should be freed with destroy

attr_sentence_new() → Attribute#

Marks the range of the attribute as a single sentence.

Note that this may require adjustments to word and sentence classification around the range.

Added in version 1.50.

Returns:: the newly allocated PangoAttribute, which should be freed with destroy

attr_shape_new(ink_rect: Rectangle, logical_rect: Rectangle) → Attribute#

Parameters:

ink_rect
logical_rect

attr_shape_new_with_data(ink_rect: Rectangle, logical_rect: Rectangle, data: Any = None, copy_func: Callable[[Any], Any | None] | None = None) → Attribute#

Parameters:

ink_rect
logical_rect
data
copy_func

attr_show_new(flags: ShowFlags) → Attribute#

Create a new attribute that influences how invisible characters are rendered.

Added in version 1.44.

Parameters:: flags – PangoShowFlags to apply
Returns:: the newly allocated PangoAttribute, which should be freed with destroy

attr_size_new(size: int) → Attribute#

Parameters:: size

attr_size_new_absolute(size: int) → Attribute#

Parameters:: size

attr_stretch_new(stretch: Stretch) → Attribute#

Create a new font stretch attribute.

Parameters:: stretch – the stretch
Returns:: the newly allocated PangoAttribute, which should be freed with destroy

attr_strikethrough_color_new(red: int, green: int, blue: int) → Attribute#

Create a new strikethrough color attribute.

This attribute modifies the color of strikethrough lines. If not set, strikethrough lines will use the foreground color.

Added in version 1.8.

Parameters:

red – the red value (ranging from 0 to 65535)
green – the green value
blue – the blue value

Returns:

the newly allocated PangoAttribute, which should be freed with destroy

attr_strikethrough_new(strikethrough: bool) → Attribute#

Create a new strike-through attribute.

Parameters:: strikethrough – True if the text should be struck-through
Returns:: the newly allocated PangoAttribute, which should be freed with destroy

attr_style_new(style: Style) → Attribute#

Create a new font slant style attribute.

Parameters:: style – the slant style
Returns:: the newly allocated PangoAttribute, which should be freed with destroy

attr_text_transform_new(transform: TextTransform) → Attribute#

Create a new attribute that influences how characters are transformed during shaping.

Added in version 1.50.

Parameters:: transform – PangoTextTransform to apply
Returns:: the newly allocated PangoAttribute, which should be freed with destroy

attr_type_get_name(type: AttrType) → str | None#

Parameters:: type

attr_type_register(name: str) → AttrType#

Parameters:: name

attr_underline_color_new(red: int, green: int, blue: int) → Attribute#

Create a new underline color attribute.

This attribute modifies the color of underlines. If not set, underlines will use the foreground color.

Added in version 1.8.

Parameters:

red – the red value (ranging from 0 to 65535)
green – the green value
blue – the blue value

Returns:

the newly allocated PangoAttribute, which should be freed with destroy

attr_underline_new(underline: Underline) → Attribute#

Create a new underline-style attribute.

Parameters:: underline – the underline style
Returns:: the newly allocated PangoAttribute, which should be freed with destroy

attr_variant_new(variant: Variant) → Attribute#

Create a new font variant attribute (normal or small caps).

Parameters:: variant – the variant
Returns:: the newly allocated PangoAttribute, which should be freed with destroy.

attr_weight_new(weight: Weight) → Attribute#

Create a new font weight attribute.

Parameters:: weight – the weight
Returns:: the newly allocated PangoAttribute, which should be freed with destroy

attr_word_new() → Attribute#

Marks the range of the attribute as a single word.

Note that this may require adjustments to word and sentence classification around the range.

Added in version 1.50.

Returns:: the newly allocated PangoAttribute, which should be freed with destroy

bidi_type_for_unichar(ch: str) → BidiType#

Parameters:: ch

break_(text: str, length: int, analysis: Analysis) → list[LogAttr]#

Parameters:

text
length
analysis

default_break(text: str, length: int, analysis: Analysis | None = None) → list[LogAttr]#

This is the default break algorithm.

It applies rules from the Unicode Line Breaking Algorithm without language-specific tailoring, therefore the analyis argument is unused and can be None.

See tailor_break for language-specific breaks.

See attr_break for attribute-based customization.

Parameters:

text – text to break. Must be valid UTF-8
length – length of text in bytes (may be -1 if text is nul-terminated)
analysis – a PangoAnalysis structure for the text

extents_to_pixels(inclusive: Rectangle | None = None, nearest: Rectangle | None = None) → None#

Converts extents from Pango units to device units.

The conversion is done by dividing by the 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 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 touching-but-not-overlapping after rounding to device units, pass them in as nearest.

Added in version 1.16.

Parameters:

inclusive – rectangle to round to pixels inclusively
nearest – rectangle to round to nearest pixels

find_base_dir(text: str, length: int) → Direction#

Searches a string the first character that has a strong direction, according to the Unicode bidirectional algorithm.

Added in version 1.4.

Parameters:

text – the text to process. Must be valid UTF-8
length – length of text in bytes (may be -1 if text is nul-terminated)

Returns:

The direction corresponding to the first strong character. If no such character is found, then NEUTRAL is returned.

find_paragraph_boundary(text: str, length: int) → tuple[int, int]#

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 next paragraph (index after all delimiters) is stored n 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).

Parameters:

text – UTF-8 text
length – length of text in bytes, or -1 if nul-terminated

font_description_from_string(str: str) → FontDescription#

Parameters:: str

get_log_attrs(text: str, length: int, level: int, language: Language) → list[LogAttr]#

Computes a PangoLogAttr for each character in text.

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

Parameters:

text – text to process. Must be valid UTF-8
length – length in bytes of text
level – embedding level, or -1 if unknown
language – language tag

get_mirror_char(ch: str) → tuple[bool, str]#

Returns the mirrored character of a Unicode character.

Mirror characters are determined by the Unicode mirrored property.

Deprecated since version 1.30: Use unichar_get_mirror_char instead; the docs for that function provide full details.

Parameters:: ch – a Unicode character
Returns:: True if ch has a mirrored character and mirrored_ch is filled in, False otherwise

gravity_get_for_matrix(matrix: Matrix | None = None) → Gravity#

Parameters:: matrix

gravity_get_for_script(script: Script, base_gravity: Gravity, hint: GravityHint) → Gravity#

Parameters:

script
base_gravity
hint

gravity_get_for_script_and_width(script: Script, wide: bool, base_gravity: Gravity, hint: GravityHint) → Gravity#

Parameters:

script
wide
base_gravity
hint

gravity_to_rotation(gravity: Gravity) → float#

Parameters:: gravity

is_zero_width(ch: str) → bool#

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 unichar_iszerowidth and is at best misnamed.

Added in version 1.10.

Parameters:: ch – a Unicode character
Returns:: True if ch is a zero-width character, False otherwise

itemize(context: Context, text: str, start_index: int, length: int, attrs: AttrList, cached_iter: AttrIterator | None = None) → list[Item]#

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

Parameters:

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.
cached_iter – Cached attribute iterator

Returns:

a GList of Item structures. The items should be freed using free in combination with free_full.

itemize_with_base_dir(context: Context, base_dir: Direction, text: str, start_index: int, length: int, attrs: AttrList, cached_iter: AttrIterator | None = None) → list[Item]#

Like pango_itemize(), but with an explicitly specified base direction.

The base direction is used when computing bidirectional levels. itemize gets the base direction from the PangoContext (see set_base_dir).

Added in version 1.4.

Parameters:

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.
cached_iter – Cached attribute iterator

Returns:

a GList of Item structures. The items should be freed using free probably in combination with free_full.

language_from_string(language: str | None = None) → Language | None#

Parameters:: language

language_get_default() → Language#

language_get_preferred() → list[Language] | None#

layout_deserialize_error_quark() → int#

log2vis_get_embedding_levels(text: str, length: int, pbase_dir: Direction) → tuple[list[int], Direction]#

Return the bidirectional embedding levels of the input paragraph.

The bidirectional embedding levels are defined by the Unicode Bidirectional Algorithm.

If the input base direction is a weak direction, the direction of the characters in the text will determine the final resolved direction.

Added in version 1.4.

Parameters:

text – the text to itemize.
length – the number of bytes (not characters) to process, or -1 if text is nul-terminated and the length should be calculated.
pbase_dir – input base direction, and output resolved direction.

Returns:

a newly allocated array of embedding levels, one item per character (not byte), that should be freed using free.

markup_parser_finish(context: MarkupParseContext) → tuple[bool, AttrList, str, str]#

Finishes parsing markup.

After feeding a Pango markup parser some data with parse, use this function to get the list of attributes and text out of the markup. This function will not free context, use free to do so.

Added in version 1.31.0.

Parameters:: context – A valid parse context that was returned from markup_parser_new
Returns:: False if error is set, otherwise True

markup_parser_new(accel_marker: str) → MarkupParseContext#

Incrementally parses marked-up text to create a plain-text string and an attribute list.

See the Pango Markup 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 LOW attribute, and the first character so marked will be returned in accel_char, when calling markup_parser_finish. Two accel_marker characters following each other produce a single literal accel_marker character.

To feed markup to the parser, use parse on the returned MarkupParseContext. When done with feeding markup to the parser, use markup_parser_finish to get the data out of it, and then use 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 parse_markup API is recommended instead.

Added in version 1.31.0.

Parameters:: accel_marker – character that precedes an accelerator, or 0 for none
Returns:: a GMarkupParseContext that should be destroyed with free.

parse_enum(type: GType, str: str | None, warn: bool) → tuple[bool, int, str]#

Parses an enum type and stores the result in value.

If str does not match the nick name of any of the possible values for the enum and is not an integer, False is returned, a warning is issued if warn is True, and a string representing the list of possible values is stored in possible_values. The list is slash-separated, eg. “none/start/middle/end”.

If failed and possible_values is not None, returned string should be freed using free().

Added in version 1.16.

Deprecated since version 1.38: Please do not use it in newly written code

Parameters:

type – enum type to parse, eg. %PANGO_TYPE_ELLIPSIZE_MODE
str – string to parse
warn – if True, issue a warning() on bad input

Returns:

True if str was successfully parsed

parse_markup(markup_text: str, length: int, accel_marker: str) → tuple[bool, AttrList, str, str]#

Parses marked-up text to create a plain-text string and an attribute list.

See the Pango Markup 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 LOW attribute, 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.

To parse a stream of pango markup incrementally, use markup_parser_new.

If any error happens, none of the output arguments are touched except for error.

Parameters:

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

Returns:

False if error is set, otherwise True

parse_stretch(str: str, warn: bool) → tuple[bool, Stretch]#

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.

Parameters:

str – a string to parse.
warn – if True, issue a warning() on bad input.

Returns:

True if str was successfully parsed.

parse_style(str: str, warn: bool) → tuple[bool, Style]#

Parses a font style.

The allowed values are “normal”, “italic” and “oblique”, case variations being ignored.

Parameters:

str – a string to parse.
warn – if True, issue a warning() on bad input.

Returns:

True if str was successfully parsed.

parse_variant(str: str, warn: bool) → tuple[bool, Variant]#

Parses a font variant.

The allowed values are “normal”, “small-caps”, “all-small-caps”, “petite-caps”, “all-petite-caps”, “unicase” and “title-caps”, case variations being ignored.

Parameters:

str – a string to parse.
warn – if True, issue a warning() on bad input.

Returns:

True if str was successfully parsed.

parse_weight(str: str, warn: bool) → tuple[bool, Weight]#

Parses a font weight.

The allowed values are “heavy”, “ultrabold”, “bold”, “normal”, “light”, “ultraleight” and integers. Case variations are ignored.

Parameters:

str – a string to parse.
warn – if True, issue a warning() on bad input.

Returns:

True if str was successfully parsed.

quantize_line_geometry(thickness: int, position: int) → tuple[int, int]#

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 of rounding.

Added in version 1.12.

Parameters:

thickness – pointer to the thickness of a line, in Pango units
position – corresponding position

read_line(stream: Any, str: String) → int#

Reads an entire line from a file into a buffer.

Lines may be delimited with ‘n’, ‘r’, ‘nr’, or ‘rn’. 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.

Deprecated since version 1.38: Please do not use it in newly written code

Parameters:

stream – a stdio stream
str – GString buffer into which to write the result

Returns:

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 ‘')

reorder_items(items: list[Item]) → list[Item]#

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.

(Please open a bug if you use this function.: It is not a particularly convenient interface, and the code is duplicated elsewhere in Pango for that reason.)

Parameters:: items – a GList of PangoItem in logical order.
Returns:: a GList of PangoItem structures in visual order.

scan_int(pos: str) → tuple[bool, str, int]#

Scans an integer.

Leading white space is skipped.

Deprecated since version 1.38: Please do not use it in newly written code

Parameters:: pos – in/out string position
Returns:: False if a parse error occurred

scan_string(pos: str, out: String) → tuple[bool, str]#

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.

Deprecated since version 1.38: Please do not use it in newly written code

Parameters:

pos – in/out string position
out – a GString into which to write the result

Returns:

False if a parse error occurred

scan_word(pos: str, out: String) → tuple[bool, str]#

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.

Deprecated since version 1.38: Please do not use it in newly written code

Parameters:

pos – in/out string position
out – a GString into which to write the result

Returns:

False if a parse error occurred

script_for_unichar(ch: str) → Script#

Parameters:: ch

script_get_sample_language(script: Script) → Language | None#

Parameters:: script

shape(text: str, length: int, analysis: Analysis) → GlyphString#

Convert the characters in text into glyphs.

Given a segment of text and the corresponding PangoAnalysis structure returned from itemize, convert the characters into glyphs. You may also pass in only a substring of the item from itemize.

It is recommended that you use shape_full instead, since that API allows for shaping interaction happening across text item boundaries.

Some aspects of hyphen insertion and text transformation (in particular, capitalization) require log attrs, and thus can only be handled by shape_item.

Note that the extra attributes in the analyis that is returned from itemize have indices that are relative to the entire paragraph, so you need to subtract the item offset from their indices before calling shape.

Parameters:

text – the text to process
length – the length (in bytes) of text
analysis – PangoAnalysis structure from itemize

shape_full(item_text: str, item_length: int, paragraph_text: str | None, paragraph_length: int, analysis: Analysis) → GlyphString#

Convert the characters in text into glyphs.

Given a segment of text and the corresponding PangoAnalysis structure returned from itemize, convert the characters into glyphs. You may also pass in only a substring of the item from itemize.

This is similar to 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 text of which item_text is part of, provide the broader text as paragraph_text. If paragraph_text is None, item text is used instead.

Some aspects of hyphen insertion and text transformation (in particular, capitalization) require log attrs, and thus can only be handled by shape_item.

Note that the extra attributes in the analyis that is returned from 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 shape_full.

Added in version 1.32.

Parameters:

item_text – valid UTF-8 text to shape.
item_length – the length (in bytes) of item_text. -1 means nul-terminated text.
paragraph_text – text of the paragraph (see details).
paragraph_length – the length (in bytes) of paragraph_text. -1 means nul-terminated text.
analysis – PangoAnalysis structure from itemize.

shape_item(item: Item, paragraph_text: str | None, paragraph_length: int, log_attrs: LogAttr | None, flags: ShapeFlags) → GlyphString#

Convert the characters in item into glyphs.

This is similar to shape_with_flags, except it takes a PangoItem instead of separate item_text and analysis arguments.

It also takes log_attrs, which are needed for implementing some aspects of hyphen insertion and text transforms (in particular, capitalization).

Added in version 1.50.

Parameters:

item – PangoItem to shape
paragraph_text – text of the paragraph (see details).
paragraph_length – the length (in bytes) of paragraph_text. -1 means nul-terminated text.
log_attrs – array of PangoLogAttr for item
flags – flags influencing the shaping process

shape_with_flags(item_text: str, item_length: int, paragraph_text: str | None, paragraph_length: int, analysis: Analysis, flags: ShapeFlags) → GlyphString#

Convert the characters in text into glyphs.

Given a segment of text and the corresponding PangoAnalysis structure returned from itemize, convert the characters into glyphs. You may also pass in only a substring of the item from itemize.

This is similar to shape_full, except it also takes flags that can influence the shaping process.

Some aspects of hyphen insertion and text transformation (in particular, capitalization) require log attrs, and thus can only be handled by shape_item.

Added in version 1.44.

Parameters:

item_text – valid UTF-8 text to shape
item_length – the length (in bytes) of item_text. -1 means nul-terminated text.
paragraph_text – text of the paragraph (see details).
paragraph_length – the length (in bytes) of paragraph_text. -1 means nul-terminated text.
analysis – PangoAnalysis structure from itemize
flags – flags influencing the shaping process

skip_space(pos: str) → tuple[bool, str]#

Skips 0 or more characters of white space.

Deprecated since version 1.38: Please do not use it in newly written code

Parameters:: pos – in/out string position
Returns:: False if skipping the white space leaves the position at a ‘0’ character.

split_file_list(str: str) → list[str]#

Splits a %G_SEARCHPATH_SEPARATOR-separated list of files, stripping white space and substituting ~/ with $HOME/.

Deprecated since version 1.38: Please do not use it in newly written code

Parameters:: str – a %G_SEARCHPATH_SEPARATOR separated list of filenames
Returns:: a list of strings to be freed with strfreev()

tab_array_from_string(text: str) → TabArray | None#

Parameters:: text

tailor_break(text: str, length: int, analysis: Analysis, offset: int) → list[LogAttr]#

Apply language-specific tailoring to the breaks in attrs.

The line breaks are assumed to have been produced by default_break.

If offset is not -1, it is used to apply attributes from analysis that are relevant to line breaking.

Note that it is better to pass -1 for offset and use attr_break to apply attributes to the whole paragraph.

Added in version 1.44.

Parameters:

text – text to process. Must be valid UTF-8
length – length in bytes of text
analysis – PangoAnalysis for text
offset – Byte offset of text from the beginning of the paragraph, or -1 to ignore attributes from analysis

trim_string(str: str) → str#

Trims leading and trailing whitespace from a string.

Deprecated since version 1.38: Please do not use it in newly written code

Parameters:: str – a string
Returns:: A newly-allocated string that must be freed with free()

unichar_direction(ch: str) → Direction#

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, for_unichar can be used instead.

Parameters:: ch – a Unicode character
Returns:: the direction of the character.

units_from_double(d: float) → int#

Converts a floating-point number to Pango units.

The conversion is done by multiplying d by SCALE and rounding the result to nearest integer.

Added in version 1.16.

Parameters:: d – double floating-point value
Returns:: the value in Pango units.

units_to_double(i: int) → float#

Converts a number in Pango units to floating-point.

The conversion is done by dividing i by SCALE.

Added in version 1.16.

Parameters:: i – value in Pango units
Returns:: the double value.

version() → int#

Returns the encoded version of Pango available at run-time.

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

Added in version 1.16.

Returns:: The encoded version of Pango library available at run time.

version_check(required_major: int, required_minor: int, required_micro: int) → str | None#

Checks that the Pango library in use is compatible with the given version.

Generally you would pass in the constants VERSION_MAJOR, VERSION_MINOR, 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 required_major.required_minor.``required_micro``. Second the running library must be binary compatible with the version required_major.required_minor.``required_micro`` (same major version.)

For compile-time version checking use VERSION_CHECK().

Added in version 1.16.

Parameters:

required_major – the required major version
required_minor – the required minor version
required_micro – the required major version

Returns:

None if the Pango library is compatible with the given version, or a string describing the version mismatch. The returned string is owned by Pango and should not be modified or freed.

version_string() → str#

Returns the version of Pango available at run-time.

This is similar to the macro VERSION_STRING except that the macro returns the version available at compile-time.

Added in version 1.16.

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.

Functions#

This Page