tdeconfigdata.h contains definitions of the data formats used by tdeconfig. Configuration entries are stored as "KEntry". They are indexed with "KEntryKey". The primary store is a "KEntryMap" which is defined as a QMap from "KEntryKey" to "KEntry" KEntry's are stored in order in the KEntryMap. The most significant sort criteria is mGroup. This means that all entries who belong in the same group, are grouped in the QMap as well. The start of a group is indicated with a KEntryKey with an empty mKey and a dummy KEntry. This allows us to search for the start of the group and then to iterate until we end up in another group. That way we will find all entries of a certain group. Entries that are localised with the _current_ locale are stored with bLocal set to true. Entries that are localised with another locale are either not stored at all (default), or with the localization as part of the key (when reading a file in order to merge it). [WABA: Does it make sense to keep both localized and non-localised around? Can't we just let the localised version override the non-localised version?] Currently the localization bit is the least significant sort criteria, that means that the localised version always follows the non-localised version immediately. <Changed for KDE 3.0> Entries that are being read from a location other than the location to which is written back are marked as "default" and will be added both as normal entry as well as an entry with the key marked as default. When entries are written to disk, it is checked whether the entry to write is equal to the default, if so the entry will not be written. The default entry always follows directly after the normal entry, due to the sorting. (After that the localised version follows) When entries are written to disk, it is checked whether the entry to write is equal to the default, if so the entry will not be written. </Changed> Open question: Should unmodified entries that are written back be compared with the default too? This seems to be mostly a transition issue. <Changed during KDE 3.0 / 3.2> Extra functions: bool entryIsImmutable(key); // Can entry be modified? bool hasDefault(key); // Is there a system wide default set for the entry? void revertToDefault(key); // Restore to default void deleteEntry(key); // Remove entry Note that there is a subtle difference between revertToDefault() and deleteEntry(). revertToDefault() will change the entry to the default value set by the system administrator (Via e.g. $TDEDIR/share/config) or, if no such default was set, non-existant. deleteEntry() will make the entry non-existant. Entries are marked "immutable" if the key is followed by [$i]. This means that a user can not override these entries. Entries can be marked as deleted if they are followed by [$d]. This is needed if the system administrator has specified a default value but the entry was deleted (made 'non-existant'). In that case we can't just leave the entry out since that would mean we get the default from the system administrator back the next time we read the file. </changed> When an entry is read with readEntry(key, defaultValue), non-existing entries will return "defaultValue" while hasKey(key) will return "false" for such entries. Currently all entries are stored in memory. When TDEConfig is "sync()'ed" it reads the file that it is about to overwrite (for the second time), it then merges in the entries it has in memory and writes the result back to the file. It does NOT update its map of entries in memory with the entries (re)read from disk. It only updates the entries in memory when "reparseConfiguration()" is called. Open Question: The standard writeEntry() function returns the original value, is this needed? Nobody seems to use it. Open Question: The bPersistent flag doesn't seem to be used... could it be removed? Open Question: Is the bNLS flag needed? Localised entries seem to be mostly useful for default files, are they ever created by the user itself? Open Question: Would it be worthwhile to lock a user option that is equal to the default so that it doesn't change when the default changes? KDE3.0 Changes ============== *) writeEntry now returns void instead of QString. *) deleteEntry functions added ------------------------------------------------------------------------------ TDEConfig XT ========== My buzzword picker offered TDEConfig XT ("eXtended Technology") and TDEConfig NG ("Next Generation"). Since the planned changes are ment to be evolutionary rather than revolutionary, TDEConfig NG was dropped. Goals ===== * Have the default value for config entries defined in 1 place. Currently it is not uncommon to have them defined in three places: 1) In the application that reads the setting in order to use it 2) In the settings dialog when reading the setting 3) In the settings dialog when selecting "Use defaults". * Provide type-information about config entries to facilate "KConfEdit" like tools. Ideally type-information also includes range-information; this is even mandatory if enums become an explicit type. * Facilitate the documentation of config entries. Instead of relying on the defaults that are hard-coded in the application, rely on default configuration files being installed in $TDEDIR. The technical changes required for this are very minimal, it is mostly a change in policy. Type information can be provide by preceding every entry with a formalized comment. Work to be done: * TDEConfig needs to be extended to provide access to the default values provided by the default config files. TDEConfig already stores this information internally. (DONE) * A formal comment structure needs to be designed that can convey type-information. Preferably in such a way that it is easily parsable by both machine and user. * TDEConfig needs to be extended, or another class created, that is able to parse the formalized comments. * A tool needs to be developed that can assist developers with the generation and verification of default configuration files including type-information. Drawbacks: * We rely on default configuration files being properly installed. * The user can break applications by making improper modifications to these files. * It is not possible to store defaults settings in a config file that are of a dynamic nature. Examples are settings derived from other settings, e.g. a color setting could be derived from the current color theme, or e.g. the default high score user name which is determined by the user currently logged in. Some random ideas: * The format of the entries would be something like this: [Mail Settings] #!Type=string #!Description=SMTP server to use for sending mail #!Description[nl]=SMTP server voor het versturen van mail Host=wantelbos.zogje.fr - the type could be subclassed more, e.g. strings can be "email", "hostname", "url", etc. - having translations in these files is very arguable. external po's would be better. Class overview TDEConfigBase | v TDEConfigBackend <-----> TDEConfig <------> TDEConfigSkeleton /--< myapp.kcfg | | | / v v |*---------------< TDEConfigINIBackend KSimpleConfig |tdeconfig_compiler \ | \--< myconfig.kcfg-codegen v MyConfig <-----TDEConfigDialogManager----> MyConfigWidget *---< myconfigwidget.ui uic TDEConfigBase: defines API for generic config class TDEConfig: functional generic config class that supports merging of cascaded configuration files KSimpleConfig: functional generic config class without support for cascading configuration files. TDEConfigBackend: defines API for config backend, t.i. the actual handling of the storage method and storage format. TDEConfigINIBackend: the standard (and only one so far) class that implements the config backend using the file-based .INI format for configuration files TDEConfigSkeleton: base class for deriving classes that store application specific options providing type-safety and single-point defaults. MyConfig: An application specific class that offers configuration options to the applications via variables or accessor functions and that handles type-safety and defaults. MyConfig is just an example name, the application developer choses the actual name. myapp.kcfg: File describing the configuration options used by a specific application. myapp.kcfg is just an example name, the application developer choses the actual name. myconfig.kcfg-codegen: Implementation specific code generation instructions for the MyConfig class. myconfig.kcfg-codegen is just an example name, the application developer choses the actual name. TDEConfigDialogManager: Class that links widgets in a dialog up with their corresponding confguration options in a configuration object derived from TDEConfigSkeleton. MyConfigWidget: Dialog generated from a .ui description file. Widget names in the dialog that start with "kcfg_" refer to configuration options.