Home · All Classes · Grouped Classes · Annotated · Functions

Qtopia Resource System

The Qtopia resource system allows application programmers to access common application resources such as images, icons and sounds without having to concern themselves with the exact installation location or file types. The Qtopia resource system is built on top of the Qtopia Core resource model.

Rather than accessing resource files directly from disk, applications should use resource syntax inplace of a regular file name. For example, the following lines refer to the same image:

    QPixmap pix1("/opt/Qtopia/pics/addressbook/email.png");
    QPixmap pix2(":image/addressbook/email");
    QPixmap pix2(":image/service/Contacts/email");

When Qtopia detects the use of the special ":" prefix, searches in various locations - depending on the resource type - and for various file types to locate the actual resource. In addition to improving the efficiency of reference for the programmer, the Qtopia resource system improves the efficiency of access for the system. Using a special file, known as a resource database, Qtopia can bundle many separate images and icons into a single archive that is both quick to access and efficiently shared across processes.

A resource database is created using the Qtopia Core rcc tool in binary mode. Any type of Qtopia supported image and icon can be added to a resource database. A special image type, known as a QRAW image, is also exclusively supported in resource databases. A QRAW image is an uncompressed raw image that can be mmap'ed directly from disk and efficiently displayed on screen with no resident in-memory copies. As the QRAW format is uncompressed, it is best reserved for small images, very frequently used images, or images stored on compressed filesystems. QRAW images can be created from other image types using the mkqraw tool included with Qtopia.

Resource databases are always named qtopia.rdb and stored in the location dictated by the resouces they contain. The list of search directories outlined for each resource type below can be used to determine where a resource database be placed. In general, resource databases are placed in either the /opt/Qtopia/pics or /opt/Qtopia/pics/<application name> directories, but may be located elsewhere in the case of installable software or resources.

Resource databases are only supported in the Qtopia 4.2 series and later.

The specifics for each resource type are outlined below. Note that the <app name> may also be specified by refering to a service rather than the application which might provide the service - for example "service/Contacts/" rather than "addressbook/".

Images

When requesting an image, applications use a "filename" of the form <path> := :image/[i18n/][<app name>/]<image>. For each search directory listed in the $QTOPIA_PATHS environment variable as well as Qtopia's install location, the following sub-locations are tried:

pics/<QApplication::applicationName()>/qtopia.rdb#<app name>/<image>

pics/qtopia.rdb#<QApplication::applicationName()>/<app name>/<image>

pics/<app name>/qtopia.rdb#<image>

pics/qtopia.rdb#<app name>/<image>

i18n only: pics/<QApplication::applicationName()>/<app name>/i18n/<language>_<locale>/<image>.<image extension>

i18n only: pics/<app name>/i18n/<language>_<locale>/<image>.<image extension>

i18n only: pics/<QApplication::applicationName()>/<app name>/i18n/<language>/<image>.<image extension>

i18n only: pics/<app name>/i18n/<language>/<image>.<image extension>

i18n only: pics/<QApplication::applicationName()>/<app name>/i18n/en_US/<image>.<image extension>

i18n only: pics/<app name>/i18n/en_US/<image>.<image extension>

pics/<QApplication::applicationName()>/<app name>/<image>.<image extension>

pics/<app name>/<image>.<image extension>

In the listing above, <language> corresponds to Qtopia's configured language and <locale> its configured locale. The supported <image extensions> are currently "pic", "svg", "png", "jpg", "mng" and no extension.

For example, in the "addressbook" application

    // /opt/Qtopia/pics/addressbook/qtopia.rdb#email
    // /opt/Qtopia/pics/qtopia.rdb#addressbook/email
    // /opt/Qtopia/pics/qtopia.rdb#email
    // /opt/Qtopia/pics/addressbook/email.pic
    // /opt/Qtopia/pics/addressbook/email.svg
    // /opt/Qtopia/pics/addressbook/email.png
    // /opt/Qtopia/pics/addressbook/email.jpg
    // /opt/Qtopia/pics/addressbook/email.mng
    // /opt/Qtopia/pics/addressbook/email
    // /opt/Qtopia/pics/email.pic
    // /opt/Qtopia/pics/email.svg
    // /opt/Qtopia/pics/email.png
    // /opt/Qtopia/pics/email.jpg
    // /opt/Qtopia/pics/email.mng
    // /opt/Qtopia/pics/email
    QPixmap pix(":image/email");

More information on image translation can be found in Qtopia's Internationalization guide.

Themes can override images by specifying an IconPath. See Images and Icons#installing-custom-icons.

See Images and Icons for more information on images in Qtopia.

Icons

When requesting an icon, applications use a "filename" of the form <path> := :icon/[i18n/][<app name>/]<icon>. For each search directory listed in the $QTOPIA_PATHS environment variable as well as Qtopia's install location, the following sub-locations are tried:

pics/<QApplication::applicationName()>/qtopia.rdb#<app name>/icons/<icon>

pics/qtopia.rdb#<QApplication::applicationName()>/<app name>/icons/<icon>

pics/<app name>/qtopia.rdb#icons/icon

pics/qtopia.rdb#<app name>/icons/icon

pics/<QApplication::applicationName()>/<app name>/icons/i18n/<language>_<locale>/icon.<icon extension>

i18n only: pics/<app name>/icons/i18n/<language>_<locale>/icon.<icon extension>

i18n only: pics/<QApplication::applicationName()>/<app name>/icons/i18n/<language>/icon.<icon extension>

i18n only: pics/<app name>/icons/i18n/<language>/icon.<icon extension>

i18n only: pics/<QApplication::applicationName()>/<app name>/icons/i18n/en_US/icon.<icon extension>

i18n only: pics/<app name>/icons/i18n/en_US/icon.<icon extension>

pics/<QApplication::applicationName()>/icons/<app name>/icon>.<icon extension>

pics/<app name>/icons/<icon>.<icon extension>

If none found, search for :image/[i18n/][<app name>/]<icon> as though the icon was requested as an image

In the listing above, <language> corresponds to Qtopia's configured language and <locale> its configured locale. The supported <icon extensions> are currently "pic", "svg", "png", "jpg", "mng" and no extension.

More information on icon translation can be found in Qtopia's Internationalization guide.

Themes can override images by specifying an IconPath. See Images and Icons#installing-custom-icons.

See Images and Icons for more information on icons in Qtopia.

Sounds

When requesting a sound, applications use a "filename" of the form <path> := :sound/<sound>. For each search directory listed in the $QTOPIA_PATHS environment variable as well as Qtopia's install location, the following sub-locations are tried:

sounds/<QApplication::applicationName()>/<sound>.wav

sounds/<sound>.wav


Copyright © 2008 Nokia Trademarks
Qtopia 4.3.3