Appendix E. Documents for developers

Appendix E. Documents for developers
Prev		Next

Table of Contents

Monitor database structure

Control list
Monitor Profiles

Profile file structure

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>