Python API reference

Rendering

Functions to run the rendering pipeline.

class pangocffi.Context

The Context structure stores global information used to control the itemization process.

property font_description: FontDescription

The default font description for the context.

Parameters:

desc – the new Pango font description.

property base_gravity: Gravity

The base gravity for the context, which is used for laying out vertical text.

property gravity: Gravity

The gravity for the context. This is similar to base_gravity, unless it’s Gravity.AUTO(); get_for_matrix() is used to retrieve the appropriate gravity from the current context matrix.

property gravity_hint: GravityHint

The gravity hint for the context, which is used when laying out vertical text, and is only relevant if the gravity of the context is Gravity.EAST() or Gravity.WEST().

load_font(desc: FontDescription) → Font | None

Loads the font in one of the fontmaps in the context that is the closest match for desc.

Parameters:

desc – A FontDescription describing the font to load.

Returns:

The Font that was loaded, or None if no font matched.

Glyph Storage

Structures for storing information about glyphs.

Units and conversion

pangocffi.units_to_double(i: int) → float

Converts a number in Pango units to floating-point: divides it by PANGO_SCALE.

Parameters:

i – value in Pango units

pangocffi.units_from_double(d: float) → int

Converts a floating-point number to Pango units: multiplies it by PANGO_SCALE and rounds to nearest integer.

Parameters:

d – double floating-point value

Rectangle

class pangocffi.Rectangle(pointer: _CDataBase | None = None, width: int | None = None, height: int | None = None, x: int | None = None, y: int | None = None)

The Rectangle structure represents a rectangle. It is frequently used to represent the logical or ink extents of a single glyph or section of text.

property x: int

X coordinate of the left side of the rectangle.

property y: int

Y coordinate of the the top side of the rectangle.

property width: int

The width of the rectangle.

property height: int

The height of the rectangle.

Matrix

API not implemented yet.

Glyph String

API not implemented yet.

Glyph Item

class pangocffi.GlyphItem(pointer: _CDataBase = None, *init_args)

A GlyphItem is a pair of a Item and the glyphs resulting from shaping the text corresponding to an item. As an example of the usage of GlyphItem, the results of shaping text with Layout is a list of LayoutLine, each of which contains a list of GlyphItem.

property item: Item

Corresponding Item.

split(text: str, split_index: int) → GlyphItem

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

This function is similar in function to Item.split() (and uses it internally.)

Parameters:

  • text – text to which positions in orig apply

  • split_index – byte index of position to split item, relative to the start of the item

Returns:

a new GlyphItem representing text before split_index.

get_logical_widths(text: str) → List[int]

Given a GlyphItem 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.

See also GlyphString.get_logical_widths().

Parameters:

text – text that glyph_item corresponds to ( glyph_item->item->offset is an offset from the start of text)

Returns:

an array whose length is the number of characters in glyph_item (equal to glyph_item->item->num_chars) to be filled in with the resulting character widths.)

Glyph Item Iterator

class pangocffi.GlyphItemIter(pointer: _CDataBase = None, *init_args)

A GlyphItemIter is an iterator over the clusters in a GlyphItem. 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.

Note that text is the start of the text for layout, which is then 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 GlyphItemIter should be modified manually.

init_start(glyph_item: GlyphItem, text: str) → bool

Initializes the GlyphItemIter structure to point to the first cluster in a glyph item. See GlyphItemIter for details of cluster orders.

Returns:

False if there are no clusters in the glyph item

init_end(glyph_item: GlyphItem, text: str) → bool

Initializes the GlyphItemIter structure to point to the last cluster in a glyph item. See GlyphItemIter for details of cluster orders.

Returns:

False if there are no clusters in the glyph item

next_cluster() → bool

Moves the iterator forward to the next run in visual order. If the iterator was already at the end of the layout, it will return False.

Returns:

True if the iterator was advanced, False if we were already on the last cluster.

prev_cluster() → bool

Moves the iterator to the preceding cluster in the glyph item. See GlyphItemIter for details of cluster orders.

Returns:

True if the iterator was moved, False if we were already on the first cluster.

property glyph_item: GlyphItem

The glyph item being iterated over.

property text: str

The text being iterated over.

Note: In some versions of Pango, the return value will always be a blank string.

