From 6d4c6dd41bd39d173e1ca187a989660b76299325 Mon Sep 17 00:00:00 2001 From: Manuel Nickschas Date: Sun, 17 Jun 2018 15:59:07 +0200 Subject: [PATCH] icons: Update icons/README.md to match reality --- icons/README.md | 158 +++++++++++++++++++++++++++++++----------------- 1 file changed, 102 insertions(+), 56 deletions(-) diff --git a/icons/README.md b/icons/README.md index e82f5523..1e5a470f 100644 --- a/icons/README.md +++ b/icons/README.md @@ -1,56 +1,102 @@ -README before changing things: -============================== - -In this folder a lot of content is generated: - -| Folder- or Filename | Generated by | Additional Info | -| ----------------------- | -------------------------- | -------------------- | -| breeze/ | import_theme.pl | | -| breezedark/ | import_theme.pl | | -| extra-icons/breeze/ | quassel-icons | | -| extra-icons/breezedark/ | quassel-icons | | -| extra-icons/oxygen/ | - | see note (a) | -| hicolor/ | partially by quassel-icons | see note (b) | -| import/ | - | see import_theme.pl | -| oxygen/ | import_theme.pl | see note (a) | -| breeze.qrc | import_theme.pl | | -| breezedark.qrc | import_theme.pl | | -| breezedark-extra.qrc | - | see note (c) | -| breeze-extra.qrc | - | see note (c) | -| CMakeLists.txt | - | | -| hicolor.qrc | - | | -| oxygen.qrc | import_theme.pl | see note (a) | -| oxygen-extra.qrc | - | see note (a) and (c) | -| README.Breeze | - | see import_theme.pl | -| README.BreezeDark | - | see import_theme.pl | -| README.md | - | | -| README.Oxygen | - | see import_theme.pl | - -# import_theme.pl - -To update the packaged icon themes you use the import_theme.pl -Check the top of the script for more detailed usage guide. But basically you need up to date -copies of the complete icon themes (e.g. in your home folder) and then run this: -``` -./import/import_theme.pl ~/oxygen-icons oxygen -./import/import_theme.pl ~/breeze-icons/icons breeze ICONS -./import/import_theme.pl ~/breeze-icons/icons-dark breezedark ICONS -``` -Note: there are additional blacklist/whitelist files in the import folder used by this script -Please update the commit info in the theme's Readme on update. - -# [quassel-icons](https://github.com/justjanne/quassel-icons) - -The quassel-icons repository ([https://github.com/justjanne/quassel-icons](https://github.com/justjanne/quassel-icons)) -by justjanne is used to generate the extra-icons folders (except the oxygen extra icons), the quassel icons in hicolor/ -as well as the ico and icns in the pics folder (outside of this icons folder). It's also used for other quassel projects -like Quasseldroid. -To update, follow the guide there and copy the output into this repository. - -# Notes - -| | Notes | -| --- | ------------------------------------------------------------------------------- | -| (a) | all oxygen related files are planned to be dropped soon™ | -| (b) | in hicolor/ there are additional icons that are not generated by quassel-icons. | -| (c) | the qrc files are not yet generated by this, but it is planned to change that. | +# Icon theme support in Quassel IRC + +## Introduction + +Quassel IRC requires many icons, which generally fall in three categories: + + - Standard icons as defined by the [Icon Naming +Specification][icon-naming-spec]. These icons should be available in most modern +icon themes. + - Extended icons that are not part of the standard, but provided by the +[Breeze][breeze-icons] icon theme that is the default in the KDE/Plasma desktop. +As a KDE-affine application, Quassel IRC makes use of this extended set of +icons. + - Quassel-specific icons that are not part of any official icon theme. + +We have put great effort into supporting different icon themes in the Quassel +client -- with the caveat that things may not look perfectly consistent, because +we need to fill the gaps in the system icon theme with icons that are shipped +with Quassel. + +## Icon theme support + +### Supported icon themes + +Quassel directly supports the [Breeze][breeze-icons] and [Breeze Dark][breeze-icons] +icon themes that are the default in KDE/Plasma, and +optionally the [Oxygen][oxygen-icons] icon theme that was the default in KDE4. +This means that Quassel-specific icons are available to match either of the +three themes, and that Quassel should integrate seamlessly into your desktop's +look-and-feel if your system icon theme is one of the three. On platforms that +don't support system icon themes at all (e.g. Windows and Mac OS), users may +select the theme to use in the Appearance settings. + +The default icon theme for Quassel is Breeze, and thus for example the +application icon will always come from this theme. + +### Handling icon themes that are not directly supported by Quassel + +As stated before, most of the unsupported icon themes will be missing icons that +Quassel requires, due to them not being specified in the [Icon Naming +Specification][icon-naming-spec]. To cope with this, Quassel ships the required +subset of each of the supported themes, and injects them as a fallback into the +icon loading mechanism. + +In the Appearance settings, users can choose which fallback theme to use, and if +Quassel should completely override the system theme (to get a consistent +look-and-feel inside the client), or just fill the gaps (to get a more +consistent look with the desktop environment). + +### Overriding icons + +Users may override any icon by providing a theme directory (matching their +system theme's name and directory layout) in one of the default theme search +paths (on Linux, the appropriate place would be `$HOME/.local/share/icons`), and +putting the replacement icons there. + +## Technical information + +### Build options + +By default, Quassel IRC will install the bundled Breeze and Breeze Dark icon +themes (which are not the full upstream themes, but only the subset actually +required by Quassel). This adds around 1.7 MiB to the installed size. However, +if it is ensured that the Breeze theme is available on the system (e.g. through +package dependencies), installing the bundled icons can be disabled using the +CMake option `-DWITH_BUNDLED_ICONS=OFF`. + +Note that the themes are installed into Quassel's own data directory, so they +will not clash with a system installation. + +The Oxygen icon theme is deprecated, and thus support for it is not enabled by +default. By setting the CMake option `-DWITH_OXYGEN_ICONS=ON`, Oxygen icons will +be installed. This adds around 1.8 MiB for the Quassel-specific icons, and +another 2.6 MiB if the bundled icon theme is installed as well. + +### Icon directories + +Quassel-specific icons are located in `icons/`. Note that the Breeze variants +are generated from the [quassel-icons repository][quassel-icons] and should not +be updated manually. + +Bundled icon theme subsets are provided in `3rdparty/icons/`. These themes can +be updated from the upstream theme by running the `icons/import/import_theme.pl` +script. See the script header for usage instructions. + +## Known issues + + - Qt versions older than Qt 5.5 don't support split icon theme installations. +Thus, the fallback mechanism does not work correctly, and icons will most likely +be missing. Third-party theme support does not work correctly, either. + - Qt currently has a [bug][QTBUG-68603] where it prefers the standard `hicolor` +theme over inherited themes. Due to the way Quassel's icon loading mechanism +deals with unsupported themes, this means that an icon available in hicolor will +override the one provided in the selected fallback theme. This normally affects +only the Quassel-specific icons (most visisbly the tray icon), which will then +always come from Breeze. + +[icon-naming-spec]: https://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html +[breeze-icons]: https://github.com/KDE/breeze-icons +[oxygen-icons]: https://github.com/KDE/oxygen-icons +[quassel-icons]: https://github.com/justjanne/quassel-icons +[QTBUG-68603]: https://bugreports.qt.io/browse/QTBUG-68603 -- 2.20.1