Qt Extended can be configured with image codecs builtin, or extened via plugins (QImageIOPlugin). Standard Qt Extended configurations include support for PNG, JPEG, SVG and QPicture image formats. QPicture is the format written by the QPicture::save() function.
SVG images are preferred wherever resolution independence is desirable. Almost all images shipped with Qt Extended are SVG images since Qt Extended runs on a large variety of displays with different resolutions and physical sizes. Qt Extended will automatically convert SVG images to QPicture images at install time as QPicture format files are faster to load than SVG images.
Icons
Icons are a special type of image. They are often required at different (standard) sizes and in different states (enabled vs. disabled). QIcon takes care of loading, scaling and any necessary post-processing of the image. Qt Extended also caches rendered icons of standard sizes in the global cache. A standard icon size is one of QStyle::PM_SmallIconSize, QStyle::PM_LargeIconSize, QStyle::PM_ListViewIconSize.
It is recommended that icons be used for standard Qt Extended widgets, e.g. QPushButton, QListView, QAction, etc. The Qt API encourages this usage by requiring QIcon parameters, rather than QImage or QPixmap.
In the Qt Extended source, SVG icons are located in the pics/icons/scalable/ or pics/<appname>/icons/scalable/ directories. The scalable part of the path is stripped out during installation, so they appear in, e.g. /opt/Qtopia/pics/icons/ on the device.
Standard raster images are placed in pics/icons/<SxS>/ or pics/<appname>/icons/<SxS>/ where <SxS> is the size of the image, e.g. 16x16, 22x22. The size installed is determined by the -iconsize configure parameter. The SxS size hint will be stripped out of the path when the image is installed.
When installing icons the installation process will first look for an SVG image, then an image of the size specified, and finally scale down a larger image to the desired size. Note that a smaller image will never be scaled up. For example, consider the following files in the source directory:
pics/icons/22x22/foo.png
pics/icons/22x22/bar.png
pics/icons/scalable/bar.svg
If Qt Extended is configured with -iconsize 16 the installed image will have:
pics/icons/foo.png
pics/icons/bar.pic
where foo.png is 16x16 pixels in size. Note also that the SVG image has been converted to a QPicture.
To load an icon within Qt Extended, use the :icon reference, for example to load the bar icon:
QIcon icon(":icon/bar").
Installing Custom Icons
Custom icons can be installed as part of a Qt Extended Theme. The Theme Configuration File includes an IconPath that will be searched before standard system locations. This allows a theme to override any icon installed on the device. The directory structure of the IconPath must mirror that of the standard system path, i.e. any replacement image must have the same name and relative location as the image being replaced.
For example, to replace pics/icons/cancel.pic with a new version supplied with the animal theme, the icon could be located in:
pics/themes/animal/pics/icons/cancel.svg
with an IconPath of:
IconPath="pics/themes/animal/pics"
See also File System Standards, QIcon, and QImage.
