Pango.FontDescription¶

record (struct)

A PangoFontDescription describes a font in an implementation-independent manner.

PangoFontDescription structures are used both to list what fonts are available on the system and also for specifying the characteristics of a font to load.

Constructors¶

new¶

@classmethod
def new(cls) -> FontDescription

Creates a new font description structure with all fields unset.

Methods¶

better_match¶

def better_match(self, old_match: FontDescription | None, new_match: FontDescription) -> bool

Determines if the style attributes of new_match are a closer match for desc than those of old_match are, or if old_match is None, determines if new_match is a match at all.

Approximate matching is done for weight and style; other style attributes must match exactly. Style attributes are all attributes other than family and size-related attributes. Approximate matching for style considers Style.OBLIQUE and Style.ITALIC as matches, but not as good a match as when the styles are equal.

Note that old_match must match desc.

Parameters:

old_match — a PangoFontDescription, or None
new_match — a PangoFontDescription

copy¶

def copy(self) -> FontDescription | None

Make a copy of a PangoFontDescription.

copy_static¶

def copy_static(self) -> FontDescription | None

Make a copy of a PangoFontDescription, but don't duplicate allocated fields.

This is like FontDescription.copy, but only a shallow copy is made of the family name and other allocated fields. The result can only be used until desc is modified or freed. This is meant to be used when the copy is only needed temporarily.

equal¶

def equal(self, desc2: FontDescription) -> bool

Compares two font descriptions for equality.

Two font descriptions are considered equal if the fonts they describe are provably identical. This means that their masks do not have to match, as long as other fields are all the same. (Two font descriptions may result in identical fonts being loaded, but still compare False.)

Parameters:

desc2 — another PangoFontDescription

free¶

def free(self) -> None

Frees a font description.

get_color¶

def get_color(self) -> FontColor

Returns the color field of the font description.

This field determines whether the font description should match fonts that have color glyphs, or fonts that don't.

get_family¶

def get_family(self) -> str | None

Gets the family name field of a font description.

See FontDescription.set_family.

get_features¶

def get_features(self) -> str | None

Gets the features field of a font description.

See FontDescription.set_features.

get_gravity¶

def get_gravity(self) -> Gravity

Gets the gravity field of a font description.

See FontDescription.set_gravity.

get_set_fields¶

def get_set_fields(self) -> FontMask

Determines which fields in a font description have been set.

get_size¶

def get_size(self) -> int

Gets the size field of a font description.

See FontDescription.set_size.

get_size_is_absolute¶

def get_size_is_absolute(self) -> bool

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

See FontDescription.set_size and FontDescription.set_absolute_size.

get_stretch¶

def get_stretch(self) -> Stretch

Gets the stretch field of a font description.

See FontDescription.set_stretch.

get_style¶

def get_style(self) -> Style

Gets the style field of a PangoFontDescription.

See FontDescription.set_style.

get_variant¶

def get_variant(self) -> Variant

Gets the variant field of a PangoFontDescription.

See FontDescription.set_variant.

get_variations¶

def get_variations(self) -> str | None

Gets the variations field of a font description.

See FontDescription.set_variations.

get_weight¶

def get_weight(self) -> Weight

Gets the weight field of a font description.

See FontDescription.set_weight.

hash¶

def hash(self) -> int

Computes a hash of a PangoFontDescription structure.

This is suitable to be used, for example, as an argument to g_hash_table_new(). The hash value is independent of desc->mask.

merge¶

def merge(self, desc_to_merge: FontDescription | None, replace_existing: bool) -> None

Merges the fields that are set in desc_to_merge into the fields in desc.

If replace_existing is False, only fields in desc that are not already set are affected. If True, then fields that are already set will be replaced as well.

If desc_to_merge is None, this function performs nothing.

Parameters:

desc_to_merge — the PangoFontDescription to merge from, or None
replace_existing — if True, replace fields in desc with the corresponding values from desc_to_merge, even if they are already exist.

merge_static¶

def merge_static(self, desc_to_merge: FontDescription, replace_existing: bool) -> None

Merges the fields that are set in desc_to_merge into the fields in desc, without copying allocated fields.

