QGIS API Documentation 3.29.0-Master (8c80f25a4f)
Signals | Public Member Functions | Static Public Attributes | List of all members
QgsFontManager Class Reference

Manages available fonts and font installation for a QGIS instance. More...

#include <qgsfontmanager.h>

Inheritance diagram for QgsFontManager:
Inheritance graph
[legend]

Signals

void fontDownloaded (const QStringList &families, const QString &licenseDetails)
 Emitted when a font has downloaded and been locally loaded. More...
 
void fontDownloadErrorOccurred (const QUrl &url, const QString &identifier, const QString &error)
 Emitted when an error occurs during font downloading. More...
 

Public Member Functions

 QgsFontManager (QObject *parent=nullptr)
 Constructor for QgsFontManager, with the specified parent object. More...
 
void addFontFamilyReplacement (const QString &original, const QString &replacement)
 Adds a new font replacement from the original font family to a replacement font family. More...
 
void addUserFontDirectory (const QString &directory)
 Adds a directory to use for user fonts. More...
 
void downloadAndInstallFont (const QUrl &url, const QString &identifier=QString())
 Downloads a font and installs in the user's profile/fonts directory as an application font. More...
 
void enableFontDownloadsForSession ()
 Enables font downloads the the current QGIS session. More...
 
QMap< QString, QString > fontFamilyReplacements () const
 Returns the map of automatic font family replacements. More...
 
bool installFontsFromData (const QByteArray &data, QString &errorMessage, QStringList &families, QString &licenseDetails, const QString &filename=QString())
 Installs local user fonts from the specified raw data. More...
 
void installUserFonts ()
 Installs user fonts from the profile/fonts directory as application fonts. More...
 
QString processFontFamilyName (const QString &name) const
 Processes a font family name, applying any matching fontFamilyReplacements() to the name. More...
 
bool removeUserFont (const QString &path)
 Removes the user font at the specified path. More...
 
void setFontFamilyReplacements (const QMap< QString, QString > &replacements)
 Sets the map of automatic font family replacements. More...
 
bool tryToDownloadFontFamily (const QString &family, QString &matchedFamily)
 Tries to download and install the specified font family. More...
 
QString urlForFontDownload (const QString &family, QString &matchedFamily) const
 Returns the URL at which the font family can be downloaded. More...
 
QMap< QString, QStringList > userFontToFamilyMap () const
 Returns the mapping of installed user fonts to font families. More...
 

Static Public Attributes

static const QgsSettingsEntryBool settingsDownloadMissingFonts = QgsSettingsEntryBool( QStringLiteral( "downloadMissingFonts" ), QgsSettings::Prefix::FONTS, true, QStringLiteral( "Automatically download missing fonts whenever possible" ) )
 Settings entry for font family replacements. More...
 
static const QgsSettingsEntryStringList settingsFontFamilyReplacements = QgsSettingsEntryStringList( QStringLiteral( "fontFamilyReplacements" ), QgsSettings::Prefix::FONTS, QStringList(), QStringLiteral( "Automatic font family replacements" ) )
 Settings entry for font family replacements. More...
 

Detailed Description

Manages available fonts and font installation for a QGIS instance.

Note
QgsFontManager is not usually directly created, but rather accessed through QgsApplication::fontManager().
Since
QGIS 3.28

Definition at line 37 of file qgsfontmanager.h.

Constructor & Destructor Documentation

◆ QgsFontManager()

QgsFontManager::QgsFontManager ( QObject *  parent = nullptr)
explicit

Constructor for QgsFontManager, with the specified parent object.

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

Definition at line 30 of file qgsfontmanager.cpp.

Member Function Documentation

◆ addFontFamilyReplacement()

void QgsFontManager::addFontFamilyReplacement ( const QString &  original,
const QString &  replacement 
)

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.
See also
fontFamilyReplacements()
setFontFamilyReplacements()

Definition at line 52 of file qgsfontmanager.cpp.

◆ addUserFontDirectory()

void QgsFontManager::addUserFontDirectory ( const QString &  directory)

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.

Definition at line 1119 of file qgsfontmanager.cpp.

◆ downloadAndInstallFont()

void QgsFontManager::downloadAndInstallFont ( const QUrl &  url,
const QString &  identifier = QString() 
)

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()
fontDownloadErrorOccurred()

Definition at line 947 of file qgsfontmanager.cpp.

