modernize: Don't use apparent connect-by-name slots in MainWin
[quassel.git] / icons / README.md
1 # Icon theme support in Quassel IRC
2
3 ## Introduction
4
5 Quassel IRC requires many icons, which generally fall in three categories:
6
7  - Standard icons as defined by the [Icon Naming
8 Specification][icon-naming-spec]. These icons should be available in most modern
9 icon themes.
10  - Extended icons that are not part of the standard, but provided by the
11 [Breeze][breeze-icons] icon theme that is the default in the KDE/Plasma desktop.
12 As a KDE-affine application, Quassel IRC makes use of this extended set of
13 icons.
14  - Quassel-specific icons that are not part of any official icon theme.
15
16 We have put great effort into supporting different icon themes in the Quassel
17 client -- with the caveat that things may not look perfectly consistent, because
18 we need to fill the gaps in the system icon theme with icons that are shipped
19 with Quassel.
20
21 ## Icon theme support
22
23 ### Supported icon themes
24
25 Quassel directly supports the [Breeze][breeze-icons] and [Breeze Dark][breeze-icons]
26 icon themes that are the default in KDE/Plasma, and
27 optionally the [Oxygen][oxygen-icons] icon theme that was the default in KDE4.
28 This means that Quassel-specific icons are available to match either of the
29 three themes, and that Quassel should integrate seamlessly into your desktop's
30 look-and-feel if your system icon theme is one of the three. On platforms that
31 don't support system icon themes at all (e.g. Windows and Mac OS), users may
32 select the theme to use in the Appearance settings.
33
34 The default icon theme for Quassel is Breeze, and thus for example the
35 application icon will always come from this theme.
36
37 ### Handling icon themes that are not directly supported by Quassel
38
39 As stated before, most of the unsupported icon themes will be missing icons that
40 Quassel requires, due to them not being specified in the [Icon Naming
41 Specification][icon-naming-spec]. To cope with this, Quassel ships the required
42 subset of each of the supported themes, and injects them as a fallback into the
43 icon loading mechanism.
44
45 In the Appearance settings, users can choose which fallback theme to use, and if
46 Quassel should completely override the system theme (to get a consistent
47 look-and-feel inside the client), or just fill the gaps (to get a more
48 consistent look with the desktop environment).
49
50 ### Overriding icons
51
52 Users may override any icon by providing a theme directory (matching their
53 system theme's name and directory layout) in one of the default theme search
54 paths (on Linux, the appropriate place would be `$HOME/.local/share/icons`), and
55 putting the replacement icons there.
56
57 ## Technical information
58
59 ### Build options
60
61 By default, Quassel IRC will install the bundled Breeze and Breeze Dark icon
62 themes (which are not the full upstream themes, but only the subset actually
63 required by Quassel). This adds around 1.7 MiB to the installed size. However,
64 if it is ensured that the Breeze theme is available on the system (e.g. through
65 package dependencies), installing the bundled icons can be disabled using the
66 CMake option `-DWITH_BUNDLED_ICONS=OFF`.
67
68 Note that the themes are installed into Quassel's own data directory, so they
69 will not clash with a system installation.
70
71 The Oxygen icon theme is deprecated, and thus support for it is not enabled by
72 default. By setting the CMake option `-DWITH_OXYGEN_ICONS=ON`, Oxygen icons will
73 be installed. This adds around 1.8 MiB for the Quassel-specific icons, and
74 another 2.6 MiB if the bundled icon theme is installed as well.
75
76 ### Icon directories
77
78 Quassel-specific icons are located in `icons/`. Note that the Breeze variants
79 are generated from the  [quassel-icons repository][quassel-icons] and should not
80 be updated manually.
81
82 Bundled icon theme subsets are provided in `3rdparty/icons/`. These themes can
83 be updated from the upstream theme by running the `icons/import/import_theme.pl`
84 script. See the script header for usage instructions.
85
86 ## Known issues
87
88  - Qt versions older than Qt 5.5 don't support split icon theme installations.
89 Thus, the fallback mechanism does not work correctly, and icons will most likely
90 be missing. Third-party theme support does not work correctly, either.
91  - Qt currently has a [bug][QTBUG-68603] where it prefers the standard `hicolor`
92 theme over inherited themes. Due to the way Quassel's icon loading mechanism
93 deals with unsupported themes, this means that an icon available in hicolor will
94 override the one provided in the selected fallback theme. This normally affects
95 only the Quassel-specific icons (most visisbly the tray icon), which will then
96 always come from Breeze.
97
98 [icon-naming-spec]: https://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html
99 [breeze-icons]: https://github.com/KDE/breeze-icons
100 [oxygen-icons]: https://github.com/KDE/oxygen-icons
101 [quassel-icons]: https://github.com/justjanne/quassel-icons
102 [QTBUG-68603]: https://bugreports.qt.io/browse/QTBUG-68603