Class: QgsFontManager¶
Manages available fonts and font installation for a QGIS instance.
Note
QgsFontManager
is not usually directly created, but rather accessed through QgsApplication.fontManager()
.
Added in version 3.28.
Class Hierarchy¶
Base classes¶
Methods
Adds a new font replacement from the original font family to a replacement font family. |
|
Adds a directory to use for user fonts. |
|
Returns a the details for downloading the specified font family. |
|
Downloads a font and installs in the user's profile/fonts directory as an application font, where the font family can be downloaded via a single url. |
|
Enables font downloads the the current QGIS session. |
|
Returns the map of automatic font family replacements. |
|
Installs local user fonts from the specified raw data. |
|
Processes a font family name, applying any matching |
|
Removes the user font at the specified path. |
|
Sets the map of automatic font family replacements. |
|
Tries to download and install the specified font family. |
|
Returns the URL at which the font family can be downloaded. |
|
Returns the mapping of installed user fonts to font families. |
Signals
Emitted when an error occurs during font downloading. |
|
Emitted when a font has downloaded and been locally loaded. |
- class qgis.core.QgsFontManager[source]¶
Bases:
QObject
- __init__(parent: QObject | None = None)
Constructor for QgsFontManager, with the specified
parent
object.Note
QgsFontManager is not usually directly created, but rather accessed through
QgsApplication.fontManager()
.- Parameters:
parent (Optional[QObject] = None)
- addFontFamilyReplacement(self, original: str | None, replacement: str | None)[source]¶
Adds a new font replacement from the
original
font family to areplacement
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 theoriginal
family will be removed.Note
This method is thread safe.
See also
See also
- Parameters:
original (Optional[str])
replacement (Optional[str])
- addUserFontDirectory(self, directory: str | None)[source]¶
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 (Optional[str])
- detailsForFontDownload(self, family: str | None)[source]¶
Returns a the details for downloading the specified font
family
.The returned object will contain all URLs which must be fetched to retrieve the entire font family (eg it may contain one URL per font style).
This method relies on a hardcoded list of available freely licensed fonts, and will return an invalid
QgsFontDownloadDetails
for any font families not present in this list.- Parameters:
family (Optional[str]) -> (QgsFontDownloadDetails) – input font family name to try to match to known fonts
- Returns:
details required for downloading font, or an invalid
QgsFontDownloadDetails
if no URL is availablematchedFamily: found font family if a match was successful
Added in version 3.38.
- downloadAndInstallFont(self, url: QUrl, identifier: str | None = '')[source]¶
Downloads a font and installs in the user’s profile/fonts directory as an application font, where the font family can be downloaded via a single
url
.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
See also
Deprecated since version 3.38: Use the version which takes a
QgsFontDownloadDetails
argument instead.- Parameters:
url (QUrl)
identifier (Optional[str] = '')
- downloadAndInstallFont(self, details: QgsFontDownloadDetails, identifier: str | None = '')[source]
Downloads a font and installs in the user’s profile/fonts directory as an application font, where the font family is split over multiple download URLs.
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
See also
Added in version 3.38.
- Parameters:
details (
QgsFontDownloadDetails
)identifier (Optional[str] = '')
- enableFontDownloadsForSession(self)[source]¶
Enables font downloads the the current QGIS session.
Warning
Ensure that the
QgsApplication
is fully initialized before calling this method.
- signal fontDownloadErrorOccurred(url: QUrl, identifier: str, error: str)[source]¶
Emitted when an error occurs during font downloading.
See also
See also
- Parameters:
url (QUrl)
identifier (str)
error (str)
- signal fontDownloaded(families: List[str], licenseDetails: str)[source]¶
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
See also
- Parameters:
families (List[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.
See also
See also
- Return type:
Dict[str, str]
- installFontsFromData(self, data: QByteArray | bytes | bytearray, filename: str | None = '', extension: str | None = '')[source]¶
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, bytes, bytearray]) – raw font data or zipped font data
filename (Optional[str] = '') – filename hint for destination file. Will be ignored for archived content (e.g. zip file data)
extension (Optional[str] = '') -> (bool) – known file extension (eg “ttf”, “otf”) for font. Should be specified to avoid issues with font installation on Windows if filename is not specified (since QGIS 3.38)
- Returns:
True
if installation was successful.errorMessage: 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
- processFontFamilyName(self, name: str | None) str [source]¶
Processes a font family
name
, applying any matchingfontFamilyReplacements()
to the name.Note
This method is thread safe.
- Parameters:
name (Optional[str])
- Return type:
str
- removeUserFont(self, path: str | None) bool [source]¶
Removes the user font at the specified
path
.- Parameters:
path (Optional[str])
- Return type:
bool
- setFontFamilyReplacements(self, replacements: Dict[str | None, str | None])[source]¶
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.
See also
See also
- Parameters:
replacements (Dict[Optional[str], Optional[str]])
- tryToDownloadFontFamily(self, family: str | None)[source]¶
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, orFalse
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 toenableFontDownloadsForSession()
made.- Parameters:
family (Optional[str]) -> (bool) – input font family name to try to match to known fonts
- Returns:
True
if match was successful and the download will occurmatchedFamily: found font family if a match was successful
- urlForFontDownload(self, family: str | None)[source]¶
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 (Optional[str]) -> (str) – input font family name to try to match to known fonts
- Returns:
URL to download font, or an empty string if no URL is available
matchedFamily: found font family if a match was successful
Deprecated since version 3.38: Use
detailsForFontDownload()
instead.
- 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]]