Archive:Settings System

From Official Kodi Wiki
Revision as of 06:51, 14 March 2014 by NedBot (talk | contribs) (Bot: automated adding of 'enclose="div"' to syntaxhighlight)
Jump to navigation Jump to search

Template:Gotham With Gotham there is a new settings system in use which is more flexible, more powerful and easier extensible than the settings system used in Frodo and earlier versions.

Design

Organisation

The settings system is organized in sections, categories, groups and finally settings. Sections, categories and groups are simply containers with an identifier, a label and a description. TODO


Setting types

TODO

Custom types

TODO

Initialization

TODO

Settings definitions

The settings system needs to be initialized with settings definition files in XML format. It is possible to use multiple settings definition files to initialize the settings system and it supports adding new settings in any of the settings definition files and overwriting setting properties specified in a previously loaded settings definition file.

Sections

A section is a container which can hold multiple categories. Every section has an identifier, a label and a description and is defined in a settings definition file as follows

<section id="section-identifier" label="123" description="456">
  ...
</section>

Categories

A category is a container within a specific section which can hold multiple groups. Every category has an identifier, a label and a description and is defined in a settings defininition file as follows

<section ...>
  <category id="category-identifier" label="123" description="456">
    ...
  </category>
</section>

Groups

A group is a container within a specific category which can hold multiple settings. Every group has an identifier and is defined in a settings definition file as follows

<section ...>
  <category ...>
    <group id="group-identifier">
      ...
    </group>
  </category>
</section>

Settings

TODO

Conditions

Conditions are checks which are defined in C++ and can be used in the XML definition of visibility, dependency et al. of categories, groups and/or settings to change their behaviour depending on certain circumstances. While in the settings definition all conditions are used the same, in C++ there is a difference between static and dynamic conditions.

Static conditions

Static conditions simply consist of an identifier. They are either registered in the settings system usingCSettingsManager::RegisterCondition() or they aren't. Being registered means that the condition is met (i.e. it evaluates to true), not being registered means that the condition is not met (i.e. it evaluates to false).

Dynamic conditions

Dynamic conditions are static C++ methods with an identifier which are evaluated during runtime. They can be registered in the settings system using CSettingsManager::RegisterCondition() and must follow the following method signature:

static bool DynamicCondition(
  const std::string &condition,
  const std::string &value,
  const std::string &settingId
);

The condition parameter is the identifier of the condition (in case the same C++ method needs to handle multiple conditions). The value parameter is a value defined in the definition of the condition. The settingId parameter is the identifier of the setting which invoked the condition.

Option fillers

Option fillers are static C++ methods with an identifier which can be used by settings to define their possible values based on runtime conditions. They can be registered in the settings system usingCSettingsManager::RegisterSettingOptionsFiller().

Integer option fillers

Integer option fillers can be used by integer-based settings and return a list of label-value pairs where the label is the string-representation/-description of the value and the value is an integer. The signature of an integer option filler method in C++ looks like this:

static void IntegerSettingOptionFiller(
  const CSetting *setting,
  std::vector< std::pair<std::string, int> > &list,
  int &current
);

The setting parameter provides the CSetting object of the setting using the option filler. The list parameter needs to be filled by the option filler with the label-value pairs and the current parameter allows the option filler to specify a new value for the setting. This is necessary because with options changing during runtime it may happen that the current value of the setting is no longer a valid option and therefore the setting's value needs to be changed to a valid value.

String option fillers

Stringoption fillers can be used by string-based settings and return a list of label-value pairs where the label is the string-representation/-description of the value and the value is a string. The signature of a string option filler method in C++ looks like this:

static void StringSettingOptionFiller(
  const CSetting *setting,
  std::vector< std::pair<std::string, std::string> > &list,
  std::string &current
);

The setting parameter provides the CSetting object of the setting using the option filler. The list parameter needs to be filled by the option filler with the label-value pairs and the current parameter allows the option filler to specify a new value for the setting. This is necessary because with options changing during runtime it may happen that the current value of the setting is no longer a valid option and therefore the setting's value needs to be changed to a valid value.

GUI integration

TODO