property start_index: int

The index at which this cluster starts within the text.

property end_index: int

The character at which this cluster ends within the text.

Item

class pangocffi.Item(pointer: _CDataBase = None, *init_args)

The Item structure stores information about a segment of text.

property offset: int

Byte offset of the start of this item in text.

property length: int

Length of this item in bytes.

property num_chars: int

Length of this item in characters.

Fonts

Structures representing abstract fonts.

Font Description

class pangocffi.FontDescription(pointer: _CDataBase = None, *init_args)

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

property family: str | None

The family name of the font description. This represents a font family of related font styles, and will resolve to a particular FontFamily. In some uses of FontDescription, it is also possible to use a comma-separated list of family names for this field.

property style: Style

The slant style of the font description.

Most fonts will either have an 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.

property variant: Variant

The variant of the font description, which describes whether the font is normal or small caps.

property stretch: Stretch

The stretch of the font description, which specifies how narrow or wide the font should be.

property size: int

The size field of a font description in fractional 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 set_absolute_size() if you need a particular size in device units.

property size_is_absolute: bool

Determines whether the size of the font is in points (not absolute) or device units (absolute). See size and set_absolute_size().

Returns:

whether the size for the font description is in device units.

property gravity: Gravity

Sets the gravity of the font description, which specifies how the glyphs should be rotated. If gravity is Gravity.AUTO, this actually unsets the gravity mask on the font description.

set_absolute_size(size: float) → None

Sets the size field of a font description, in device 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. See size.

Font

class pangocffi.Font(pointer: _CDataBase = None, *init_args)

The Font represents a loaded font.

get_metrics(language: Language | None = None) → FontMetrics

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.

Parameters:

language – Language tag used to determine which script to get the metrics for, or None to indicate to get the metrics for the entire font.

Returns:

A FontMetrics object.

API not fully implemented yet.

Font Metrics

class pangocffi.FontMetrics(pointer: _CDataBase = None, *init_args)

The FontMetrics describes metrics about a font.

property approximate_char_width: int

The approximate character width, in Pango units.

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.

property approximate_digit_width: int

The approximate digit width, in Pango units.

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 is generally somewhat more accurate than the result of approximate_char_width for digits.

property ascent: int

The ascent, in Pango units.

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

property descent: int

The descent, in Pango units.

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

property height: int

The height, in Pango units.

The line height is the recommended distance between successive baselines in wrapped text using this font.

If the line height is not available, 0 is returned.

property strikethrough_position: int

The suggested strikethrough position, in Pango units.

The value returned is the distance above the baseline of the top of the strikethrough.

property strikethrough_thickness: int

The suggested strikethrough thickness, in Pango units.

property underline_position: int

The suggested underline position, in Pango units.

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.

property underline_thickness: int

The suggested underline thickness, in Pango units.

Font Map

API not implemented yet.

Font Set

API not implemented yet.

Font Fields

API not implemented yet.

Style

class pangocffi.Style(*values)

An enumeration specifying the various slant styles possible for a font.

NORMAL = 0

the font is upright.

OBLIQUE = 1

the font is slanted, but in a roman style.

ITALIC = 2

the font is slanted in an italic style.

Weight