This is like FontDescription.merge, but only a shallow copy is made of the family name and other allocated fields. desc can only be used until desc_to_merge is modified or freed. This is meant to be used when the merged font description is only needed temporarily.

Parameters:

desc_to_merge — the PangoFontDescription to merge from
replace_existing — if True, replace fields in desc with the corresponding values from desc_to_merge, even if they are already exist.

set_absolute_size¶

def set_absolute_size(self, size: float) -> None

Sets the size field of a font description, in device units.

This is mutually exclusive with FontDescription.set_size which sets the font size in points.

Parameters:

size — the new size, in Pango units. There are 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.

set_color¶

def set_color(self, color: FontColor | int) -> None

Sets the color field of a font description.

This field determines whether the font description should match fonts that have color glyphs, or fonts that don't.

Parameters:

color — the PangoFontColor value

set_family¶

def set_family(self, family: str) -> None

Sets the family name field of a font description.

The family name represents a family of related font styles, and will resolve to a particular PangoFontFamily. In some uses of PangoFontDescription, it is also possible to use a comma separated list of family names for this field.

Parameters:

family — a string representing the family name.

set_family_static¶

def set_family_static(self, family: str) -> None

Sets the family name field of a font description, without copying the string.

This is like FontDescription.set_family, except that no copy of family is made. The caller must make sure that the string passed in stays around until desc has been freed or the name is set again. This function can be used if family is a static string such as a C string literal, or if desc is only needed temporarily.

Parameters:

family — a string representing the family name

set_features¶

def set_features(self, features: str | None = ...) -> None

Sets the features field of a font description.

OpenType font features allow to enable or disable certain optional features of a font, such as tabular numbers.

The format of the features string is comma-separated list of feature assignments, with each assignment being one of these forms:

FEATURE=n

where FEATURE must be a 4 character tag that identifies and OpenType feature, and n an integer (depending on the feature, the allowed values may be 0, 1 or bigger numbers). Unknown features are ignored.

Note that font features set in this way are enabled for the entire text that is using the font, which is not appropriate for all OpenType features. The intended use case is to select character variations (features cv01 - c99), style sets (ss01 - ss20) and the like.

Pango does not currently have a way to find supported OpenType features of a font. Both harfbuzz and freetype have API for this. See for example hb_ot_layout_table_get_feature_tags.

Features that are not supported by the font are silently ignored.

Parameters:

features — a string representing the features

set_features_static¶

def set_features_static(self, features: str) -> None

Sets the features field of a font description.

This is like FontDescription.set_features, except that no copy of featuresis made. The caller must make sure that the string passed in stays around until desc has been freed or the name is set again. This function can be used if features is a static string such as a C string literal, or if desc is only needed temporarily.

Parameters:

features — a string representing the features

set_gravity¶

def set_gravity(self, gravity: Gravity | int) -> None

Sets the gravity field of a font description.

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

This function is seldom useful to the user. Gravity should normally be set on a PangoContext.

Parameters:

gravity — the gravity for the font description.

set_size¶

def set_size(self, size: int) -> None

Sets the size field of a font description in fractional points.

This is mutually exclusive with FontDescription.set_absolute_size.

Parameters:

size — the size of the font in points, scaled by 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 FontDescription.set_absolute_size if you need a particular size in device units.

set_stretch¶

def set_stretch(self, stretch: Stretch | int) -> None

Sets the stretch field of a font description.

The Stretch field specifies how narrow or wide the font should be.

Parameters:

stretch — the stretch for the font description

set_style¶

def set_style(self, style: Style | int) -> None

Sets the style field of a PangoFontDescription.

The Style enumeration describes whether the font is slanted and the manner in which it is slanted; it can be either Style.NORMAL, Style.ITALIC, or Style.OBLIQUE.

Most fonts will either have a italic style or an oblique style, but not both, and font matching in Pango will match italic specifications with oblique fonts and vice-versa if an exact match is not found.

Parameters:

style — the style for the font description

set_variant¶

def set_variant(self, variant: Variant | int) -> None

Sets the variant field of a font description.

The Variant can either be Variant.NORMAL or Variant.SMALL_CAPS.

