kdecore/config/DESIGN

   1 If you add a major new feature, suggest using it in
   2 http://techbase.kde.org/Development/Tutorials/KConfig
   3
   4 kconfigdata.h contains definitions of the data formats used by kconfig.
   5
   6 Configuration entries are stored as "KEntry". They are indexed with "KEntryKey".
   7 The primary store is a "KEntryMap" which is defined as a QMap from "KEntryKey"
   8 to "KEntry"
   9
  10 KEntry's are stored in order in the KEntryMap. The most significant sort
  11 criteria is mGroup. This means that all entries who belong in the same group,
  12 are grouped in the QMap as well.
  13
  14 The start of a group is indicated with a KEntryKey with an empty mKey and a
  15 dummy KEntry. This allows us to search for the start of the group and then to
  16 iterate until we end up in another group. That way we will find all entries
  17 of a certain group.
  18
  19 Entries that are localised with the _current_ locale are stored with bLocal
  20 set to true. Entries that are localised with another locale are either not
  21 stored at all (default), or with the localization as part of the key and bRaw
  22 set to true (when reading a file in order to merge it).
  23
  24 Entries that are being read from a location other than the location to
  25 which is written back are marked as "default" and will be added both as
  26 normal entry as well as an entry with the key marked as default.
  27
  28 When the configuration is synced to disk, the current on-disk state is re-read
  29 into a temporary map, updated with dirty (modified) entries from the
  30 current config object's entry map and then written back.
  31
  32
  33 Note that there is a subtle difference between revertToDefault() and deleteEntry().
  34 revertToDefault() will change the entry to the default value set by the system
  35 administrator (Via e.g. $KDEDIR/share/config) or, if no such default was set,
  36 non-existant.
  37 deleteEntry() will make the entry non-existant. If if the system administrator
  38 has specified a default value, the local entry is marked with [$d].
  39
  40 Entries are marked "immutable" if the key is followed by [$i]. This means
  41 that a user can not override these entries.
  42
  43
  44 ------------------------------------------------------------------------------
  45
  46 KConfig XT
  47 ==========
  48
  49 My buzzword picker offered KConfig XT ("eXtended Technology") and KConfig NG
  50 ("Next Generation").  Since the planned changes are ment to be evolutionary
  51 rather than revolutionary, KConfig NG was dropped.
  52
  53 Goals
  54 =====
  55
  56 * Have the default value for config entries defined in 1 place. Currently it is
  57 not uncommon to have them defined in three places:
  58   1) In the application that reads the setting in order to use it
  59   2) In the settings dialog when reading the setting
  60   3) In the settings dialog when selecting "Use defaults".
  61
  62 * Provide type-information about config entries to facilate "KConfEdit" like
  63 tools. Ideally type-information also includes range-information; this is even
  64 mandatory if enums become an explicit type.
  65
  66 * Facilitate the documentation of config entries.
  67
  68 KCoreConfigSkeleton
  69          |
  70          v
  71   KConfigSkeleton           /--< myapp.kcfg
  72          |                 /
  73          |*---------------<
  74          |kconfig_compiler \
  75          |                  \--< myconfig.kcfgc
  76          v
  77      MyConfig <-----KConfigDialogManager----> MyConfigWidget *---< myconfigwidget.ui
  78                                                              uic
  79
  80 KCoreConfigSkeleton/ base class for deriving classes that store application
  81 KConfigSkeleton:     specific options providing type-safety and single-point
  82                      defaults.
  83
  84 MyConfig: An application specific class that offers configuration options
  85           to the applications via variables or accessor functions and that
  86           handles type-safety and defaults. MyConfig is just an example
  87           name, the application developer choses the actual name.
  88
  89 myapp.kcfg: File describing the configuration options used by a specific
  90             application. myapp.kcfg is just an example name, the application
  91             developer choses the actual name.
  92
  93 myconfig.kcfgc: Implementation specific code generation instructions
  94                 for the MyConfig class. myconfig.kcfgc is
  95                 just an example name, the application developer
  96                 choses the actual name.
  97
  98 KConfigDialogManager: Class that links widgets in a dialog up with their
  99                       corresponding confguration options in a configuration
 100                       object derived from KConfigSkeleton.
 101
 102 MyConfigWidget: Dialog generated from a .ui description file. Widget names
 103                 in the dialog that start with "kcfg_" refer to configuration
 104                 options.
 105
 106 See http://techbase.kde.org/Development/Tutorials/Using_KConfig_XT