class pangocffi.Weight(*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.

THIN = 100

the thin weight( = 100; Since: 1.24)

ULTRALIGHT = 200

the ultralight weight( = 200)

LIGHT = 300

the light weight( = 300)

SEMILIGHT = 350

the semilight weight( = 350; Since: 1.36.7)

BOOK = 380

the book weight( = 380; Since: 1.24)

NORMAL = 400

the default weight( = 400)

MEDIUM = 500

the normal weight( = 500; Since: 1.24)

SEMIBOLD = 600

the semibold weight( = 600)

BOLD = 700

the bold weight( = 700)

ULTRABOLD = 800

the ultrabold weight( = 800)

HEAVY = 900

the heavy weight( = 900)

ULTRAHEAVY = 1000

the ultraheavy weight( = 1000; Since: 1.24)

Variant

class pangocffi.Variant(*values)

An enumeration specifying capitalization variant of the font.

NORMAL = 0

A normal font.

SMALL_CAPS = 1

A font with the lower case characters replaced by smaller variants of the capital characters.

Stretch

class pangocffi.Stretch(*values)

An enumeration specifying the width of the font relative to other designs within a family.

ULTRA_CONDENSED = 0

Ultra Condensed width

EXTRA_CONDENSED = 1

Extra Condensed width

CONDENSED = 2

Condensed width

SEMI_CONDENSED = 3

Semi condensed width

NORMAL = 4

The normal width

SEMI_EXPANDED = 5

Semi expanded width

EXPANDED = 6

Expanded width

EXTRA_EXPANDED = 7

Extra Expanded width

ULTRA_EXPANDED = 8

Ultra Expanded width

FontMask

class pangocffi.FontMask(*values)

The bits in a FontMask correspond to fields in a FontDescription that have been set.

FAMILY = 1

the font family is specified.

STYLE = 2

the font style is specified.

VARIANT = 4

the font variant is specified.

WEIGHT = 8

the font weight is specified.

STRETCH = 16

the font stretch is specified.

SIZE = 32

the font size is specified.

GRAVITY = 64

the font gravity is specified(Since: 1.16.)

Text Attributes

Font and other attributes for annotating text.

Attribute

class pangocffi.Attribute(pointer: _CDataBase = None, *init_args)

The Attributes — Font and other attributes for annotating text. 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.

property start_index

The index at which this attribute starts.

property end_index

The index at which this attriute ends.

classmethod from_family(family: str, start_index: int = 0, end_index: int = 1) → Attribute

Create a new font family attribute.

Parameters:

  • family – the font family

  • start_index – the start index of the range. Should be >=0.

  • end_index – end index of the range. The character at this index is not included in the range.

Returns:

the Attribute.

classmethod from_style(style: Style, start_index: int = 0, end_index: int = 1) → Attribute

Create a new font slant style attribute.

Parameters:

  • style – the slant style

  • start_index – the start index of the range. Should be >=0.

  • end_index – end index of the range. The character at this index is not included in the range.

Returns:

the Attribute.

Raises:

AssertionError When style isn’t a Style.

classmethod from_variant(variant: Variant, start_index: int = 0, end_index: int = 1) → Attribute

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

Parameters:

  • variant – the variant

  • start_index – the start index of the range. Should be >=0.

  • end_index – end index of the range. The character at this index is not included in the range.

Returns:

the Attribute.

Raises:

AssertionError When variant isn’t a Variant.

classmethod from_stretch(stretch: Stretch, start_index: int = 0, end_index: int = 1) → Attribute

Create a new font stretch attribute

Parameters:

  • stretch – the stretch

  • start_index – the start index of the range. Should be >=0.

  • end_index – end index of the range. The character at this index is not included in the range.

Returns:

the Attribute.

Raises:

AssertionError When stretch isn’t a Stretch.

classmethod from_weight(weight: Weight, start_index: int = 0, end_index: int = 1) → Attribute

Create a new font weight attribute.

Parameters:

  • weight – the weight

  • start_index – the start index of the range. Should be >=0.

  • end_index – end index of the range. The character at this index is not included in the range.

Returns:

the Attribute.

Raises:

AssertionError When weight isn’t a Weight.

classmethod from_size(size: int, start_index: int = 0, end_index: int = 1) → Attribute

Create a new font-size attribute in fractional points.

Parameters:

  • size – the font size, in PANGO_SCALEths of a point.

  • start_index – the start index of the range. Should be >=0.

  • end_index – end index of the range. The character at this index is not included in the range.

Returns:

the Attribute.

Raises:

AssertionError When size isn’t a int.

classmethod from_size_absolute(size: int, start_index: int = 0, end_index: int = 1)

Create a new font-size attribute in device units.

Parameters:

  • size – the font size, in PANGO_SCALEths of a device unit.

  • start_index – the start index of the range. Should be >=0.

  • end_index – end index of the range. The character at this index is not included in the range.

Returns:

the Attribute.

Raises:

AssertionError When absolute_size isn’t a int.

classmethod from_font_desc(font_desc: FontDescription, start_index: int = 0, end_index: int = 1) → Attribute

Create a new font description attribute. This attribute allows setting family, style, weight, variant, stretch, and size simultaneously.

Parameters:

  • font_desc – the font description

  • start_index – the start index of the range. Should be >=0.

  • end_index – end index of the range. The character at this index is not included in the range.

Returns:

the Attribute.

Raises:

AssertionError When font_desc isn’t a FontDescription.

classmethod from_foreground_color(red: int, green: int, blue: int, start_index: int = 0, end_index: int = 1) → Attribute

Create a new foreground color attribute.

Parameters:

  • red – the red value (ranging from 0 to 65535)

  • green – the green value (ranging from 0 to 65535)

  • blue – the blue value (ranging from 0 to 65535)

  • start_index – the start index of the range. Should be >=0.

  • end_index – end index of the range. The character at this index is not included in the range.

Returns:

the Attribute.

Raises:

AssertionError When red or blue or green isn’t a int.

classmethod from_background_color(red: int, green: int, blue: int, start_index: int = 0, end_index: int = 1)

Create a new background color attribute.

Parameters:

  • red – the red value (ranging from 0 to 65535)

  • green – the green value (ranging from 0 to 65535)

  • blue – the blue value (ranging from 0 to 65535)

  • start_index – the start index of the range. Should be >=0.

  • end_index – end index of the range. The character at this index is not included in the range.

Returns:

the Attribute.

Raises:

AssertionError When red or blue or green isn’t a int.

classmethod from_strikethrough(strikethrough: bool, start_index: int = 0, end_index: int = 1) → Attribute

Create a new strike-through attribute.

Parameters:

  • strikethrough – True if the text should be struck-through.

  • start_index – the start index of the range. Should be >=0.

  • end_index – end index of the range. The character at this index is not included in the range.

Returns:

the Attribute.

Raises:

AssertionError When strikethrough isn’t a bool.

classmethod from_strikethrough_color(red: int, green: int, blue: int, start_index: int = 0, end_index: int = 1) → 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.

Parameters:

  • red – the red value (ranging from 0 to 65535)

  • green – the green value (ranging from 0 to 65535)

  • blue – the blue value (ranging from 0 to 65535)

  • start_index – the start index of the range. Should be >=0.

  • end_index – end index of the range. The character at this index is not included in the range.

Returns:

the Attribute.

Raises:

AssertionError When red or blue or green isn’t a int.

classmethod from_underline(underline: Underline, start_index: int = 0, end_index: int = 1) → Attribute

Create a new underline-style attribute.

Parameters:

  • underline – the underline style.

  • start_index – the start index of the range. Should be >=0.

  • end_index – end index of the range. The character at this index is not included in the range.

Returns:

the Attribute.

Raises:

AssertionError When underline isn’t a Underline.

classmethod from_underline_color(red: int, green: int, blue: int, start_index: int = 0, end_index: int = 1) → Attribute

Create a new underline color attribute. This attribute modifies the color of underlines. If not set, underlines will use the foreground color.

Parameters:

  • red – the red value (ranging from 0 to 65535)

  • green – the green value (ranging from 0 to 65535)

  • blue – the blue value (ranging from 0 to 65535)

  • start_index – the start index of the range. Should be >=0.

  • end_index – end index of the range. The character at this index is not included in the range.

Returns:

the Attribute.

Raises:

AssertionError When red or blue or green isn’t a int.

classmethod from_shape(ink_rect: Rectangle, logical_rectangle: Rectangle, start_index: int = 0, end_index: int = 1) → Attribute

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.

Parameters:

  • ink_rect – ink rectangle to assign to each character

  • logical_rectangle – logical rectangle to assign to each character

  • start_index – the start index of the range. Should be >=0.

  • end_index – end index of the range. The character at this index is not included in the range.

Returns:

the Attribute.

Raises:

AssertionError When ink_rect or logical_rectangle isn’t a Rectangle.

classmethod from_scale(scale_factor: int, start_index: int = 0, end_index: int = 1) → 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

  • start_index – the start index of the range. Should be >=0.

  • end_index – end index of the range. The character at this index is not included in the range.

Returns:

the Attribute.

Raises:

AssertionError When scale_factor isn’t a int.

classmethod from_rise(rise: int, start_index: int = 0, end_index: int = 1) → 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.

  • start_index – the start index of the range. Should be >=0.

  • end_index – end index of the range. The character at this index is not included in the range.

Returns:

the Attribute.

Raises:

AssertionError When rise isn’t a int.

classmethod from_letter_spacing(letter_spacing: int, start_index: int = 0, end_index: int = 1) → Attribute

Create a new letter-spacing attribute.

Parameters:

  • letter_spacing – amount of extra space to add between graphemes of the text, in Pango units.

  • start_index – the start index of the range. Should be >=0.

  • end_index – end index of the range. The character at this index is not included in the range.

Returns:

the Attribute.

Raises:

AssertionError When letter_spacing isn’t a int.

classmethod from_fallback(enable_fallback: bool, start_index: int = 0, end_index: int = 1) → 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.

Parameters:

  • enable_fallback – True if we should fall back on other fonts for characters the active font is missing.

  • start_index – the start index of the range. Should be >=0.

  • end_index – end index of the range. The character at this index is not included in the range.

Returns:

the Attribute.

Raises:

AssertionError When enable_fallback isn’t a bool.

classmethod from_gravity(gravity: Gravity, start_index: int = 0, end_index: int = 1) → Attribute

Create a new gravity attribute.

Parameters:

  • gravity – the gravity value; should not be PANGO_GRAVITY_AUTO.

  • start_index – the start index of the range. Should be >=0.

  • end_index – end index of the range. The character at this index is not included in the range.

Returns:

the Attribute.

Raises:

AssertionError When gravity isn’t a Gravity.

classmethod from_gravity_hints(hint: GravityHint, start_index: int = 0, end_index: int = 1) → Attribute

Create a new gravity hint attribute.

Parameters:

  • hint – the gravity hint value from GravityHint

  • start_index – the start index of the range. Should be >=0.

  • end_index – end index of the range. The character at this index is not included in the range.

Returns:

the Attribute.

Raises:

AssertionError When hint isn’t a GravityHint.

classmethod from_font_features(features: str, start_index: int = 0, end_index: int = 1) → Attribute

Create a new font features tag attribute.

Parameters:

  • features – a string with OpenType font features, in CSS syntax

  • start_index – the start index of the range. Should be >=0.

  • end_index – end index of the range. The character at this index is not included in the range.

Returns:

the Attribute.

Raises:

AssertionError When features isn’t a str.

classmethod from_foreground_alpha(alpha: int, start_index: int = 0, end_index: int = 1) → Attribute

Create a new foreground alpha attribute.

Parameters:

  • alpha – the alpha value, between 1 and 65536

  • start_index – the start index of the range. Should be >=0.

  • end_index – end index of the range. The character at this index is not included in the range.

Returns:

the Attribute.

Raises:

AssertionError When alpha isn’t a int.

classmethod from_background_alpha(alpha: int, start_index: int = 0, end_index: int = 1) → Attribute

Create a new background alpha attribute.

Parameters:

  • alpha – the alpha value, between 1 and 65536

  • start_index – the start index of the range. Should be >=0.

  • end_index – end index of the range. The character at this index is not included in the range.

Returns:

the Attribute.

Raises:

AssertionError When alpha isn’t a int.

AttrList

class pangocffi.AttrList(pointer: _CDataBase = None, *init_args)

The AttrList represents a list of attributes(Attribute) 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 AttrList.change(), the overlap between properties will meet stricter criteria.

In general, you should not use a single AttrList for more than one paragraph of text due to internal structures.

insert(attr: Attribute) → None

Insert the given attribute into the PangoAttrList. It will be inserted after all other attributes with a matching start_index.

Parameters:

attr – The Attribute to insert.

Raises:

AssertionError When attr isn’t a Attribute.

insert_before(attr: Attribute) → None

Insert the given attribute into the PangoAttrList. It will be inserted before all other attributes with a matching start_index.

Parameters:

attr – The Attribute to insert.

Raises:

AssertionError When attr isn’t a Attribute.

change(attr: Attribute) → None

Insert the given attribute into the AttrList. 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 AttrList.insert() for creating an attribute list in order (potentially much slower for large lists). However, AttrList.insert() is not suitable for continually changing a set of attributes since it never removes or combines existing attributes.

Parameters:

attr – The Attribute to insert.

Raises:

AssertionError When attr isn’t a Attribute.

splice(attr_list: AttrList, pos: int, length: int)

This function opens up a hole in self, 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 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.

Parameters:

  • attr_list (AttrList) – another AttrList

  • pos (int) – the position in self at which to insert other

  • length (int) – 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)

