From ac08598176663dd4edbb1df8c3ea337499d5aee7 Mon Sep 17 00:00:00 2001
From: Adriaan de Groot <groot@kde.org>
Date: Wed, 25 Mar 2020 23:35:33 +0100
Subject: [PATCH] Branding: expand the stylesheet example

- Mention that the sidebar menu can't be styled
- Point to more documentation about styling
- Give an example of styling buttons with an icon
---
 src/branding/default/stylesheet.qss | 65 +++++++++++++++++++++++++----
 1 file changed, 58 insertions(+), 7 deletions(-)

diff --git a/src/branding/default/stylesheet.qss b/src/branding/default/stylesheet.qss
index c5341ee0a..72dd91ba4 100644
--- a/src/branding/default/stylesheet.qss
+++ b/src/branding/default/stylesheet.qss
@@ -6,26 +6,72 @@ In principle, all parts can be styled through CSS.
 Missing parts should be filed as issues.
 
 The IDs are based on the object names in the C++ code.
+You can use the Debug Dialog to find out object names:
+  - Open the debug dialog
+  - Choose tab *Tools*
+  - Click *Widget Tree* button
+The list of object names is printed in the log.
 
 Documentation for styling Qt Widgets through a stylesheet
 can be found at
     https://doc.qt.io/qt-5/stylesheet-examples.html
+    https://doc.qt.io/qt-5/stylesheet-reference.html
 In Calamares, styling widget classes is supported (e.g.
-using `QComboBox` as a selector). You can also use specific
-object names (ids), which you can find through debugging tools.
+using `QComboBox` as a selector).
+
+This example stylesheet has all the actual styling commented out.
+The examples are not exhaustive.
 
 */
 
-/* Main application window.
+/*** Generic Widgets.
+ *
+ * You can style **all** widgets of a given class by selecting
+ * the class name. Some widgets have specialized sub-selectors.
+ */
 
+/*
+QPushButton { background-color: green; }
+*/
+
+/*** Main application window.
+ *
+ * The main application window has the sidebar, which in turn
+ * contains a logo and a list of items -- note that the list
+ * can **not** be styled, since it has its own custom C++
+ * delegate code.
+ */
+
+/*
 #mainApp { }
-#logoApp { }
 #sidebarApp { }
-#sidebarMenuApp { }
+#logoApp { }
 */
 
-/* Partitioning module.
+/*** Welcome module.
+ *
+ * There are plenty of parts, but the buttons are the most interesting
+ * ones (donate, release notes, ...). The little icon image can be
+ * styled through *qproperty-icon*, which is a little obscure.
+ * URLs can reference the QRC paths of the Calamares application
+ * or loaded via plugins or within the filesystem. There is no
+ * comprehensive list of available icons, though.
+ */
 
+/*
+QPushButton#aboutButton { qproperty-icon: url(:/data/images/release.svg); }
+#donateButton,
+#supportButton,
+#releaseNotesButton,
+#knownIssuesButton { qproperty-icon: url(:/data/images/help.svg); }
+*/
+
+/*** Partitioning module.
+ *
+ * Many moving parts, which you will need to experiment with.
+ */
+
+/*
 #bootInfoIcon { }
 #bootInfoLable { }
 #deviceInfoIcon { }
@@ -34,8 +80,13 @@ object names (ids), which you can find through debugging tools.
 #partitionBarView { }
 */
 
-/* Licensing module.
+/*** Licensing module.
+ *
+ * The licensing module paints individual widgets for each of
+ * the licenses. The item can be collapsed or expanded.
+ */
 
+/*
 #licenseItem {  }
 #licenseItemFullText {  }
 */