From f5e74db1b5245814d5993b6b16d58274ca8b89ab Mon Sep 17 00:00:00 2001

From: Jan Grulich <jgrulich@redhat.com>

Date: Thu, 27 Jul 2023 12:42:49 +0200

Subject: [PATCH 13/15] Document QGtk3Storage

Add internal documentation to header and implementation of

QGtk3Storage

---

 .../platformthemes/gtk3/qgtk3storage.cpp      | 231 +++++++++++++++---

 .../platformthemes/gtk3/qgtk3storage_p.h      |   1 +

 2 files changed, 193 insertions(+), 39 deletions(-)

diff --git a/src/plugins/platformthemes/gtk3/qgtk3storage.cpp b/src/plugins/platformthemes/gtk3/qgtk3storage.cpp

index 0b6b8e8523..7775ac66e4 100644

--- a/src/plugins/platformthemes/gtk3/qgtk3storage.cpp

+++ b/src/plugins/platformthemes/gtk3/qgtk3storage.cpp

@@ -24,7 +24,26 @@ QGtk3Storage::QGtk3Storage()

     populateMap();

 }

-// Set a brush from a source and resolve recursions

+/*!

+    \internal

+    \enum QGtk3Storage::SourceType

+    \brief This enum represents the type of a color source.

+

+    \value Gtk Color is read from a GTK widget

+    \value Fixed A fixed brush is specified

+    \value Modified The color is a modification of another color (fixed or read from GTK)

+    \omitvalue Invalid

+ */

+

