QGIS API Documentation 3.40.0-Bratislava (b56115d8743)
|
Manages available fonts and font installation for a QGIS instance. More...
#include <qgsfontmanager.h>
Signals | |
void | fontDownloaded (const QStringList &families, const QString &licenseDetails) |
Emitted when a font has downloaded and been locally loaded. | |
void | fontDownloadErrorOccurred (const QUrl &url, const QString &identifier, const QString &error) |
Emitted when an error occurs during font downloading. | |
Public Member Functions | |
QgsFontManager (QObject *parent=nullptr) | |
Constructor for QgsFontManager, with the specified parent object. | |
void | addFontFamilyReplacement (const QString &original, const QString &replacement) |
Adds a new font replacement from the original font family to a replacement font family. | |
void | addUserFontDirectory (const QString &directory) |
Adds a directory to use for user fonts. | |
QgsFontDownloadDetails | detailsForFontDownload (const QString &family, QString &matchedFamily) const |
Returns a the details for downloading the specified font family. | |
void | downloadAndInstallFont (const QgsFontDownloadDetails &details, const QString &identifier=QString()) |
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. | |
Q_DECL_DEPRECATED 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, where the font family can be downloaded via a single url. | |
void | enableFontDownloadsForSession () |
Enables font downloads the the current QGIS session. | |
QMap< QString, QString > | fontFamilyReplacements () const |
Returns the map of automatic font family replacements. | |
bool | installFontsFromData (const QByteArray &data, QString &errorMessage, QStringList &families, QString &licenseDetails, const QString &filename=QString(), const QString &extension=QString()) |
Installs local user fonts from the specified raw data. | |
void | installUserFonts () |
Installs user fonts from the profile/fonts directory as application fonts. | |
QString | processFontFamilyName (const QString &name) const |
Processes a font family name, applying any matching fontFamilyReplacements() to the name. | |
bool | removeUserFont (const QString &path) |
Removes the user font at the specified path. | |
void | setFontFamilyReplacements (const QMap< QString, QString > &replacements) |
Sets the map of automatic font family replacements. | |
bool | tryToDownloadFontFamily (const QString &family, QString &matchedFamily) |
Tries to download and install the specified font family. | |
Q_DECL_DEPRECATED QString | urlForFontDownload (const QString &family, QString &matchedFamily) const |
Returns the URL at which the font family can be downloaded. | |
QMap< QString, QStringList > | userFontToFamilyMap () const |
Returns the mapping of installed user fonts to font families. | |
Static Public Attributes | |
static const QgsSettingsEntryBool * | settingsDownloadMissingFonts = new QgsSettingsEntryBool( QStringLiteral( "downloadMissingFonts" ), QgsSettingsTree::sTreeFonts, true, QStringLiteral( "Automatically download missing fonts whenever possible" ) ) |
Settings entry for font family replacements. | |
static const QgsSettingsEntryStringList * | settingsFontFamilyReplacements = new QgsSettingsEntryStringList( QStringLiteral( "fontFamilyReplacements" ), QgsSettingsTree::sTreeFonts, QStringList(), QStringLiteral( "Automatic font family replacements" ) ) |
Settings entry for font family replacements. | |
Manages available fonts and font installation for a QGIS instance.
Definition at line 136 of file qgsfontmanager.h.
|
explicit |
Constructor for QgsFontManager, with the specified parent object.
Definition at line 64 of file qgsfontmanager.cpp.
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.
Definition at line 86 of file qgsfontmanager.cpp.
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 2045 of file qgsfontmanager.cpp.
QgsFontDownloadDetails QgsFontManager::detailsForFontDownload | ( | const QString & | family, |
QString & | matchedFamily | ||
) | const |
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.
family | input font family name to try to match to known fonts |
matchedFamily | will be set to found font family if a match was successful |
Definition at line 245 of file qgsfontmanager.cpp.
void QgsFontManager::downloadAndInstallFont | ( | const QgsFontDownloadDetails & | details, |
const QString & | identifier = QString() |
||
) |
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.
Definition at line 1821 of file qgsfontmanager.cpp.
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, 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.
Definition at line 1905 of file qgsfontmanager.cpp.
void QgsFontManager::enableFontDownloadsForSession | ( | ) |
Enables font downloads the the current QGIS session.
Definition at line 212 of file qgsfontmanager.cpp.
|
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.
|
signal |
Emitted when an error occurs during font downloading.
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.
Definition at line 80 of file qgsfontmanager.cpp.
bool QgsFontManager::installFontsFromData | ( | const QByteArray & | data, |
QString & | errorMessage, | ||
QStringList & | families, | ||
QString & | licenseDetails, | ||
const QString & | filename = QString() , |
||
const QString & | extension = 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.
data | raw font data or zipped font data |
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 |
filename | filename hint for destination file. Will be ignored for archived content (e.g. zip file data) |
extension | 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) |
true
if installation was successful. Definition at line 1910 of file qgsfontmanager.cpp.
void QgsFontManager::installUserFonts | ( | ) |
Installs user fonts from the profile/fonts directory as application fonts.
Definition at line 131 of file qgsfontmanager.cpp.
QString QgsFontManager::processFontFamilyName | ( | const QString & | name | ) | const |
Processes a font family name, applying any matching fontFamilyReplacements() to the name.
Definition at line 113 of file qgsfontmanager.cpp.
bool QgsFontManager::removeUserFont | ( | const QString & | path | ) |
Removes the user font at the specified path.
Definition at line 2070 of file qgsfontmanager.cpp.
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.
Definition at line 102 of file qgsfontmanager.cpp.
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.
family | input font family name to try to match to known fonts |
matchedFamily | will be set to found font family if a match was successful |
true
if match was successful and the download will occur Definition at line 172 of file qgsfontmanager.cpp.
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.
family | input font family name to try to match to known fonts |
matchedFamily | will be set to found font family if a match was successful |
Definition at line 1815 of file qgsfontmanager.cpp.
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 2064 of file qgsfontmanager.cpp.
|
static |
Settings entry for font family replacements.
Definition at line 147 of file qgsfontmanager.h.
|
static |
Settings entry for font family replacements.
Definition at line 144 of file qgsfontmanager.h.