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’sGravity.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()
orGravity.WEST()
.
Glyph Storage
Structures for storing information about glyphs.
Units and conversion
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.
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 aItem
and the glyphs resulting from shaping the text corresponding to an item. As an example of the usage ofGlyphItem
, the results of shaping text withLayout
is a list ofLayoutLine
, each of which contains a list ofGlyphItem
.- split(text: str, split_index: int) GlyphItem
Modifies
orig
to cover only the text aftersplit_index
, and returns a new item that covers the text beforesplit_index
that used to be inorig
. You can think ofsplit_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
applysplit_index – byte index of position to split item, relative to the start of the item
- Returns:
a new
GlyphItem
representing text beforesplit_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 oftext
)- 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 aGlyphItem
. The forward direction of the iterator is the logical direction of text. That is, with increasingstart_index
andstart_char
values. Ifglyph_item
is right-to-left (that is, ifglyph_item->item->analysis.level
is odd), thenstart_glyph
decreases as the iterator moves forward. Moreover, in right-to-left cases,start_glyph
is greater thanend_glyph
.Note that
text
is the start of the text for layout, which is then indexed byglyph_item->item->offset
to get to the text ofglyph_item
. Thestart_index
andend_index
values can directly index intotext
. Thestart_glyph
,end_glyph
,start_char
, andend_char
values however are zero-based for theglyph_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. SeeGlyphItemIter
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. SeeGlyphItemIter
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.
Item
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 ofFontDescription
, 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 of10 * 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 a10 * (96 / 72) = 13.3
pixel font. Useset_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
andset_absolute_size()
.- Returns:
whether the size for the font description is in device units.
Font Metrics
API not implemented yet.
Font Map
API not implemented yet.
Font Set
API not implemented yet.
Font Fields
API not implemented yet.
Style
- class pangocffi.Style(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)
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(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)
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(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)
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(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)
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(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)
The bits in a
FontMask
correspond to fields in aFontDescription
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 aStyle
.
- 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 aVariant
.
- 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 aStretch
.
- 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 aWeight
.
- 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 aint
.
- 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 aint
.
- 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 aFontDescription
.
- 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
orblue
orgreen
isn’t aint
.
- 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
orblue
orgreen
isn’t aint
.
- 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 abool
.
- 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
orblue
orgreen
isn’t aint
.
- 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 aUnderline
.
- 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
orblue
orgreen
isn’t aint
.
- 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
orlogical_rectangle
isn’t aRectangle
.
- 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 aint
.
- 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 aint
.
- 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 aint
.
- 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 abool
.
- 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 aGravity
.
- 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 aGravityHint
.
- 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 astr
.
- 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 aint
.
- 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 aint
.
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 throughAttrList.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
.
- 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
.
- 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.
- 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 callingAttrList.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.
Tab Stops
Structures for storing tab stops.
TabArray
- class pangocffi.TabArray
-
- 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.
TabAlign
- class pangocffi.TabAlign(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)
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 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.- 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 theattributes
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 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 toNONE
.
- 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 attributes: AttrList | None
The text attributes for this layout.
- Parameters:
attrs – a
AttrList
- 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_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 PangoLayout
.To obtain a
LayoutIter
, useLayout.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, ifLayout.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 fromLayoutLine.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.
Layout Line
API not implemented yet.
Layout Run
Layout Modes
API not implemented yet.
Wrap Mode
- class pangocffi.WrapMode(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)
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(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)
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(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)
Alignment
describes how to align the lines of aLayout
within the available space. If theLayout
is set to justify usingset_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
API not implemented yet.
Underlined Text
Enum used by Text Attributes for underlining text.
- class pangocffi.Underline(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)
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(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)
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-identityMatrix
, and then glyph orientation is controlled usingGravity
. Not every value in this enumeration makes sense for every usage ofGravity
; for example,Gravity.AUTO
only can be passed toContext.set_base_gravity()
and can only be returned byContext.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(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)
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
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.