Raises:

AssertionError When attr_list isn’t a AttrList. When pos isn’t a int When length isn’t a int

Tab Stops

Structures for storing tab stops.

TabArray

class pangocffi.TabArray
property tabs: List[Tuple[TabAlign, int]]

Alignment and location of the tabs.

property decimal_point: List[str | None]

Unicode character to use as decimal point.

This is only relevant for tabs with TabAlign.DECIMAL alignment, which align content at the first occurrence of the decimal point character.

The default value of None means that Pango will use the decimal point according to the current locale.

Raises:

IndexError when trying to assign more or less elements than defined tab stops.

property positions_in_pixels: bool

True if tab positions are in pixels.

TabAlign

class pangocffi.TabAlign(*values)

TabAlign specifies where the text appears relative to the tab stop position.

LEFT = 0

The text appears to the right of the tab stop position.

RIGHT = 1

The text appears to the left of the tab stop position until the available space is filled. Since: 1.50

CENTER = 2

The text is centered at the tab stop position until the available space is filled. Since: 1.50

DECIMAL = 3

Text before the first occurrence of the decimal point character appears to the left of the tab stop position (until the available space is filled), the rest to the right. Since: 1.50

Text Attribute Markup

See Gnome’s documentation for details on how to use the Pango Text Attribute Markup Language.

