View source for QtDesignStudio/ComponentRegistry

= Component Registry JSON Format =
<nowiki>**</nowiki>NOTICE** This feature only applies to the Qt Design Studio for Automotive product variant.

== Abstract ==
Qt Design Studio supports extension of its component library through JSON configuration files.

All the configuration files share the same schema, each file declares a self-contained set of categories and components. This document specific the structure, field semantics and constraints.

== Description ==
Beyond the basic built-in QtQuick and QtQuick.Controls items, the component library can be extended with more Qt modules, e.g. Qt Multimedia types, by simply importing the additional modules via Components Library view.

The JSON format described in that document is the contract between the Qt Design Studio component library and the JSON file which is the source of the components. It maps a QML type to its import module, version, visual representation, etc. to enable Design Studio to instantiate and render the types.

The built-in components library is stored in a components_registry.json file: <syntaxhighlight lang="bash">
/qt-automotive-studio/share/qtcreator/qmldesigner/itemLibrary/components_registry.json
</syntaxhighlight>Additional modules for the component library can also be added there:<syntaxhighlight lang="bash">
/qt-automotive-studio/share/qtcreator/qmldesigner/itemLibrary/<module_name>.json
</syntaxhighlight>

== Format Structure Definition ==

=== Top-Level Structure ===
<syntaxhighlight lang="json">
{
  "categories": [<Category>, ...],
  "components": [<Component>, ...]
}
</syntaxhighlight>Where:
{| class="wikitable"
|+
!Field
!Type
!Required
!Description
|-
|categories
|Category[]
|Yes
|List of category definitions
|-
|components
|Component[]
|Yes
|List of component definitions
|}

=== Category Object ===
A Category groups related components under a named section.<syntaxhighlight lang="json">
{
  "id":        <string>,
  "name":      <string>,
  "dimension": <"2D" | "3D">
}
</syntaxhighlight>Where:
{| class="wikitable"
!Field
!Type
!Required
!Description
|-
|id
|string
|Yes
|Unique identifier of the category, referenced by Component.categoryId.
|-
|name
|string
|Yes
|Human-readable display name.
|-
|dimension
|string
|Yes
|Rendering context of the category, i.e. "2D" for standard QtQuick items, "3D" for QtQuick 3D.
|}

==== Example ====
<syntaxhighlight lang="json">
{
  "id": "buttons",
  "name": "Buttons",
  "dimension": "2D"
}
</syntaxhighlight>

=== Component Object ===
A Component represents a single QML type.<syntaxhighlight lang="json">{
  "id":              <string>,
  "name":            <string>,
  "categoryId":      <string>,
  "dimension":       <"2D" | "3D">,
  "requiredImport":  <string>,
  "importVersion":   <string>,
  "iconPath":        <string>,
  "qmlType":         <string>,
  "toolTipTrId":     <string>,
  "properties":      [ <Property>, ... ],
  "sourceFile":      <string>
}</syntaxhighlight>Where:
{| class="wikitable"
!Field
!Type
!Required
!Description
|-
|id
|string
|Yes
|Globally unique identifier for the component, conventionally formatted as <Module>.<TypeName>.
|-
|name
|string
|Yes
|Human-readable display name.
|-
|categoryId
|string
|No
|Reference to the id of a Category declared in the same file.
Components may be uncategorized too, therefore this field is optional.
|-
|dimension
|string
|No
|Specified the component-level dimension in case the categoryId is not specified.
|-
|requiredImport
|string
|Yes
|QML module name to be inserted as an import statement when the component is added to the canvas.
|-
|importVersion
|string
|Yes
|Version of the QML module in <major>.<minor> format.
|-
|iconPath
|string
|Yes
|Path to the icon image file displayed in the component library view. Resolved relative to the location of the JSON file.
|-
|qmlType
|string
|Yes
|The exact QML type name, used to generate the QML instance in the code.
|-
|toolTipTrId
|string
|Yes
|Plain-text description translation Id, to be displayed as a tolltip in the component library view. An empty string is valid too.
|-
|sourceFile
|string
|No
|When present, it is used as the instantiation template instead of generating code from qmlType alone. E.g. might be used with ListView to pre-define the child items.
|-
|properties
|Property[]
|No
|Default property values applied to the QML code when the component is added to the canvas. E.g. a Rectangle might have a width/height pre-defined, so it's visible on the QML preview.
|}

==== Example ====
<syntaxhighlight lang="json">{
  "id": "QtQuick.Controls.Basic.Button",
  "name": "Button",
  "categoryId": "buttons",
  "requiredImport": "QtQuick.Controls",
  "importVersion": "2.0",
  "iconPath": "images/button-icon.png",
  "qmlType": "Button",
  "toolTipTrId": "A button with text.",
  "properties": [
    {"name": "text", "type": "binding", "value": "qsTr(\"Button\")"}
  ]
}</syntaxhighlight>

=== Property Object ===
A Property specifies a default value for a QML property.<syntaxhighlight lang="json">{
  "name":  <string>,
  "type":  <string>,
  "value": <string | number | boolean>
}</syntaxhighlight>Where:
{| class="wikitable"
!Field
!Type
!Required
!Description
|-
|name
|string
|Yes
|The QML property name.
|-
|type
|string
|Yes
|The QML property type.
|-
|value
|<nowiki>string | number | boolean</nowiki>
|Yes
|The default value.
|}

=== Constraints ===

* All id across components array and across all the files must be unique.
* When categoryId is present in a component, it must refer to a category.id declared in the same file.
* A component must specify either a categoryId or a component-level dimension field.