Parameters:

variant — the variant type for the font description.

set_variations¶

def set_variations(self, variations: str | None = ...) -> None

Sets the variations field of a font description.

OpenType font variations allow to select a font instance by specifying values for a number of axes, such as width or weight.

The format of the variations string is

AXIS1=VALUE,AXIS2=VALUE...

with each AXIS a 4 character tag that identifies a font axis, and each VALUE a floating point number. Unknown axes are ignored, and values are clamped to their allowed range.

Pango does not currently have a way to find supported axes of a font. Both harfbuzz and freetype have API for this. See for example hb_ot_var_get_axis_infos.

Parameters:

variations — a string representing the variations

set_variations_static¶

def set_variations_static(self, variations: str) -> None

Sets the variations field of a font description.

This is like FontDescription.set_variations, except that no copy of variations is made. The caller must make sure that the string passed in stays around until desc has been freed or the name is set again. This function can be used if variations is a static string such as a C string literal, or if desc is only needed temporarily.

Parameters:

variations — a string representing the variations

set_weight¶

def set_weight(self, weight: Weight | int) -> None

Sets the weight field of a font description.

The weight field specifies how bold or light the font should be. In addition to the values of the Weight enumeration, other intermediate numeric values are possible.

Parameters:

weight — the weight for the font description.

to_filename¶

def to_filename(self) -> str | None

Creates a filename representation of a font description.

The filename is identical to the result from calling FontDescription.to_string, but with underscores instead of characters that are untypical in filenames, and in lower case only.

to_string¶

def to_string(self) -> str

Creates a string representation of a font description.

See FontDescription.from_string for a description of the format of the string representation. The family list in the string description will only have a terminating comma if the last word of the list is a valid style option.

unset_fields¶

def unset_fields(self, to_unset: FontMask | int) -> None

Unsets some of the fields in a PangoFontDescription.

The unset fields will get back to their default values.

Parameters:

to_unset — bitmask of fields in the desc to unset.

Static functions¶

from_string¶

@staticmethod
def from_string(str: str) -> FontDescription

Creates a new font description from a string representation.

The string must have the form

[FAMILY-LIST] [STYLE-OPTIONS] [SIZE] [VARIATIONS] [FEATURES]

where FAMILY-LIST is a comma-separated list of families optionally terminated by a comma, STYLE_OPTIONS is a whitespace-separated list of words where each word describes one of style, variant, weight, stretch, or gravity, and SIZE is a decimal number (size in points) or optionally followed by the unit modifier "px" for absolute size.

The following words are understood as styles: "Normal", "Roman", "Oblique", "Italic".

The following words are understood as variants: "Small-Caps", "All-Small-Caps", "Petite-Caps", "All-Petite-Caps", "Unicase", "Title-Caps".

The following words are understood as weights: "Thin", "Ultra-Light", "Extra-Light", "Light", "Semi-Light", "Demi-Light", "Book", "Regular", "Medium", "Semi-Bold", "Demi-Bold", "Bold", "Ultra-Bold", "Extra-Bold", "Heavy", "Black", "Ultra-Black", "Extra-Black".

The following words are understood as stretch values: "Ultra-Condensed", "Extra-Condensed", "Condensed", "Semi-Condensed", "Semi-Expanded", "Expanded", "Extra-Expanded", "Ultra-Expanded".

The following words are understood as gravity values: "Not-Rotated", "South", "Upside-Down", "North", "Rotated-Left", "East", "Rotated-Right", "West".

The following words are understood as color values: "With-Color", "Without-Color".

VARIATIONS is a comma-separated list of font variations of the form @‍axis1=value,axis2=value,...

FEATURES is a comma-separated list of font features of the form #‍feature1=value,feature2=value,... The =value part can be ommitted if the value is 1.

Any one of the options may be absent. If FAMILY-LIST is absent, then the family_name field of the resulting font description will be initialized to None. If STYLE-OPTIONS is missing, then all style options will be set to the default values. If SIZE is missing, the size in the resulting font description will be set to 0.

A typical example:

Cantarell Italic Light 15 @‍wght=200 #‍tnum=1

Parameters:

str — string representation of a font description.