Layout Objects

High-level layout driver objects.

Layout

class pangocffi.Layout(context: Context)

A Pango Layout represents an entire paragraph of text. It is initialized with a Pango Context, 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.

property context: Context

The Context used for this layout.

property text: str

The text contained in the layout.

Note that if you have used apply_markup() on the layout before, you may want to clear the attributes from the markup when setting this property, as attributes are not cleared automatically.

property font_description: FontDescription | None

The default font description for the layout. If no font description is set, the font description from the layout’s context is used.

property width: int

The width to which the lines of the layout should wrap or ellipsize.

property height: int

The height to which the layout should be ellipsized at.

If the height is positive, it will be the maximum height of the layout. Only lines which fit will be shown, and any omitted text is replaced by an ellipsis. 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 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 property only has effect if a positive width is set on layout and its ellipsization mode is not NONE. The behavior is undefined if a height other than -1 is set and ellipsization mode is set to NONE.

property spacing: int

The amount of spacing, in Pango units, between the lines of the layout.

property alignment: Alignment

The alignment of the layout: how partial lines are positioned within the horizontal space available.

property ellipsize: EllipsizeMode

The ellipsize mode of the layout.

property wrap: WrapMode

The wrap mode of the layout.

property attributes: AttrList | None

The text attributes for this layout.

