Introduction

OpenGPI tries to simplify and speed up the creation of configuration editors. To enable a certain kind of flexibility, developers can write the specification for their configuration menu as a simple XML file. Using a good editor will be quite advantageous, because it can assist with autocomplete and other features.

Basic Terms

OpenGPI uses files named "descriptions" to create its interfaces. These descriptions consist of two basic elements: Blocks and keys. Blocks are just a way to organize the keys in sub-groups, similar to what is done in most configuration files today, anyway. To give you an impression of the syntax, let's look at the most basic description file we can create:

<?xml version="1.0"?>

<description xmlns="http://numhpc.math.kit.edu">
    <version>0.1</version>
    <block>
        <name>BasicBlock</name>
        <enabled>true</enabled>
         <key>
            <name>MeshFile</name>
            <enabled>true</enabled>
            <type>spinbox</type>
            <default>1</default>
         </key>
     </block>
</description>

If you want, you can validate this file against the description as follows:

Change to the OpenGPI base directory
create the file "description_minimal.xml" with the above content
call "python src/validate.py data/description.xsd description_minimal.xml"

This should return "XML file is valid."

As you can see, the general format is not that complicated.

Possible Tags

All these elements are block elements, i.e. they contain other elements. These child elements are listed here, each with their description following. The general structure can also be looked up in data/description.xsd

<description>

This is the most basic block all descriptions contain.

Needed children:

<block>

Allowed children:

<version> "This may be any string you may want to use to version your description files"

<block>

This element may contain other <block> or <key> elements. Needed children:

<name> "The reference name. Displayed, when no display name is given"

<enabled> "Decides if this block is enabled, i.e. shown. May be 'true' or 'false'"

Allowed children:

<displayname> "The name to display for this block"

other <block>s

<key> elements, see section "<key>"

<key>

This is the most important tag for us.

Needed children:

<name> "The name, also used to reference and displayed if there is no display name"
<enabled> "Decides if this key is enabled, i.e. shown. May be 'true' or 'false'"
<type> "The type of this key. May be 'text', 'combobox', 'spinbox', 'file'"
<default> "The default value for this key"

Allowed children:

<dep> "Dependencies triggered by certain values of this key"
<displayname> "The name to display for this key"
<info> "An explanation which may be provided to the user"

Depending on the type, there may be additional children elements. WARNING: Compatibility between type and the children is not currently being checked by the script.

"combobox": Needed children:

<defaultlist> "The list of default options" (see <itemlist>)

Allowed children:

<currentlist> "Depending on the current values in the defaults for all keys, you can provide an adjusted list of options to be displayed" (see <itemlist>)

"spinbox": Allowed children - <defaultmin> "Minimum to set when evaluating all dependencies" - <defaultmax> "Maximum to set when evaluating all dependencies" - <min> "Minimum value for the default settings. Usually not needed to be applied" - <max> "Maximum value for the default settings. Usually not needed to be applied"

<itemlist>

Itemlists are used for the default- and currentlist tags. Itemlists contain <item>-tags. To enable easier reference, one may supply the attribute 'value' to the item.

<item value="itsValue">Its display value</item>

<dep>

Dependencies are specified for certain values in each key. Needed children:

<value> "The value for which to execute this dependency

<target> "Reference to the targets. This may have arbitrarily many"

<target>

Depending on the action, the target tag may contain only a <targetblock>, or an additional <targetkey>. It also contains an <action>. For all actions except "enableblock", a <targetkey> is needed.

<action>

This tag may contain one of each of the following:

<enableblock> "This will enable a block"
<enablekey> "This will enable a key"
<setvalue> "Set the key to this value"
<setmin> "Set the minimum for this key to this value"
<setmax> "Set the maximum for this key to this value"
<insertitems> "Add these items to the option list"
<removeitems> "Remove these items from the option list"

Be careful that for one target, you only specify either insertitems or removeitems. Specifying both does not have a specified behaviour, and the implemented one _may_ change.