Back to index
Application resources manager. More...
|Generic resources files reader/writer class. More...|
|Reader/writer for .ini resources files. More...|
|Represents container for settings read from the resource file. More...|
|Reader/writer for .xml resources files. More...|
Application resources manager.
This class can be used to define settings, save/load settings and application preferences to the resource file(s), load translation files (internationalization mechanism), load pixmaps and other resources from external files, etc.
Currently it supports .ini and .xml resources file formats. To implement own resources file format, inherit from the Format class and implement virtual Format::load() and Format::save() methods.
Resources manager is initialized by the (symbolic) name of the application. The parameter resVarTemplate specifies the template for the environment variable which should point to the resource directory or list of directories. Environment variable name is calculated by substitution of "%1" substring in the resVarTemplate parameter (if it contains such substring) by the application name (appName). By default, resVarTemplate is set to "%1Resources". For example, if the application name is "MyApp", the environment variable "MyAppResources" will be inspected in this case.
Resource manager can handle several global application configuration files and one user configuration file. Location of global configuration files is defined by the environment variable (see above) and these files are always read-only. The name of the global configuration files is retrieved by calling virtual method globalFileName() which can be redefined in the QtxResourceMgr class successors. User configuration file always situated in the user's home directory. It's name is defined by calling virtual method userFileName() which can be also redefined in the QtxResourceMgr class successors. This is the only file which the preferences changed by the user during the application session are written to (usually when the application closes).
Resources environment variable should contain one or several resource directories (separated by ";" symbol on Windows and ":" or ";" on Linux). Each resource directory can contain application global configuration file. The user configuration file has the highest priority, for the global configuration files the priority is decreasing from left to right, i.e. the first directory in the directoris list, defined by the resources environment variable has higher priority. Priority has the meaning when searching requested resources (application preference, pixmap file name, translation file, etc).
When retrieving preferences, it is sometimes helpful to ignore values coming from the user preference file and take into account only global preferences. To do this, use setWorkingMode() method passing QtxResourceMgr::IgnoreUserValues enumerator as parameter.
Resources manager operates with such terms like options, sections and parameters. Parametets are named application resources, for example, application preferences like integer, double, boolean or string values, pictures, font and color definitions, etc. Parameters are organized inside the resources files into the named groups - sections. Options are special kind of resoures which allow customizing resource files interpreting. For example, by default language settings are defined in the resource file in the section "language". It is possible to change this section name by setting "language" option to another value (see setOption()).
Retrieving preferences values can be done by using one of value() methods, each returns
true if the corresponding preference is found. Another way is to use integerValue(), doubleValue(), etc methods, which allow specifying default value which is used if the specified preference is not found. Removing of preferences or sections can be done using remove(const QString& sect) or remove(const QString& sect, const QString& name) methods. To add the preference or to change exiting preference value use setValue() methods family. Methods hasSection() and hasValue() can be used to check existence of section or preference (in the specified section). List of all sections can be retrieved with the sections() method, and list of all settings names in some specified section can be obtained with parameters() method.
Pixmaps can be loaded with the loadPixmap() methods. If the specified pixmap is not found, the default one is returned. Default pixmap can be set by setDefaultPixmap().
One of the key feature of the resources manager is support of application internationalization mechanism. Translation files for the specified language can be loaded with loadLanguage() method.