Parameters:

attrs – a AttrList

property tabs: TabArray | None

The tab stops for this layout.

apply_markup(markup: str) → None

Sets the layout text and attribute list from marked-up text.

Parameters:

markup – marked-up text

get_extents() → Tuple[Rectangle, Rectangle]

Computes the logical and ink extents of the 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.

The extents are given in layout coordinates and in Pango units; layout coordinates begin at the top left corner of the layout.

Returns:

a tuple containing two Rectangle objects. The first is the extent of the layout as drawn. The second is the logical extent of the layout.

get_size() → Tuple[int, int]

Determines the logical width and height of the layout in Pango units. This is simply a convenience function around get_extents().

Returns:

a tuple containing the logical width and height, respectively.

get_baseline() → int

Returns the Y coordinate of the first line’s baseline in the layout.

Returns:

baseline of the Layout’s first, line from the top

get_line_count() → int

Returns the number of lines.

Returns:

the line count

get_iter() → LayoutIter

Returns an iterator to iterate over the visual extents of the layout.

Returns:

the layout iterator

Layout Iterator

class pangocffi.LayoutIter(pointer: _CDataBase = None, *init_args)

A LayoutIter can be used to iterate over the visual extents of a Pango Layout.

To obtain a LayoutIter, use Layout.get_iter().

next_run() → bool

Moves the iterator forward to the next run in visual order. If the iterator was already at the end of the layout, it will return False.

Returns:

whether motion was possible

next_char() → bool

