Component Description Language

Wherein we describe how to describe components.

In general, component are created from property trees, which are loaded into the global resource manager at start-up time. This document assumes that they are loaded from JSON files.

A basic component has two fields that it cares about: name and properties. The name is given to identify the property tree so that it can be retrieved later. It also identifies whether the property tree contains the default values, or whether it is a set of overrides (see later.) The properties are the values given to the component.

Each property has three fields: a name, a type, and a value. The name uniquely identifies the property within the component. The type describes in what form the value should be stored, and the value is the value to store.

Available types and how they are stored are:

• string - std::string
• char - char
• estring - yggdrasil::munin::estring
• element - yggdrasil::munin::element
• number - u64
• real - double
• boolean - bool
• array of X, where X is another (non-array) type - std::vector

If the type field is not present, it will be determined to be either estring or array of estring, depending on whether it is an array value or not.

Example:

{
  "name" : "image",  # Declares that this component is the type "image"
  "properties" : [
    { "name" : "background_brush",
      "type" : "element",
      "value" : " " },
    { "name" : "value",
      "type" : "array of estring",
      "value" : [] }
  ]
}

It is possible to create an override set by declaring a cut down set of properties and using a "type" field in the root. This will cause a component to be created with defaults from the given type, but properties will be set using the override set:

{
  "name" : "boxart", # Declares that this component is the type "boxart"
  "type" : "image",  # But is initialized as if it were an "image"
  "properties" : [   # Except that it has the following properties:
    # NOTE: still has default background_brush
    "name" : "value",
    "value" : [
      "o-o",
      "| |",
      "o-o"
    ]
  ]
}

Composite components -- components made by arranging several sub-components together -- have two extra fields:

• layout - chooses a layout to manage the sub-components
• content - an array of descriptions for sub-components

The sub-components are described as if they were other components, but also have a field called "hint" which describes how the component should be arranged in the layout. In a hypothetical example that describes an "OK" button:

{
  "name" : "ok_button",
  "type" : "composite_component",
  "layout" : "framed",
  "content" : [
    { "type" : "solid_frame", # drop a default solid frame here
      "hint" : "outer" },     # this is the outer component of a framed layout
    { "type" : "image",       # drop an image here
      "hint" : "inner",       # in the inner component of a framed layout
      "properties" : [        # But override the image to be " OK ".
        { "value" : [ " OK " ] }
      ]
    }
  ]
}