Changeset View
Changeset View
Standalone View
Standalone View
README.md
Show All 19 Lines | |||||
20 | ## Icon Theme Deployment | 20 | ## Icon Theme Deployment | ||
21 | 21 | | |||
22 | On Linux/BSD, it is expected that the main icon themes (hicolor, oxygen, breeze) | 22 | On Linux/BSD, it is expected that the main icon themes (hicolor, oxygen, breeze) | ||
23 | are installed by the distribution. The platform theme plugin reads the icon | 23 | are installed by the distribution. The platform theme plugin reads the icon | ||
24 | theme name from KConfig, and redirects QIcon::fromTheme calls to KIconEngine/KIconLoader, | 24 | theme name from KConfig, and redirects QIcon::fromTheme calls to KIconEngine/KIconLoader, | ||
25 | which brings some benefits over Qt's internal icon loading, such as a cache shared | 25 | which brings some benefits over Qt's internal icon loading, such as a cache shared | ||
26 | between processes. | 26 | between processes. | ||
27 | 27 | | |||
28 | On other platforms such as Windows and Mac OS, icon themes are not part of the system. | 28 | On other platforms such as MS Windows and Mac OS, icon themes are not a regular part of the system, | ||
29 | The deployment strategy for applications on those operations systems is the following: | 29 | though they are available through package management systems (like MacPorts, Fink and Cygwin). | ||
30 | | ||||
31 | When icon themes are installed in a suitable (system) location, applications can be built and | ||||
32 | deployed as on Linux/BSD provided that the location is registered by calling QIcon::setThemeSearchPath(). | ||||
33 | This can be done early in the main() function, or in a plugin that Qt loads automatically when | ||||
34 | the application starts up (a platform theme plugin, for instance). | ||||
35 | The more usual deployment strategy on those platforms consists of creating standalone applications | ||||
36 | where each has its own copy of all dependencies and required resources. | ||||
37 | | ||||
38 | Icon theme resources for standalone applications can be created and deployed as follows: | ||||
30 | - breeze-icons and other icon themes, when configured with -DBINARY\_ICONS\_RESOURCE=ON, install .rcc files (binary resources, loadable by Qt) | 39 | - breeze-icons and other icon themes, when configured with -DBINARY\_ICONS\_RESOURCE=ON, install .rcc files (binary resources, loadable by Qt) | ||
31 | - the installation process should copy one of these under the name "icontheme.rcc", in | 40 | - the installation process should copy one of these under the name "icontheme.rcc", in | ||
32 | a directory found by [QStandardPaths::AppDataLocation](http://doc.qt.io/qt-5/qstandardpaths.html#StandardLocation-enum). | 41 | a directory found by [QStandardPaths::AppDataLocation](http://doc.qt.io/qt-5/qstandardpaths.html#StandardLocation-enum). | ||
33 | For instance on Windows, icontheme.rcc is usually installed in APPROOT/data/, | 42 | For instance on Windows, icontheme.rcc is usually installed in APPROOT/data/, | ||
34 | while on Mac OS it is installed in the Resources directory inside the application bundle. | 43 | while on Mac OS it is installed in the Resources directory inside the application bundle. | ||
35 | - as long as the application links to KIconThemes (even if it doesn't use any of its API), | 44 | - as long as the application links to KIconThemes (even if it doesn't use any of its API), | ||
36 | the icontheme.rcc file will be found on startup, loaded, and set as the default icon theme. | 45 | the icontheme.rcc file will be found on startup, loaded, and set as the default icon theme. | ||
37 | 46 | | |||
47 | A related note of caution: These systems use embedded application icons regardless | ||||
48 | of how icon themes are provided, and allow users to change that icon. Software should | ||||
49 | thus ideally refrain from calling QGuiApplication::setWindowIcon() or at least pass | ||||
50 | QGuiApplication::windowIcon() as the fallback argument when using QIcon::fromTheme(). | ||||
51 | |