Moves the iterator forward to the next character in visual order. If the iterator was already at the end of the layout, it will return False.

Returns:

whether motion was possible

next_cluster() → bool

Moves the iterator forward to the next cluster in visual order. If the iterator was already at the end of the layout, it will return False.

Returns:

whether motion was possible

next_line() → bool

Moves the iterator forward to the start of the next line. If the iterator was already at the end of the layout, it will return False.

Returns:

whether motion was possible.

at_last_line() → bool

Determines whether the iterator is on the last line of the layout.

Returns:

whether the iterator is on the last line

get_index() → int

Returns 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 get_run()).

Returns:

the current byte index

get_baseline() → int

Returns the Y position of the current line’s baseline, in layout coordinates (origin at top left of the entire layout).

Returns:

the baseline of the current line

get_run() → LayoutRun | None

Returns 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 None. 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 get_run_readonly() if you do not plan to modify the contents of the run (glyphs, glyph widths, etc.).

Returns:

the current run

get_char_extents() → Rectangle

Returns the extents of the current character, in layout coordinates (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.

Returns:

a rectangle representing the logical extent of a character.

get_cluster_extents() → Tuple[Rectangle, Rectangle]

Returns the extents of the current cluster, in layout coordinates (origin is the top left of the entire layout).

Returns:

a tuple containing two Rectangle objects. The first is the extent of the cluster as drawn. The second is the logical extent.

get_run_extents() → Tuple[Rectangle, Rectangle]

Returns the extents of the current run, in layout coordinates (origin is the top left of the entire layout).

Returns:

a tuple containing two Rectangle objects. The first is the extent of the run as drawn. The second is the logical extent.

get_line_yrange() → Tuple[int, int]

Divides the vertical space in the Layout 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 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).

Returns:

a tuple containing two integers. The first is the y position of the start of the line. The second is the y position of the end of the line

get_line_extents() → Tuple[Rectangle, Rectangle]

Obtains the extents of the current line. Extents are in layout coordinates (origin is the top-left corner of the entire Layout). 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 LayoutLine.get_extents().

Returns:

a tuple containing two Rectangle objects. The first is the extent of the line as drawn. The second is the logical extent.

get_layout_extents() → Tuple[Rectangle, Rectangle]

Returns the extents of the Layout being iterated over.

Returns:

a tuple containing two Rectangle objects. The first is the extent of the run as drawn. The second is the logical extent.

Layout Line

API not implemented yet.

Layout Run

class pangocffi.LayoutRun(pointer: _CDataBase = None, *init_args)

The LayoutRun structure represents a single run within a LayoutLine; it is simply an alternate name for GlyphItem. See the GlyphItem docs for details on the fields.

Layout Modes

API not implemented yet.

Wrap Mode

class pangocffi.WrapMode(*values)

WrapMode describes how to wrap the lines of a Pango layout to the desired width.

WORD = 0

Wrap lines at word boundaries

CHAR = 1

Wrap lines at character boundaries

WORD_CHAR = 2

Wrap lines at word boundaries, but fall back to character boundaries if there is not enough space for a full word.

Ellipsize Mode

class pangocffi.EllipsizeMode(*values)

EllipsizeMode describes what sort of (if any) ellipsization should be applied to a line of 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.

NONE = 0

No ellipsization

START = 1

Omit characters at the start of the text

MIDDLE = 2

Omit characters in the middle of the text

END = 3

Omit characters at the end of the text

Alignment

class pangocffi.Alignment(*values)

Alignment describes how to align the lines of a Layout within the available space. If the Layout is set to justify using set_justify(), this only has effect for partial lines.

LEFT = 0

Put all available space on the right

CENTER = 1

Center the line within the available space

RIGHT = 2

Put all available space on the left

Scripts and Languages

Identifying writing systems and languages.

Script

API not implemented yet.

Language

class pangocffi.Language(pointer: _CDataBase = None, *init_args)

The Language represents a pango Language.

static from_string(lang: str | None) → Language | None

Create a language from a string descriptor.

The language tag must be in a RFC-3066 format.

This function first canonicalizes the string by converting it to lowercase, mapping _ to -, and stripping all characters other than letters and -.

Parameters:

lang –

A string representing a language tag.

The argument can be None.

Returns:

