Detailed Description

The ImageProvider allows to load graphical assets into application, picking the best candidate of size variants.

An application can be run on devices with different screen resolutions and pixel densities. In order to scale between these, different sized graphical assets can be provided with a specific directory structure. The ImageProvider will then search for the variant best matching the device capabilities.

This mechanism allows also to have monochromatic icons which will be colored with the theme primary color, i.e. on dark ambience with different shades of white, and on light ambience different shades of black.

The directory structure on an icon root is of following:

 /path_to/iconRoot/
 .../iconRoot/icons                 - icons which don't need scaling, will be picked from here regardless of pixel ratio.
 .../iconRoot/icon-monochrome       - monochrome icons which don't need scaling. Will be colored with primary color.
 .../iconRoot/z1.0/icons            - icons for pixel ratio 1.0
 .../iconRoot/z1.0/icons-monochrome - monochrome icons for pixel ratio 1.0
 .../iconRoot/z1.25/icons           - as above for pixel ratio 1.25
 [etc]

The pixel ratio is using two digits, or one if the second would be zero. The currently used pixel ratios are: 1.0, 1.25, 1.5, 1.75, 2.0 and 2.5.

The monochrome icons should be .png files with transparency level indicating how much color to use. Colored icons can be either .png or .jpg.

The icon filenames can be appended with "-light" or "-dark" to allow having slightly different graphical assets on dark and light ambiences. For example choosing a level of gray instead of full white or black. If the icon the app is requesting is not found, the image provider will attempt appending to the name "-light" on light ambience, and "-dark" on dark ambience.

Image provider for above icon root is registered in c++:

 #include <silicaimageprovider.h>

 int main()
 {
     // [...]
     // view is QQuickView
     auto *imageProvider = new Silica::ImageProvider;
     imageProvider->addIconRoot("/usr/share/myapp/iconroot");
     view->engine()->addImageProvider(QLatin1String("my_icons"), imageProvider);
     view->setSource(appPath + QLatin1String("myapp.qml"));
     view->showFullScreen();

     return app->exec();
 }

And used in QML as:

 import QtQuick 2.6
 import Sailfish.Silica 1.0

 Image {
     source: "image://my_icons/nicely-scaled-icon"
 }