DarkRadiant XMLRegistry

The XMLRegistry is the central storage for all kinds of variables, settings, preferences, game defaults, etc. As the name states, all the content is stored in XML format, which has some conveniences when accessing, changing and saving the content.

Accessing the Registry

The XMLRegistry plugin (interface defined in iregistry.h) implements some convenient methods to retrieve and save values into the keys. Use the GlobalRegistry() method to retrieve a reference to the XMLRegistry instance.

GlobalRegistry().get(<key>)        // returns a string
GlobalRegistry().getFloat(<key>)   // returns a float
GlobalRegistry().getInt(<key>)     // returns an int

The above methods try to load the value from the registry and convert them via boost::lexical_cast, if required. If the key is not found in the specified place, an empty value is returned as default ("" or 0.0 or 0).

To save values into the registry, the set methods form the counterparts to the above functions:

GlobalRegistry().set(<key>, <value>)       // save the string into <key>
GlobalRegistry().setFloat(<key>, <value>)  // save the floating point value to <key>
GlobalRegistry().setInt(<key>, <value>)    // save the integer value to <key>

If the specified key does not exist, it is created and all non-existing parent nodes are created recursively as well. So you don't have to create your key before you save a value into it.

Keys

The following is an example of a valid key:

user/ui/showAllLightVolumes

and refers to this internal node:

<user>
  <ui>
    <showAllLightRadii value="1" />   
  </ui>
</user>

Be sure to always omit the leading slash, so don't use /user/ui/... (see below).

The internal XML tree

As a valid XML document consists of exactly one global parent node, the toplevel node is called <darkradiant>. However, you don't have to specify this toplevel node, as it is added automatically by the XMLRegistry.

So, the key user/ui/showAllLightVolumes is automatically recognised as relative path and becomes /darkradiant/user/ui/showAllLightRadii before being passed to the libxml functions.

You of course can access the keys with absolute xpaths (/darkradiant/user/ui/showAllLightRadii for example), but this is not recommended, as the toplevel node is maintained by the registry module only.

XPath Syntax

The libxml2 library is capable of interpreting the XPath syntax (see reference). Use the findXPath() and deleteXPath() methods to retrieve (or delete) certain paths. The findXPath() method returns an xml::Node structure which in turn provides some methods for adding children, getting attribute values and so on.