pyface.font module

Toolkit-independent font utilities.

Pyface fonts are intended to be generic, but able to be mapped fairly well to most backend toolkit font descriptions. In most cases we can describe fonts along the common dimensions that are used by CSS, Wx, and Qt. However when it comes to actually working with a font, the toolkit needs to take the description and produce something that is as close as possible to the specification, but within the constraints of the toolkit, operating system and available fonts on the machine where this is being executed.

Because of this inherent ambiguity in font specification, this system tries to be flexible in what it accepts as a font specification, rather than trying to specify a unique canoncial form.

Font Properties

The properties that fonts have are:

Font Family

A list of font family names in order of preference, such as “Helvetica” or “Comic Sans”. In the case of a font that has been selected by the toolkit this list will have one value which is the actual font family name.

There are several generic font family names that can be used as fall-backs in case all preferred fonts are unavailable. The allowed values are:

“default”

The application’s default system font.

“fantasy”

A primarily decorative font, but with recognisable characters.

“decorative”

A synonym for “fantasy”.

“serif”

A proportional serif font, such as Times New Roman or Garamond.

“roman”

A synonym for “serif”.

“cursive”

A font which resembles hand-written cursive text, such as Zapf Chancery.

“script”

A synonym for “cursive”.

“sans-serif”

A proportional sans-serif font, such as Helvetica or Arial.

“swiss”

A synonym for “sans-serif”.

“monospace”

A fixed-pitch sans-serif font, such as Source Code Pro or Roboto Mono. Commonly used for display of code.

“modern”

A synonym for “monospace”.

“typewriter”

A fixed-pitch serif font which resembles typewritten text, such as Courier. Commonly used for display of code.

“teletype”

A synonym for “typewriter”.

These special names will be converted into appropriate toolkit flags which correspond to these generic font specifications.

Weight

How thick or dark the font glyphs are. These can be given as a number from 1 (lightest) to 999 (darkest), but are typically specified by a multiple of 100 from 100 to 900, with a number of synonyms such as ‘light’ and ‘bold’ available for those values.

Stretch

The amount of horizontal compression or expansion to apply to the glyphs. These can be given as a percentage between 50% and 200%, or by strings such as ‘condensed’ and ‘expanded’ that correspond to those values.

Style

This selects either ‘oblique’ or ‘italic’ variants typefaces of the given font family. If neither is wanted, the value is ‘normal’.

Size

The overall size of the glyphs. This can be expressed either as the numeric size in points, or as a string such as “small” or “large”.

Variants

A set of additional font style specifiers, such as “small-caps”, “strikethrough”, “underline” or “overline”, where supported by the underlying toolkit.

Font Specificiation Class

The Pyface Font class is a HasStrictTraits class which specifies a requested font. It has methods that convert the Font class to and from a toolkit Font class.

pyface.font.WEIGHTS = {'100': 100, '1000': 1000, '200': 200, '300': 300, '400': 400, '500': 500, '600': 600, '700': 700, '800': 800, '900': 900, 'black': 900, 'bold': 700, 'book': 400, 'demi': 600, 'demi-bold': 600, 'extra bold': 800, 'extra-bold': 800, 'extra-heavy': 1000, 'extra-light': 200, 'hairline': 100, 'heavy': 900, 'light': 300, 'medium': 500, 'normal': 400, 'regular': 400, 'roman': 500, 'semi-bold': 600, 'thin': 100, 'ultra-bold': 800, 'ultra-light': 200, 'ultralight': 200}

Font weight synonyms. These are alternate convenience names for font weights. The intent is to allow a developer to use a common name (eg. “bold”) instead of having to remember the corresponding number (eg. 700). These come from: - the OpenType specification: https://docs.microsoft.com/en-us/typography/opentype/spec/os2#usweightclass - QFont weights: https://doc.qt.io/qt-5/qfont.html#Weight-enum - WxPython font weights: https://wxpython.org/Phoenix/docs/html/wx.FontWeight.enumeration.html - CSS Common weight name mapping: https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight#common_weight_name_mapping - values used by Enable: https://github.com/enthought/enable/blob/78d2e494097fac71cc5c73efef5fb464963fb4db/kiva/fonttools/_constants.py#L90-L105 See also: https://gist.github.com/lukaszgrolik/5849599

pyface.font.STRETCHES = {'condensed': 75, 'expanded': 125, 'extra-condensed': 62.5, 'extra-expanded': 150, 'normal': 100, 'semi-condensed': 87.5, 'semi-expanded': 112.5, 'ultra-condensed': 50, 'ultra-expanded': 200}

