Document QGtk3Interface

Add internal documentation to header and implementation of
QGtk3Interface.

Pick-to: 6.5
Change-Id: I3e6e970afa0c2ab26e0ce9efe6285cad1edfdb94
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

2 files changed, 183 insertions, 21 deletions

diff --git a/src/plugins/platformthemes/gtk3/qgtk3interface.cpp b/src/plugins/platformthemes/gtk3/qgtk3interface.cpp
index 4ce7d92ceb..1a717aeb67 100644
--- a/src/plugins/platformthemes/gtk3/qgtk3interface.cpp
+++ b/src/plugins/platformthemes/gtk3/qgtk3interface.cpp
@@ -64,6 +64,14 @@ QGtk3Interface::~QGtk3Interface()
         gtk_widget_destroy(v.second);
 }
 
+/*!
+    \internal
+    \brief Converts a string into the GtkStateFlags enum.
+
+    Converts a string formatted GTK color \param state into an enum value.
+    Returns an integer corresponding to GtkStateFlags.
+    Returns -1 if \param state does not correspond to a valid enum key.
+ */
 int QGtk3Interface::toGtkState(const QString &state)
 {
 #define CASE(x) \
@@ -91,6 +99,10 @@ int QGtk3Interface::toGtkState(const QString &state)
 #undef CASE
 }
 
+/*!
+    \internal
+    \brief Returns \param state converted into a string.
+ */
 const QLatin1String QGtk3Interface::fromGtkState(GtkStateFlags state)
 {
 #define CASE(x) case GTK_STATE_FLAG_ ##x: return QLatin1String(#x)
@@ -102,9 +114,12 @@ const QLatin1String QGtk3Interface::fromGtkState(GtkStateFlags state)
 #undef CONVERT
 }
 
