Doc: explain how to check for the existence of a font family

bb6d68703b67e042e2a7254c2ca6a004a1441cc5 fixed warnings in the
Universal style by using a faster alternative. It's possible that users
will run into these warnings too, and they should be provided with
information to make a more informed choice about which approach they
can use.

Fixes: QTBUG-123360
Pick-to: 6.5
Change-Id: I4170e9ade40c4b54dbc2bd73d124b2ade4d8c939
Reviewed-by: Eskil Abrahamsen Blomfeldt <eskil.abrahamsen-blomfeldt@qt.io>
(cherry picked from commit ce9f06c1579efda7ae0d259bfaa565f99d89e4f7)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
(cherry picked from commit 78b7b0472cb086f4be157ffee8d6c26bff8502ca)

1 files changed, 32 insertions, 1 deletions

diff --git a/src/gui/text/qfont.cpp b/src/gui/text/qfont.cpp
index 05225d1408..68b564c164 100644
--- a/src/gui/text/qfont.cpp
+++ b/src/gui/text/qfont.cpp
@@ -2750,6 +2750,35 @@ QDataStream &operator>>(QDataStream &s, QFont &font)
     info object is \e not updated.
     \endlist
 
+    \section1 Checking for the existence of a font
+
+    Sometimes it can be useful to check if a font exists before attempting
+    to use it. The most thorough way of doing so is by using \l {exactMatch()}:
+
+    \code
+    const QFont segoeFont(QLatin1String("Segoe UI"));
+    if (QFontInfo(segoeFont).exactMatch()) {
+        // Use the font...
+    }
+    \endcode
+
+    However, this deep search of families can be expensive on some platforms.
+    \c QFontDatabase::families().contains() is a faster, but less thorough
+    alternative:
+
+    \code
+    const QLatin1String segoeUiFamilyName("Segoe UI");
+    if (QFontDatabase::families().contains(segoeUiFamilyName)) {
+        const QFont segoeFont(segoeUiFamilyName);
+        // Use the font...
+    }
+    \endcode
+
+    It's less thorough because it's not a complete search: some font family
+    aliases may be missing from the list. However, this approach results in
+    faster application startup times, and so should always be preferred if
+    possible.
+
     \sa QFont, QFontMetrics, QFontDatabase
 */
 
@@ -2766,6 +2795,8 @@ QDataStream &operator>>(QDataStream &s, QFont &font)
     Use QPainter::fontInfo() to get the font info when painting.
     This will give correct results also when painting on paint device
     that is not screen-compatible.
+
+    \sa {Checking for the existence of a font}
 */
 QFontInfo::QFontInfo(const QFont &font)
     : d(font.d)
@@ -2807,7 +2838,7 @@ QFontInfo &QFontInfo::operator=(const QFontInfo &fi)
 /*!
     Returns the family name of the matched window system font.
 
-    \sa QFont::family()
+    \sa QFont::family(), {Checking for the existence of a font}
 */
 QString QFontInfo::family() const
 {