A Language.

The return value can be None.

static default() → Language

Returns the Language for the current locale of the process.

On Unix systems, this is the return value is derived from 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 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 does not use any such environment variables, and setting them won’t affect the behavior of functions like ctime(). The user sets the locale through the Regional Options in the Control Panel. The C library (in the setlocale() function) does not use country and language codes, but country and language names spelled out in English. However, this function does check the above environment 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 setlocale(LC_ALL, "") for the user settings to take effect. GTK does this in its initialization functions automatically (by calling gtk_set_locale()). See the setlocale() manpage for more details.

Note that the default language can change over the life of an application.

Also note that this function will not do the right thing if you use per-thread locales with uselocale(). In that case, you should just call from_string() yourself.

Returns:

The default language as a Language.

static preferred() → List[Language] | None

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

When choosing language-specific resources, such as the sample text returned by get_sample_string(), you should first try the default language, followed by the languages returned by this function.

Returns:

A list of Language.

The return value can be None.

get_sample_string() → str

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 as sample text in a font selection dialog.

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:

Language('xx').get_sample_string()
Returns:

The sample string.

matches(range_list: str) → bool

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

Parameters:

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

Returns:

True if a match was found.

to_string() → str

Gets the RFC-3066 format string representing the given language tag.

Returns:

The string.

Underlined Text

Enum used by Text Attributes for underlining text.

class pangocffi.Underline(*values)

Underline is used to specify whether text should be underlined, and if so, the type of underlining.

NONE = 0

no underline should be drawn

SINGLE = 1

a single underline should be drawn

DOUBLE = 2

a double underline should be drawn

LOW = 3

A single underline should be drawn at a position beneath the ink extents of the text being underlined. This should be used only for underlining single characters, such as for keyboard accelerators. PANGO_UNDERLINE_SINGLE should be used for extended portions of text.

ERROR = 4

a wavy underline should be drawn below. This underline is typically used to indicate an error such as a possible mispelling; in some cases a contrasting color may automatically be used. This type of underlining is available since Pango 1.4.

Bidirectional Text

Types and functions to help with handling bidirectional text.

API not implemented yet.

Vertical Text

Laying text out in vertical directions.

Gravity

class pangocffi.Gravity(*values)

Gravity 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 Matrix, and then glyph orientation is controlled using Gravity. Not every value in this enumeration makes sense for every usage of Gravity; for example, Gravity.AUTO only can be passed to Context.set_base_gravity() and can only be returned by Context.get_base_gravity().

SOUTH = 0

Glyphs stand upright (default)

EAST = 1

Glyphs are rotated 90 degrees clockwise

NORTH = 2

Glyphs are upside-down

WEST = 3

Glyphs are rotated 90 degrees counter-clockwise

AUTO = 4

Gravity is resolved from the context matrix

Gravity Hints

class pangocffi.GravityHint(*values)

GravityHint defines how horizontal scripts should behave in a vertical context. That is, English excerpt in a vertical paragraph for example.

See Gravity.

NATURAL = 0

scripts will take their natural gravity based on the base gravity and the script. This is the default.

STRONG = 1

always use the base gravity set, regardless of the script.

LINE = 2

for scripts not in their natural direction (eg. Latin in East gravity), choose per-script gravity such that every script respects the line progression. This means, Latin and Arabic will take opposite gravities and both flow top-to-bottom for example.

Low Level Functionality

Version Checking

pangocffi.pango_version() → int

Return the pango version number as a single integer, such as 14204 for 1.42.4. Major, minor and micro versions are “worth” 10000, 100 and 1 respectively.

Can be useful as a guard for method not available in older pango versions:

if pango_version() >= 11000:
    ...
pangocffi.pango_version_string() → str

Return the pango version number as a string, such as 1.42.4.

Pango Object

class pangocffi.PangoObject(pointer: _CDataBase = None, *init_args)

An AbstractBaseClass for every object used by Pango.

property pointer: _CDataBase

The C pointer to this object.

classmethod from_pointer(pointer: _CDataBase, gc: bool = False) → PangoObject

Instantiates an object from a C pointer.

Parameters:

  • pointer – a C pointer to the object.

  • gc – whether to garbage collect the pointer. Defaults to False.

Returns:

the object.