+/*!
+    \internal
+    \brief Populates the internal map used to find a GTK color's source and fallback generic color.
+ */
 void QGtk3Interface::initColorMap()
 {
-    // Populate map with default values
  #define SAVE(src, state, prop, def)\
     {ColorKey({QGtkColorSource::src, GTK_STATE_FLAG_ ##state}), ColorValue({#prop ##_L1, QGtkColorDefault::def})}
 
@@ -131,8 +146,17 @@ void QGtk3Interface::initColorMap()
     qCDebug(lcQGtk3Interface) << "Color map populated from defaults.";
 }
 
-// Return an image rather than an icon or a pixmap:
-// Image can be cached and re-scaled to different sizes if requested multiple times
+/*!
+    \internal
+    \brief Returns a QImage corresponding to \param standardPixmap.
+
+    A QImage (not a QPixmap) is returned so it can be cached and re-scaled in case the pixmap is
+    requested multiple times with different resolutions.
+
+    \note Rather than defaulting to a QImage(), all QPlatformTheme::StandardPixmap enum values have
+    been mentioned explicitly.
+    That way they can be covered more easily in case additional icons are provided by GTK.
+ */
 QImage QGtk3Interface::standardPixmap(QPlatformTheme::StandardPixmap standardPixmap) const
 {
     switch (standardPixmap) {
@@ -235,6 +259,10 @@ QImage QGtk3Interface::standardPixmap(QPlatformTheme::StandardPixmap standardPix
     Q_UNREACHABLE();
 }
 
+/*!
+    \internal
+    \brief Returns a QImage for a given GTK \param iconName.
+ */
 QImage QGtk3Interface::qt_gtk_get_icon(const char* iconName) const
 {
     GtkIconSet* iconSet  = gtk_icon_factory_lookup_default (iconName);
@@ -242,14 +270,23 @@ QImage QGtk3Interface::qt_gtk_get_icon(const char* iconName) const
     return qt_convert_gdk_pixbuf(icon);
 }
 
+/*!
+    \internal
+    \brief Returns a QImage converted from the GDK pixel buffer \param buf.
+
+    The ability to convert GdkPixbuf to QImage relies on the following assumptions:
+    \list
+    \li QImage uses uchar as a data container (unasserted)
+    \li the types guint8 and uchar are identical (statically asserted)
+    \li GDK pixel buffer uses 8 bits per sample (assumed at runtime)
+    \li GDK pixel buffer has 4 channels (assumed at runtime)
+    \endlist
+ */
 QImage QGtk3Interface::qt_convert_gdk_pixbuf(GdkPixbuf *buf) const
 {
     if (!buf)
         return QImage();
 
-    // Ability to convert GdkPixbuf to QImage relies on the assumptions, that
-    // - QImage uses uchar as a data container
-    // - the types guint8 and uchar are identical
     const guint8 *gdata = gdk_pixbuf_read_pixels(buf);
     static_assert(std::is_same<decltype(gdata), const uchar *>::value,
             "guint8 has diverted from uchar. Code needs fixing.");
@@ -264,6 +301,13 @@ QImage QGtk3Interface::qt_convert_gdk_pixbuf(GdkPixbuf *buf) const
     return converted.copy(); // detatch to survive lifetime of buf
 }
 
+/*!
+    \internal
+    \brief Instantiate a new GTK widget.
+
+    Returns a pointer to a new GTK widget of \param type, allocated on the heap.
+    Returns nullptr of gtk_Default has is passed.
+ */
 GtkWidget *QGtk3Interface::qt_new_gtkWidget(QGtkWidget type) const
 {
 #define CASE(Type)\
@@ -298,6 +342,14 @@ GtkWidget *QGtk3Interface::qt_new_gtkWidget(QGtkWidget type) const
     Q_UNREACHABLE();
 }
 
+/*!
+    \internal
+    \brief Read a GTK widget's color from a generic color getter.
+
+    This method returns a generic color of \param con, a given GTK style context.
+    The requested color is defined by \param def and the GTK color-state \param state.
+    The return type is GDK color in RGBA format.
+ */
 GdkRGBA QGtk3Interface::genericColor(GtkStyleContext *con, GtkStateFlags state, QGtkColorDefault def) const
 {
     GdkRGBA color;
@@ -316,9 +368,16 @@ GdkRGBA QGtk3Interface::genericColor(GtkStyleContext *con, GtkStateFlags state,
 #undef CASE
 }
 
-// Deliver a QColor from a GTK widget, a source type and a GTK widget state
-// Fall back to the generic color getter of source/state if the property name does not exist
-// Fall back to a hard coded generic color getter of source/state are not mapped
+/*!
+    \internal
+    \brief Read a GTK widget's color from a property.
+
+    Returns a color of GTK-widget \param widget, defined by \param source and \param state.
+    The return type is GDK color in RGBA format.
+
+    \note If no corresponding property can be found for \param source, the method falls back to a
+    suitable generic color.
+ */
 QColor QGtk3Interface::color(GtkWidget *widget, QGtkColorSource source, GtkStateFlags state) const
 {
     GdkRGBA col;
@@ -355,7 +414,15 @@ QColor QGtk3Interface::color(GtkWidget *widget, QGtkColorSource source, GtkState
 #undef CASE
 }
 
-// Deliver a widget pointer
+/*!
+    \internal
+    \brief Get pointer to a GTK widget by \param type.
+
+    Returns the pointer to a GTK widget, specified by \param type.
+    GTK widgets are cached, so that only one instance of each type is created.
+    \note
+    The method returns nullptr for the enum value gtk_Default.
+ */
 GtkWidget *QGtk3Interface::widget(QGtkWidget type) const
 {
     if (type == QGtkWidget::gtk_Default)
@@ -371,7 +438,14 @@ GtkWidget *QGtk3Interface::widget(QGtkWidget type) const
     return w;
 }
 
-// Return widget syle context or default style
+/*!
+    \internal
+    \brief Access a GTK widget's style context.
+
+    Returns the pointer to the style context of GTK widget \param w.
+
+    \note If \param w is nullptr, the GTK default style context (entry style) is returned.
+ */
 GtkStyleContext *QGtk3Interface::context(GtkWidget *w) const
 {
     if (w)
@@ -380,15 +454,28 @@ GtkStyleContext *QGtk3Interface::context(GtkWidget *w) const
     return gtk_widget_get_style_context(widget(QGtkWidget::gtk_entry));
 }
 
-// FIXME
-// Brush assets (e.g. 9-patches) can't be accessed by the GTK API.
-// => brush height and width from GTK will be ignored for the time being,
-// because it is unknown if they relate to a plain brush or an image brush.
+/*!
+    \internal
+    \brief Create a QBrush from a GTK widget.
+
+    Returns a QBrush corresponding to GTK widget type \param wtype, \param source and \param state.
+
+    Brush height and width is ignored in GTK3, because brush assets (e.g. 9-patches)
+    can't be accessed by the GTK3 API. It's therefore unknown, if the brush relates only to colors,
+    or to a pixmap based style.
+
+ */
 QBrush QGtk3Interface::brush(QGtkWidget wtype, QGtkColorSource source, GtkStateFlags state) const
 {
+    // FIXME: When a color's pixmap can be accessed via the GTK API,
+    // read it and set it in the brush.
     return QBrush(color(widget(wtype), source, state));
 }
 
+/*!
+    \internal
+    \brief Returns the name of the current GTK theme.
+ */
 const QString QGtk3Interface::themeName() const
 {
     gchar *theme_name;
@@ -400,6 +487,15 @@ const QString QGtk3Interface::themeName() const
     return QLatin1StringView(theme_name);
 }
 
+/*!
+    \internal
+    \brief Determine appearance by colors.
+
+    Returns the appearance of the current GTK theme, heuristically determined by the
+    lightness difference between default background and foreground colors.
+
+    \note Returns Unknown in the unlikely case that both colors have the same lightness.
+ */
 Qt::Appearance QGtk3Interface::appearanceByColors() const
 {
     const QColor background = color(widget(QGtkWidget::gtk_Default),
@@ -416,6 +512,12 @@ Qt::Appearance QGtk3Interface::appearanceByColors() const
     return Qt::Appearance::Unknown;
 }
 
+/*!
+    \internal
+    \brief Map font type to GTK widget type.
+
+    Returns the GTK widget type corresponding to the given QPlatformTheme::Font \param type.
+ */
 inline constexpr QGtk3Interface::QGtkWidget QGtk3Interface::toWidgetType(QPlatformTheme::Font type)
 {
     switch (type) {
@@ -451,6 +553,10 @@ inline constexpr QGtk3Interface::QGtkWidget QGtk3Interface::toWidgetType(QPlatfo
     Q_UNREACHABLE();
 }
 
+/*!
+    \internal
+    \brief Convert pango \param style to QFont::Style.
+ */
 inline constexpr QFont::Style QGtk3Interface::toFontStyle(PangoStyle style)
 {
      switch (style) {
@@ -462,6 +568,13 @@ inline constexpr QFont::Style QGtk3Interface::toFontStyle(PangoStyle style)
      Q_UNREACHABLE();
 }
 
+/*!
+    \internal
+    \brief Convert pango font \param weight to an int, representing font weight in Qt.
+
+    Compatibility of PangoWeight is statically asserted.
+    The minimum (1) and maximum (1000) weight in Qt is respeced.
+ */
 inline constexpr int QGtk3Interface::toFontWeight(PangoWeight weight)
 {
     // GTK PangoWeight can be directly converted to QFont::Weight
@@ -475,6 +588,17 @@ inline constexpr int QGtk3Interface::toFontWeight(PangoWeight weight)
     return qBound(1, static_cast<int>(weight), 1000);
 }
 
+/*!
+    \internal
+    \brief Return a GTK styled font.
+
+    Returns the QFont corresponding to \param type by reading the corresponding
+    GTK widget type's font.
+
+    \note GTK allows to specify a non fixed font as the system's fixed font.
+    If a fixed font is requested, the method fixes the pitch and falls back to monospace,
+    unless a suitable fixed pitch font is found.
+ */
 QFont QGtk3Interface::font(QPlatformTheme::Font type) const
 {
     GtkStyleContext *con = context(widget(toWidgetType(type)));
@@ -498,9 +622,6 @@ QFont QGtk3Interface::font(QPlatformTheme::Font type) const
     font.setPointSizeF(static_cast<float>(pango_font_description_get_size(gtkFont)/PANGO_SCALE));
     font.setStyle(toFontStyle(pango_font_description_get_style(gtkFont)));
 
-    // fix pixel pitch if fixed font is requested
-    // NOTE: GTK allows to specify a non fixed font as the system's fixed font.
-    // => the returned font may still not be a fixed font.
     if (type == QPlatformTheme::FixedFont) {
         font.setFixedPitch(true);
         if (!QFontInfo(font).fixedPitch()) {
@@ -513,6 +634,10 @@ QFont QGtk3Interface::font(QPlatformTheme::Font type) const
     return font;
 }
 
+/*!
+    \internal
+    \brief Returns a GTK styled file icon for \param fileInfo.
+ */
 QIcon QGtk3Interface::fileIcon(const QFileInfo &fileInfo) const
 {
     GFile *file = g_file_new_for_path(fileInfo.absoluteFilePath().toLatin1().constData());
diff --git a/src/plugins/platformthemes/gtk3/qgtk3interface_p.h b/src/plugins/platformthemes/gtk3/qgtk3interface_p.h
index 84119cc638..0ac476eeb1 100644
--- a/src/plugins/platformthemes/gtk3/qgtk3interface_p.h
+++ b/src/plugins/platformthemes/gtk3/qgtk3interface_p.h
@@ -38,6 +38,18 @@ Q_DECLARE_LOGGING_CATEGORY(lcQGtk3Interface);
 using namespace Qt::StringLiterals;
 
 class QGtk3Storage;
+
+/*!
+    \internal
+    \brief The QGtk3Interface class centralizes communication with the GTK3 library.
+
+    By encapsulating all GTK version specific syntax and conversions, it makes Qt's GTK theme
+    independent from GTK versions.
+
+    \note
+    Including GTK3 headers requires #undef signals, which disables Qt signal/slot handling.
+ */
+
 class QGtk3Interface
 {
     Q_GADGET
@@ -45,7 +57,13 @@ public:
     QGtk3Interface(QGtk3Storage *);
     ~QGtk3Interface();
 
-    // Enum representing GTK widget types
+    /*!
+     *  \internal
+        \enum QGtk3Interface::QGtkWidget
+        \brief Represents GTK widget types used to obtain color information.
+
+        \note The enum value gtk_Default refers to the GTK default style, rather than to a specific widget.
+     */
     enum class QGtkWidget {
         gtk_menu_bar,
         gtk_menu,
@@ -70,7 +88,15 @@ public:
     };
     Q_ENUM(QGtkWidget)
 
-    // Enum representing color sources of a GTK theme
+    /*!
+        \internal
+        \enum QGtk3Interface::QGtkColorSource
+        \brief The QGtkColorSource enum represents the source of a color within a GTK widgets style context.
+
+        If the current GTK theme provides such a color for a given widget, the color can be read
+        from the style context by passing the enum's key as a property name to the GTK method
+        gtk_style_context_lookup_color. The method will return false, if no color has been found.
+     */
     enum class QGtkColorSource {
         Foreground,
         Background,
@@ -80,7 +106,18 @@ public:
     };
     Q_ENUM(QGtkColorSource)
 
-    // Enum for default color getter
+    /*!
+        \internal
+        \enum QGtk3Interface::QGtkColorDefault
+        \brief The QGtkColorDefault enum represents generic GTK colors.
+
+        The GTK3 methods gtk_style_context_get_color, gtk_style_context_get_background_color, and
+        gtk_style_context_get_foreground_color always return the respective colors with a widget's
+        style context. Unless set as a property by the current GTK theme, GTK's default colors will
+        be returned.
+        These generic default colors, represented by the GtkColorDefault enum, are used as a
+        back, if a specific color property is requested but not defined in the current GTK theme.
+     */
     enum class QGtkColorDefault {
         Foreground,
         Background,