Clarify the role of the two QPlatformFontDatabase::fontEngine overloads

Change-Id: I81c59dad3479a783db8883f31e7ca9962ce959ff
Reviewed-by: Eskil Abrahamsen Blomfeldt <eskil.abrahamsen-blomfeldt@qt.io>

2 files changed, 21 insertions, 3 deletions

diff --git a/src/gui/text/qplatformfontdatabase.cpp b/src/gui/text/qplatformfontdatabase.cpp
index eb54a4e5cb..2b53fb0406 100644
--- a/src/gui/text/qplatformfontdatabase.cpp
+++ b/src/gui/text/qplatformfontdatabase.cpp
@@ -279,6 +279,17 @@ QFontEngineMulti *QPlatformFontDatabase::fontEngineMulti(QFontEngine *fontEngine
 /*!
     Returns the font engine that can be used to render the font described by
     the font definition, \a fontDef, in the specified \a script.
+
+    This function is called by QFontDatabase both for system fonts provided
+    by the platform font database, as well as for application fonts added by
+    the application developer.
+
+    The handle is the QPlatformFontDatabase specific handle passed when
+    registering the font family via QPlatformFontDatabase::registerFont.
+
+    The function is called for both fonts added via a filename as well
+    as fonts added from QByteArray data. Subclasses will need to handle
+    both cases via its platform specific handle.
 */
 QFontEngine *QPlatformFontDatabase::fontEngine(const QFontDef &fontDef, void *handle)
 {
@@ -288,6 +299,13 @@ QFontEngine *QPlatformFontDatabase::fontEngine(const QFontDef &fontDef, void *ha
     return nullptr;
 }
 
+/*!
+    Returns the font engine that will be used to back a QRawFont,
+    based on the given \fontData, \a pixelSize, and \a hintingPreference.
+
+    This function is called by QRawFont, and does not play a part in
+    the normal operations of QFontDatabase.
+*/
 QFontEngine *QPlatformFontDatabase::fontEngine(const QByteArray &fontData, qreal pixelSize,
                                                QFont::HintingPreference hintingPreference)
 {
diff --git a/src/gui/text/qplatformfontdatabase.h b/src/gui/text/qplatformfontdatabase.h
index ffb32d701c..73af0bf50f 100644
--- a/src/gui/text/qplatformfontdatabase.h
+++ b/src/gui/text/qplatformfontdatabase.h
@@ -72,13 +72,13 @@ public:
     virtual void populateFamily(const QString &familyName);
     virtual void invalidate();
 
-    virtual QFontEngineMulti *fontEngineMulti(QFontEngine *fontEngine, QChar::Script script);
-    virtual QFontEngine *fontEngine(const QFontDef &fontDef, void *handle);
     virtual QStringList fallbacksForFamily(const QString &family, QFont::Style style, QFont::StyleHint styleHint, QChar::Script script) const;
     virtual QStringList addApplicationFont(const QByteArray &fontData, const QString &fileName, QFontDatabasePrivate::ApplicationFont *font = nullptr);
-    virtual void releaseHandle(void *handle);
 
+    virtual QFontEngine *fontEngine(const QFontDef &fontDef, void *handle);
     virtual QFontEngine *fontEngine(const QByteArray &fontData, qreal pixelSize, QFont::HintingPreference hintingPreference);
+    virtual QFontEngineMulti *fontEngineMulti(QFontEngine *fontEngine, QChar::Script script);
+    virtual void releaseHandle(void *handle);
 
     virtual QString fontDir() const;