Font stretch synonyms. These are alternate convenience names for font stretch/width values. The intent is to allow a developer to use a common name (eg. “expanded”) instead of having to remember the corresponding number (eg. 125). These come from: - the OpenType specification: https://docs.microsoft.com/en-us/typography/opentype/spec/os2#uswidthclass - QFont stetch: https://doc.qt.io/qt-5/qfont.html#Stretch-enum - CSS font-stretch: https://developer.mozilla.org/en-US/docs/Web/CSS/font-stretch - values used by Enable: https://github.com/enthought/enable/blob/78d2e494097fac71cc5c73efef5fb464963fb4db/kiva/fonttools/_constants.py#L78-L88

pyface.font.SIZES = {'large': 14.0, 'medium': 12.0, 'small': 10.0, 'x-large': 18.0, 'x-small': 9.0, 'xx-large': 20.0, 'xx-small': 7.0}

Font size synonyms. These are alternate convenience names for font size values. The intent is to allow a developer to use a common name (eg. “small”) instead of having to remember the corresponding number (eg. 10). These come from CSS font-size: https://developer.mozilla.org/en-US/docs/Web/CSS/font-size

pyface.font.VARIANTS = ['small-caps']

Font variants. Currently only small caps variants are exposed in Qt, and nothing in Wx. In the future this could include things like swashes, numeric variants, and so on, as exposed in the toolkit.

pyface.font.DECORATIONS = ['underline', 'strikethrough', 'overline']

Additional markings on or around the glyphs of the font that are not part of the glyphs themselves. Currently Qt and Wx support underline and strikethrough, and Qt supports overline. In the future overlines and other decorations may be supported, as exposed in the toolkit.

pyface.font.FontFamily = CList(Str, ['default'])

A trait for font families.

pyface.font.FontWeight = Map(WEIGHTS, default_value='normal')

A trait for font weights.

pyface.font.FontStyle = Enum(STYLES)

A trait for font styles.

pyface.font.FontVariants = CSet(Enum(VARIANTS))

A trait for font variant properties.

pyface.font.FontDecorations = CSet(Enum(DECORATIONS))

A trait for font decorator properties.

class pyface.font.FontStretch(default_value=<traits.trait_type._NoDefaultSpecifiedType object>, **metadata)

Bases: BaseCFloat

Trait type for font stretches.

The is a CFloat trait which holds floating point values between 50 and 200, inclusive. In addition to values which can be converted to floats, this trait also accepts named synonyms for sizes which are converted to the associated commonly accepted weights:

• ‘ultra-condensed’: 50

• ‘extra-condensed’: 62.5

• ‘condensed’: 75

• ‘semi-condensed’: 87.5

• ‘normal’: 100

• ‘semi-expanded’: 112.5

• ‘expanded’: 125

• ‘extra-expanded’: 150

• ‘ultra-expanded’: 200

default_value = 100.0

The default value for the trait.

validate(object, name, value)

Validate the trait

This is a CFloat trait that also accepts percentage strings. Values must be in the range 50 to 200 inclusive

info()

Describe the trait

class pyface.font.FontSize(default_value=<traits.trait_type._NoDefaultSpecifiedType object>, **metadata)

Bases: BaseCFloat

Trait type for font sizes.

The is a CFloat trait which also allows values which are keys of the size dictionary, and also ignores trailing ‘pt’ ot ‘px’ annotation in string values. The value stored is a float.

default_value = 12.0

The default value for the trait.

validate(object, name, value)

Validate the trait

This is a CFloat trait that also accepts strings with ‘pt’ or ‘px’ suffixes. Values must be positive.

info()

Describe the trait

class pyface.font.Font

Bases: HasStrictTraits

A toolkit-independent font specification.

This class represents a request for a font with certain characteristics, not a concrete font that can be used for drawing. Font objects returned from the toolkit may or may not match what was requested, depending on the capabilities of the toolkit, OS, and the fonts installed on a particular computer.

family = FontFamily()

The preferred font families.

weight = FontWeight()

The weight of the font.

stretch = FontStretch()

How much the font is expanded or compressed.

style = FontStyle()

The style of the font.

size = FontSize()

The size of the font.

variants = FontVariants()

The font variants.

decorations = FontDecorations()

The font decorations.

classmethod from_toolkit(toolkit_font)

Create a Font from a toolkit font object.

Parameters

toolkit_font (Any) – A toolkit font to be converted to a corresponding class instance, within the limitations of the options supported by the class.

to_toolkit()

Create a toolkit font object from the Font instance.

Returns

toolkit_font – A toolkit font which matches the property of the font as closely as possible given the constraints of the toolkit.

Return type

Any