You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
367 lines
13 KiB
367 lines
13 KiB
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
|
|
|