+/*!

+    \internal

+    \brief Find a brush from a source.

+

+    Returns a QBrush from a given \param source and a \param map of available brushes

+    to search from.

+

+    A null QBrush is returned, if no brush corresponding to the source has been found.

+ */

 QBrush QGtk3Storage::brush(const Source &source, const BrushMap &map) const

 {

     switch (source.sourceType) {

@@ -64,7 +83,14 @@ QBrush QGtk3Storage::brush(const Source &source, const BrushMap &map) const

     Q_UNREACHABLE();

 }

-// Find source for a recursion and take dark/light/unknown into consideration

+/*!

+    \internal

+    \brief Recurse to find a source brush for modification.

+

+    Returns the source specified by the target brush \param b in the \param map of brushes.

+    Takes dark/light/unknown into consideration.

+    Returns an empty brush if no suitable one can be found.

+ */

 QGtk3Storage::Source QGtk3Storage::brush(const TargetBrush &b, const BrushMap &map) const

 {

 #define FIND(brush) if (map.contains(brush))\

@@ -88,7 +114,16 @@ QGtk3Storage::Source QGtk3Storage::brush(const TargetBrush &b, const BrushMap &m

 #undef FIND

 }

-// Create a simple standard palette

+/*!

+    \internal

+    \brief Returns a simple, hard coded base palette.

+

+    Create a hard coded palette with default colors as a fallback for any color that can't be

+    obtained from GTK.

+

+    \note This palette will be used as a default baseline for the system palette, which then

+    will be used as a default baseline for any other palette type.

+ */

 QPalette QGtk3Storage::standardPalette()

 {

     QColor backgroundColor(0xd4, 0xd0, 0xc8);

@@ -105,7 +140,13 @@ QPalette QGtk3Storage::standardPalette()

     return palette;

 }

-// Deliver a palette styled according to the current GTK Theme

+/*!

+    \internal

+    \brief Return a GTK styled QPalette.

+

+    Returns the pointer to a (cached) QPalette for \param type, with its brushes

+    populated according to the current GTK theme.

+ */

 const QPalette *QGtk3Storage::palette(QPlatformTheme::Palette type) const

 {

     if (type >= QPlatformTheme::NPalettes)

@@ -160,6 +201,12 @@ const QPalette *QGtk3Storage::palette(QPlatformTheme::Palette type) const

     return &m_paletteCache[type].value();

 }

+/*!

+    \internal

+    \brief Return a GTK styled font.

+

+    Returns a QFont of \param type, styled according to the current GTK theme.

+*/

 const QFont *QGtk3Storage::font(QPlatformTheme::Font type) const

 {

     if (m_fontCache[type].has_value())

@@ -169,6 +216,13 @@ const QFont *QGtk3Storage::font(QPlatformTheme::Font type) const

     return &m_fontCache[type].value();

 }

+/*!

+    \internal

+    \brief Return a GTK styled standard pixmap if available.

+

+    Returns a pixmap specified by \param standardPixmap and \param size.

+    Returns an empty pixmap if GTK doesn't support the requested one.

+ */

 QPixmap QGtk3Storage::standardPixmap(QPlatformTheme::StandardPixmap standardPixmap,

                                      const QSizeF &size) const

 {

@@ -186,11 +240,19 @@ QPixmap QGtk3Storage::standardPixmap(QPlatformTheme::StandardPixmap standardPixm

     return QPixmap::fromImage(image.scaled(size.toSize()));

 }

+/*!

+    \internal

+    \brief Returns a GTK styled file icon corresponding to \param fileInfo.

+ */

 QIcon QGtk3Storage::fileIcon(const QFileInfo &fileInfo) const

 {

     return m_interface ? m_interface->fileIcon(fileInfo) : QIcon();

 }

+/*!

+    \internal

+    \brief Clears all caches.

+ */

 void QGtk3Storage::clear()

 {

     m_appearance = Qt::Appearance::Unknown;

@@ -202,6 +264,13 @@ void QGtk3Storage::clear()

         cache.reset();

 }

+/*!

+    \internal

+    \brief Handles a theme change at runtime.

+

+    Clear all caches, re-populate with current GTK theme and notify the window system interface.

+    This method is a callback for the theme change signal sent from GTK.

+ */

 void QGtk3Storage::handleThemeChange()

 {

     clear();

@@ -209,6 +278,54 @@ void QGtk3Storage::handleThemeChange()

     QWindowSystemInterface::handleThemeChange(nullptr);

 }

+/*!

+    \internal

+    \brief Populates a map with information about how to locate colors in GTK.

+

+    This method creates a data structure to locate color information for each brush of a QPalette

+    within GTK. The structure can hold mapping information for each QPlatformTheme::Palette

+    enum value. If no specific mapping is stored for an enum value, the system palette is returned

+    instead of a specific one. If no mapping is stored for the system palette, it will fall back to

+    QGtk3Storage::standardPalette.

+

+    The method will populate the data structure with a standard mapping, covering the following

+    palette types:

+    \list

+    \li QPlatformTheme::SystemPalette

+    \li QPlatformTheme::CheckBoxPalette

+    \li QPlatformTheme::RadioButtonPalette

+    \li QPlatformTheme::ComboBoxPalette

+    \li QPlatformTheme::GroupBoxPalette

+    \li QPlatformTheme::MenuPalette

+    \li QPlatformTheme::TextLineEditPalette

+    \endlist

+

+    The method will check the environment variable {{QT_GUI_GTK_JSON_SAVE}}. If it points to a

+    valid path with write access, it will write the standard mapping into a Json file.

+    That Json file can be modified and/or extended.

+    The Json syntax is

+    - "QGtk3Palettes" (top level value)

+        - QPlatformTheme::Palette

+            - QPalette::ColorRole

+                - Qt::Appearance

+                - Qt::ColorGroup

+                - Source data

+                    - Source Type

+                        - [source data]

+

+    If the environment variable {{QT_GUI_GTK_JSON_HARDCODED}} contains the keyword \c true,

+    all sources are converted to fixed sources. In that case, they contain the hard coded HexRGBA

+    values read from GTK.

+

+    The method will also check the environment variable {{QT_GUI_GTK_JSON}}. If it points to a valid

+    Json file with read access, it will be parsed instead of creating a standard mapping.

+    Parsing errors will be printed out with qCInfo if the logging category {{qt.qpa.gtk}} is activated.

+    In case of a parsing error, the method will fall back to creating a standard mapping.

+

+    \note

+    If a Json file contains only fixed brushes (e.g. exported with {{QT_GUI_GTK_JSON_HARDCODED=true}}),

+    no colors will be imported from GTK.

+ */

 void QGtk3Storage::populateMap()

 {

     static QString m_themeName;

@@ -248,6 +365,15 @@ void QGtk3Storage::populateMap()

         qWarning() << "File" << jsonOutput << "could not be saved.\n";

 }

+/*!

+    \internal

+    \brief Return a palette map for saving.

+

+    This method returns the existing palette map, if the environment variable

+    {{QT_GUI_GTK_JSON_HARDCODED}} is not set or does not contain the keyword \c true.

+    If it contains the keyword \c true, it returns a palette map with all brush

+    sources converted to fixed sources.

+ */

 const QGtk3Storage::PaletteMap QGtk3Storage::savePalettes() const

 {

     const QString hard = qEnvironmentVariable("QT_GUI_GTK_JSON_HARDCODED");

@@ -282,21 +408,50 @@ const QGtk3Storage::PaletteMap QGtk3Storage::savePalettes() const

     return map;

 }

+/*!

+    \internal

+    \brief Saves current palette mapping to a \param filename with Json format \param f.

+

+    Saves the current palette mapping into a QJson file,

+    taking {{QT_GUI_GTK_JSON_HARDCODED}} into consideration.

+    Returns \c true if saving was successful and \c false otherwise.

+ */

 bool QGtk3Storage::save(const QString &filename, QJsonDocument::JsonFormat f) const

 {

     return QGtk3Json::save(savePalettes(), filename, f);

 }

+/*!

+    \internal

+    \brief Returns a QJsonDocument with current palette mapping.

+

+    Saves the current palette mapping into a QJsonDocument,

+    taking {{QT_GUI_GTK_JSON_HARDCODED}} into consideration.

+    Returns \c true if saving was successful and \c false otherwise.

+ */

 QJsonDocument QGtk3Storage::save() const

 {

     return QGtk3Json::save(savePalettes());

 }

+/*!

+    \internal

+    \brief Loads palette mapping from Json file \param filename.

+

+    Returns \c true if the file was successfully parsed and \c false otherwise.

+ */

 bool QGtk3Storage::load(const QString &filename)

 {

     return QGtk3Json::load(m_palettes, filename);

 }

+/*!

+    \internal

+    \brief Creates a standard palette mapping.

+

+    The method creates a hard coded standard mapping, used if no external Json file

+    containing a valid mapping has been specified in the environment variable {{QT_GUI_GTK_JSON}}.

+ */

 void QGtk3Storage::createMapping()

 {

     // Hard code standard mapping

@@ -332,41 +487,39 @@ void QGtk3Storage::createMapping()

 #define CLEAR map.clear()

     /*

-     *  Macro ussage:

-     *

-     *  1. Define a source

-     *

-     *  GTK(QGtkWidget, QGtkColorSource, GTK_STATE_FLAG)

-     *  Fetch the color from a GtkWidget, related to a source and a state.

-     *

-     *  LIGHTER(ColorGroup, ColorROle, lighter)

-     *  Use a color of the same QPalette related to ColorGroup and ColorRole.

-     *  Make the color lighter (if lighter >100) or darker (if lighter < 100)

-     *

-     *  MODIFY(ColorGroup, ColorRole, red, green, blue)

-     *  Use a color of the same QPalette related to ColorGroup and ColorRole.

-     *  Modify it by adding red, green, blue.

-     *

-     *  FIX(const QBrush &)

-     *  Use a fixed brush without querying GTK

-     *

-     *  2. Define the target

-     *

-     *  Use ADD(ColorGroup, ColorRole) to use the defined source for the

-     *  color group / role in the current palette.

-     *

-     *  Use ADD(ColorGroup, ColorRole, Appearance) to use the defined source

-     *  only for a specific appearance

-     *

-     *  3. Save mapping

-     *  Save the defined mappings for a specific palette.

-     *  If a mapping entry does not cover all color groups and roles of a palette,

-     *  the system palette will be used for the remaining values.

-     *  If the system palette does not have all combination of color groups and roles,

-     *  the remaining ones will be populated by a hard coded fusion-style like palette.

-     *

-     *  4. Clear mapping

-     *  Use CLEAR to clear the mapping and begin a new one.

+       Macro usage:

+

+       1. Define a source

+       GTK(QGtkWidget, QGtkColorSource, GTK_STATE_FLAG)

+       Fetch the color from a GtkWidget, related to a source and a state.

+

+       LIGHTER(ColorGroup, ColorROle, lighter)

+       Use a color of the same QPalette related to ColorGroup and ColorRole.

+       Make the color lighter (if lighter >100) or darker (if lighter < 100)

+

+       MODIFY(ColorGroup, ColorRole, red, green, blue)

+       Use a color of the same QPalette related to ColorGroup and ColorRole.

+       Modify it by adding red, green, blue.

+

+       FIX(const QBrush &)

+       Use a fixed brush without querying GTK

+

+       2. Define the target

+       Use ADD(ColorGroup, ColorRole) to use the defined source for the

+       color group / role in the current palette.

+

+       Use ADD(ColorGroup, ColorRole, Appearance) to use the defined source

+       only for a specific appearance

+

+       3. Save mapping

+       Save the defined mappings for a specific palette.

+       If a mapping entry does not cover all color groups and roles of a palette,

+       the system palette will be used for the remaining values.

+       If the system palette does not have all combination of color groups and roles,

+       the remaining ones will be populated by a hard coded fusion-style like palette.

+

+       4. Clear mapping

+       Use CLEAR to clear the mapping and begin a new one.

      */

diff --git a/src/plugins/platformthemes/gtk3/qgtk3storage_p.h b/src/plugins/platformthemes/gtk3/qgtk3storage_p.h

index 57f6aeea96..af628d49ff 100644

--- a/src/plugins/platformthemes/gtk3/qgtk3storage_p.h

+++ b/src/plugins/platformthemes/gtk3/qgtk3storage_p.h

@@ -33,6 +33,7 @@ class QGtk3Storage

 public:

     QGtk3Storage();

+    // Enum documented in cpp file. Please keep it in line with updates made here.

     enum class SourceType {

         Gtk,

         Fixed,

-- 

2.41.0