QtDesignStudio/ComponentRegistry

Component Registry JSON Format

**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:

/qt-automotive-studio/share/qtcreator/qmldesigner/itemLibrary/components_registry.json

Additional modules for the component library can also be added there:

/qt-automotive-studio/share/qtcreator/qmldesigner/itemLibrary/<module_name>.json

Format Structure Definition

Top-Level Structure

{
  "categories": [<Category>, ...],
  "components": [<Component>, ...]
}

Where:

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.

{
  "id":        <string>,
  "name":      <string>,
  "dimension": <"2D" | "3D">
}

Where:

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

{
  "id": "buttons",
  "name": "Buttons",
  "dimension": "2D"
}

Component Object

A Component represents a single QML type.

{
  "id":              <string>,
  "name":            <string>,
  "categoryId":      <string>,
  "dimension":       <"2D" | "3D">,
  "requiredImport":  <string>,
  "importVersion":   <string>,
  "iconPath":        <string>,
  "qmlType":         <string>,
  "toolTipTrId":     <string>,
  "properties":      [ <Property>, ... ],
  "sourceFile":      <string>
}

Where:

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

{
  "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\")"}
  ]
}

Property Object

A Property specifies a default value for a QML property.

{
  "name":  <string>,
  "type":  <string>,
  "value": <string | number | boolean>
}

Where:

Field	Type	Required	Description
name	string	Yes	The QML property name.
type	string	Yes	The QML property type.
value	string | number | boolean	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.