Monitor database structure
Prev | Appendix E. Documents for developers | Next

## Monitor database structure

The monitor database is written in XML, it can be found in the `db` directory of `ddccontrol-db` package.

This directory contains the following files:

- `options.xml`
- `monitor/`%monitor_id%`.xml`

### Control list

#### XML file: `options.xml`

`control` elements (e.g. `“brightness”`) are contained in `group` elements (e.g. `“color settings”`). `group` and `subgroup` elements allow the GUI to separate the controls in different branches on the tree.

`options` attributes:

- `date`: indicates the release date of the current database (YYYYMMDD format).
- `dbversion`: indicates which version of database format is used (must be set to 3).

`group` attributes:

- `name`: full English group name.

`subgroup` attributes:

- `name`: full English subgroup name.
- `pattern`: name of the fullscreen pattern `gddccontrol` must display to help the user to adjust subgroup's controls (optional). For possible values, see `ddccontrol/src/gddccontrol/fspatterns.c`.

`control` attributes:

- `id`: abbreviated control name.
- `name`: full English control name.
- `address`: DDC/CI address (optional).
- `type`: one of these values:
  - `“value”`: The control accepts values in a continuous range (e.g. brightness).
  - `“command”`: An action occurs when the value is set to something greater than `“0”` (e.g. degauss). If you don't define any `value` element in a command control, the default value `“0x01”` will be used.
  - `“list”`: The control accepts a list of values (e.g. OSD language).
- `refresh` (only for list and command controls): Set whether other controls must be refreshed after changing list value or running the command associated with the control (optional). Possible values:
  - `“none”`: Do not refresh anything. (default)
  - `“all”`: Refresh all controls.

`value` attributes:

- `id`: abbreviated value name.
- `name`: full English value name (it is not needed if there is only one value for command controls).
- `value`: DDC/CI control value (optional).

File format:

    <?xml version="1.0"?>
    <options date="%date%" dbversion="3">
      <group name="%groupname%">
        <subgroup name="%subgroupname%" pattern="%patternname%">
          <control id="%control_id%" type="value" name="%control_name%" address="%hex_address%"/>
            <!-- Command using the default 0x01 address -->
          <control id="%control_id%" type="command" name="%control_name%" address="%hex_address%"/>
          <control id="%control_id%" type="command" name="%control_name%" address="%hex_address%">
            <value id="%value_id%" value="%hex_value%"/>
          </control>
          <control id="%control_id%" type="list" name="%control_name%" address="%hex_address%">
            <value id="%value_id%" name="%value_name%" value="%hex_value%"/>
            <value...>
          </control>
          <control ...>
        </subgroup>
      </group>
      <group ...>
    </options>

### Monitor Profiles

#### XML files: `monitor/`%monitor_id%`.xml`

#### `caps` element

The caps attribute is optional. Its format is defined in ACCESS.bus specifications.

To add controls to caps, use the `add` attribute. To remove controls from caps, use the `remove` attribute.

Note remove is handled before add, so if you remove and add a same control, it will finally be in caps.

#### `controls` element

List of controls supported by a monitor (optional if you have an `include` element).

`control` `id` attributes are defined in `options.xml`. If `control` `type` is `“list”` or `“command”` without default values, supported values must be defined.

`address` attribute for `control` elements and `value` attribute for `value` elements are optional if they are defined in the general options file.

The `init` attribute in `monitor` element define the type of the initialization: DDC/CI standard (`“standard”`), or Samsung (`“samsung”`). This attribute is optional, as long as the monitor profile includes another profile which defines this attribute.

You can set a `delay` attribute in `control` elements to set the time in milliseconds to wait after changing the value of this control. If you don't, a default value is used.

#### `include` element

Includes another monitor, manufacturer or standard profile, specified by the `file` attribute.

### Note

Monitor profile are read sequentially. Control and init mode redifinitions are ignored, so define specific controls and init mode before including a generic profile. Caps are also treated sequentially, so if a control is not in CAPS at the time it is defined, it won't be supported by ddccontrol.

File format:

    <?xml version="1.0"?>
    <monitor name="%full_monitor_name%" init="[standard|samsung]">
      <caps add="%add_caps%" remove="%remove_caps%"/>
      <controls>
        <!--- value -->
        <control id="%control_id%" address="%hex_address%" delay="%wait_time%"/>
        <!--- command using a default 0x01 value-->
        <control id="%control_id%" address="%hex_address%" delay="%wait_time%"/>
        <!--- command -->
        <control id="%control_id%" address="%hex_address%" delay="%wait_time%">
          <value id="activate" value="%hex_value%"/>
        </control>
        <!--- list -->
        <control id="%control_id%" address="%hex_address%" delay="%wait_time%">
          <value id="%value_id%" value="%hex_value%"/>
          <value...>
        </control>
        <control...>
      </controls>
      <!--- Including VESA generic profile is generally a good idea. -->
      <include file="VESA"/>
    </monitor>

If a monitor supports exactly the same controls as another one, you can define it as shown:

    <?xml version="1.0"?>
    <monitor name="%full_monitor_name%">
      <caps add="%add_caps%" remove="%remove_caps%"/>
      <include file="%include_monitor_id%"/>
    </monitor>

Prev | Up | Next
Appendix E. Documents for developers | Home | Profile file structure