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