◆ enableFontDownloadsForSession()

void QgsFontManager::enableFontDownloadsForSession ( )

Enables font downloads the the current QGIS session.

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

Definition at line 178 of file qgsfontmanager.cpp.

◆ fontDownloaded

void QgsFontManager::fontDownloaded ( const QStringList &  families,
const QString &  licenseDetails 
)
signal

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
downloadAndInstallFont()
fontDownloadErrorOccurred()

◆ fontDownloadErrorOccurred

void QgsFontManager::fontDownloadErrorOccurred ( const QUrl &  url,
const QString &  identifier,
const QString &  error 
)
signal

Emitted when an error occurs during font downloading.

See also
downloadAndInstallFont()
fontDownloaded()

◆ fontFamilyReplacements()

QMap< QString, QString > QgsFontManager::fontFamilyReplacements ( ) const

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
addFontFamilyReplacement()
setFontFamilyReplacements()

Definition at line 46 of file qgsfontmanager.cpp.

◆ installFontsFromData()

bool QgsFontManager::installFontsFromData ( const QByteArray &  data,
QString &  errorMessage,
QStringList &  families,
QString &  licenseDetails,
const QString &  filename = QString() 
)

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
dataraw font data or zipped font data
errorMessagewill be set to a descriptive error message if the installation fails
familieswill be populated with a list of font families installed from the data
licenseDetailswill be populated with font license details, if found
filenamefilename hint for destination file. Will be ignored for archived content (e.g. zip file data)
Returns
true if installation was successful.

Definition at line 992 of file qgsfontmanager.cpp.

◆ installUserFonts()

void QgsFontManager::installUserFonts ( )

Installs user fonts from the profile/fonts directory as application fonts.

Note
Not available in Python bindings

Definition at line 97 of file qgsfontmanager.cpp.

◆ processFontFamilyName()

QString QgsFontManager::processFontFamilyName ( const QString &  name) const

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

Note
This method is thread safe.

Definition at line 79 of file qgsfontmanager.cpp.

◆ removeUserFont()

bool QgsFontManager::removeUserFont ( const QString &  path)

Removes the user font at the specified path.

Definition at line 1144 of file qgsfontmanager.cpp.

◆ setFontFamilyReplacements()

void QgsFontManager::setFontFamilyReplacements ( const QMap< QString, QString > &  replacements)

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
fontFamilyReplacements()
addFontFamilyReplacement()

Definition at line 68 of file qgsfontmanager.cpp.

◆ tryToDownloadFontFamily()

bool QgsFontManager::tryToDownloadFontFamily ( const QString &  family,
QString &  matchedFamily 
)

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
familyinput font family name to try to match to known fonts
matchedFamilywill be set to found font family if a match was successful
Returns
true if match was successful and the download will occur

Definition at line 138 of file qgsfontmanager.cpp.

◆ urlForFontDownload()

QString QgsFontManager::urlForFontDownload ( const QString &  family,
QString &  matchedFamily 
) const

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
familyinput font family name to try to match to known fonts
matchedFamilywill be set to found font family if a match was successful
Returns
URL to download font, or an empty string if no URL is available

Definition at line 196 of file qgsfontmanager.cpp.

◆ userFontToFamilyMap()

QMap< QString, QStringList > QgsFontManager::userFontToFamilyMap ( ) const

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.

Definition at line 1138 of file qgsfontmanager.cpp.

Member Data Documentation

◆ settingsDownloadMissingFonts

const QgsSettingsEntryBool QgsFontManager::settingsDownloadMissingFonts = QgsSettingsEntryBool( QStringLiteral( "downloadMissingFonts" ), QgsSettings::Prefix::FONTS, true, QStringLiteral( "Automatically download missing fonts whenever possible" ) )
inlinestatic

Settings entry for font family replacements.

Definition at line 48 of file qgsfontmanager.h.

◆ settingsFontFamilyReplacements

const QgsSettingsEntryStringList QgsFontManager::settingsFontFamilyReplacements = QgsSettingsEntryStringList( QStringLiteral( "fontFamilyReplacements" ), QgsSettings::Prefix::FONTS, QStringList(), QStringLiteral( "Automatic font family replacements" ) )
inlinestatic

Settings entry for font family replacements.

Definition at line 45 of file qgsfontmanager.h.


The documentation for this class was generated from the following files: