Class: QgsFontManager

class qgis.core.QgsFontManager

Bases: PyQt5.QtCore.QObject

Manages available fonts and font installation for a QGIS instance.

Note

QgsFontManager is not usually directly created, but rather accessed through QgsApplication.fontManager().

New in version 3.28.

QgsFontManager(parent: QObject = None) Constructor for QgsFontManager, with the specified parent object.

Note

QgsFontManager is not usually directly created, but rather accessed through QgsApplication.fontManager().

Methods

addFontFamilyReplacement

Adds a new font replacement from the original font family to a replacement font family.

addUserFontDirectory

Adds a directory to use for user fonts.

childEvent

connectNotify

customEvent

disconnectNotify

downloadAndInstallFont

Downloads a font and installs in the user's profile/fonts directory as an application font.

enableFontDownloadsForSession

Enables font downloads the the current QGIS session.

fontFamilyReplacements

Returns the map of automatic font family replacements.

installFontsFromData

Installs local user fonts from the specified raw data.

isSignalConnected

processFontFamilyName

Processes a font family name, applying any matching fontFamilyReplacements() to the name.

receivers

removeUserFont

Removes the user font at the specified path.

sender

senderSignalIndex

setFontFamilyReplacements

Sets the map of automatic font family replacements.

timerEvent

tryToDownloadFontFamily

Tries to download and install the specified font family.

urlForFontDownload

Returns the URL at which the font family can be downloaded.

userFontToFamilyMap

Returns the mapping of installed user fonts to font families.

Signals

fontDownloadErrorOccurred

Emitted when an error occurs during font downloading.

fontDownloaded

Emitted when a font has downloaded and been locally loaded.

addFontFamilyReplacement(self, original: str, replacement: str)

Adds a new font replacement from the original font family to a replacement font family.

This is used to transparently map an original font family to an alternative font family, e.g. to permit graceful handling of opening projects which reference fonts which are not available on the system.

The replacement map is stored locally and persists across QGIS sessions.

If replacement is an empty string then any existing mapping for the original family will be removed.

Note

This method is thread safe.

Parameters
  • original (str) –

  • replacement (str) –

addUserFontDirectory(self, directory: str)

Adds a directory to use for user fonts.

This directory will be scanned for any TTF or OTF font files, which will automatically be added and made available for use in the QGIS session.

Additionally, if this is the first user font directory added, any fonts downloaded via downloadAndInstallFont() will be installed into this directory.

Parameters

directory (str) –

childEvent(self, QChildEvent)
connectNotify(self, QMetaMethod)
customEvent(self, QEvent)
disconnectNotify(self, QMetaMethod)
downloadAndInstallFont(self, url: QUrl, identifier: str = '')

Downloads a font and installs in the user’s profile/fonts directory as an application font.

The download will proceed in a background task.

The optional identifier string can be used to specify a user-friendly name for the download tasks, e.g. the font family name if known.

See also

fontDownloaded()

Parameters
  • url (QUrl) –

  • identifier (str = '') –

enableFontDownloadsForSession(self)

Enables font downloads the the current QGIS session.

Warning

Ensure that the QgsApplication is fully initialized before calling this method.

fontDownloadErrorOccurred

Emitted when an error occurs during font downloading.

See also

fontDownloaded() [signal]

Parameters
  • url (QUrl) –

  • identifier (str) –

  • error (str) –

fontDownloaded

Emitted when a font has downloaded and been locally loaded.

The families list specifies the font families contained in the downloaded font.

If found, the licenseDetails string will be populated with corresponding font license details.

See also

fontDownloadErrorOccurred() [signal]

Parameters
  • families (Iterable[str]) –

  • licenseDetails (str) –

fontFamilyReplacements(self) Dict[str, str]

Returns the map of automatic font family replacements.

This map is used to transparently map an original font family to an alternative font family, e.g. to permit graceful handling of opening projects which reference fonts which are not available on the system.

The map keys are the original font family names, and the values are the alternative replacement family to use for the font.

Note

This method is thread safe.

Return type

Dict[str, str]

installFontsFromData(self, data: Union[QByteArray, bytes, bytearray], filename: str = '') Tuple[bool, str, List[str], str]

Installs local user fonts from the specified raw data.

The data array may correspond to the contents of a TTF or OTF font file, or a zipped archive of font files.

Parameters
  • data (Union[QByteArray) – raw font data or zipped font data

  • filename (str = '') – filename hint for destination file. Will be ignored for archived content (e.g. zip file data)

Return type

Tuple[bool, str, List[str], str]

Returns

  • True if installation was successful.

  • errorMessage: will be set to a descriptive error message if the installation fails

  • families: will be populated with a list of font families installed from the data

  • licenseDetails: will be populated with font license details, if found

isSignalConnected(self, QMetaMethod) bool
processFontFamilyName(self, name: str) str

Processes a font family name, applying any matching fontFamilyReplacements() to the name.

Note

This method is thread safe.

Parameters

name (str) –

Return type

str

receivers(self, PYQT_SIGNAL) int
removeUserFont(self, path: str) bool

Removes the user font at the specified path.

Parameters

path (str) –

Return type

bool

sender(self) QObject
senderSignalIndex(self) int
setFontFamilyReplacements(self, replacements: Dict[str, str])

Sets the map of automatic font family replacements.

This map is used to transparently map an original font family to an alternative font family, e.g. to permit graceful handling of opening projects which reference fonts which are not available on the system.

The map keys are the original font family names, and the values are the alternative replacement family to use for the font.

The replacement map is stored locally and persists across QGIS sessions.

Note

This method is thread safe.

Parameters

replacements (Dict[str) –

timerEvent(self, QTimerEvent)
tryToDownloadFontFamily(self, family: str) Tuple[bool, str]

Tries to download and install the specified font family.

This method will attempt to download missing fonts, if the font download URL is known and the font is freely licensed.

Returns True if a download link for the family is known and the download has commenced, or False if the family is not known and cannot be automatically downloaded.

The actual download operation occurs in a background task, and this method returns immediately. Connect to fontDownloaded() in order to respond when the font is installed and available for use.

Warning

Before calling this method a QgsApplication must be fully initialized and a call to enableFontDownloadsForSession() made.

Parameters

family (str) – input font family name to try to match to known fonts

Return type

Tuple[bool, str]

Returns

  • True if match was successful and the download will occur

  • matchedFamily: will be set to found font family if a match was successful

urlForFontDownload(self, family: str) Tuple[str, str]

Returns the URL at which the font family can be downloaded.

This method relies on a hardcoded list of available freely licensed fonts, and will return an empty string for any font families not present in this list.

Parameters

family (str) – input font family name to try to match to known fonts

Return type

Tuple[str, str]

Returns

  • URL to download font, or an empty string if no URL is available

  • matchedFamily: will be set to found font family if a match was successful

userFontToFamilyMap(self) Dict[str, List[str]]

Returns the mapping of installed user fonts to font families.

The map keys are the file names, the values are a list of families provided by the file.

Return type

Dict[str, List[str]]