Creating Components

A component is a reusable building block for a UI.

Qt Design Studio comes with preset components that you can use in your UI by creating instances of them. The preset components are similar to Symbols in Sketch or Prefab in Unity.

Some of the preset components represent simple shapes, text, or images, while others represent complex UI controls with full functionality, such as spin boxes or sliders. You can also add instances of preset 3D components to your UIs.

To build your own components, you can modify the properties of the component instances and combine them.

A component is specified within one file (with the file extension ui.qml or .qml). For example, a Button component may be defined in Button.ui.qml. Typically, the visual appearance of a component is defined in a UI file (ui.qml). To create component files, you can use wizard templates, or move component instances into separate component files.

Select Library > Components to view the preset components that have been added to your project. If you cannot find the components you need, add the relevant modules to your project, as described in Adding and Removing Modules.

"Components in Library"

Note: Use as few components as possible. To minimize the number of components, use alias properties and states to create the differences in your component instances. Using component instances instead of duplicating the components reduces the time needed to load and build the application, as well as the size of the application package.

Creating Component Instances

"Creating Component Instances"

  1. Drag-and-drop components from Library (1) to Navigator (2), Form Editor (3), or 3D Editor (4). This creates instances of the components in the current component file.
  2. Select component instances in Navigator to edit the values of their properties in Properties.

    "Properties view"

    For more information, see Specifying Component Properties.

  3. To change the appearance and behavior of the component instances in ways that are not supported in Qt Design Studio by default, you can define custom properties in Connection View > Properties.

    "Connection View Properties tab"

    For more information, see Specifying Dynamic Properties.

  4. To enable users to interact with the component instances, connect the instances to signals in Connection View > Connections. For example, you can specify what happens when a component instance is clicked. For more information, see Connecting Components to Signals.

    "Connection View Connections tab"

  5. To dynamically change the behavior of a component instance when another component instance changes, create bindings between them in Connection View > Bindings. For more information, see Adding Bindings Between Properties.

    "Connection View Bindings tab"

  6. Add states to apply sets of changes to the property values of one or several component instances in the States view. For more information, see Adding States.
  7. Animate the properties of component instances in the Timeline view. For more information, see Creating Animations.

Creating Your Own Components

You can either use project wizard templates to create custom components and controls or move component instances into separate files to turn them into new components that you can create instances of. You can then use the instances of the new components in other components.

Creating Components from Scratch

To use wizard templates to create custom components:

  1. Select File > New File or Project > Qt Quick Files > Qt Quick File > Choose to create a new .qml file.

    Note: Components are listed in the My Components tab in the Library view only if the filename begins with a capital letter.

  2. Click Design to open the component file (ui.qml) in Form Editor.
  3. Drag-and-drop a component from Library to Navigator or Form Editor.
  4. Edit component properties in the Properties view.

    The available properties depend on the component type. You can add properties for components in Connection View > Properties.

  5. To change the appearance and behavior of the component instances in ways that are not supported in Qt Design Studio by default, you can define custom properties in Connection View > Properties.

The following sections contain more information about how to use Form Editor to edit 2D content and 3D Editor to edit 3D scenes, as well as examples of how to create UI controls using instances of basic components:

Creating Custom Controls

You can use project wizard templates to create stylable UI controls based on the components in the Qt Quick Controls module:

You can edit the properties of the controls in all the preset states to apply your own style to them.

"A stylable Dial component"

To create stylable UI controls:

  1. Select File > New File or Project > Files and Classes > Qt Quick Controls.
  2. Select the control to create, and then select Choose.

    Note: Components are listed in Library > Components > My Components only if the filename begins with a capital letter.

  3. Edit component properties in the Properties view.

    The available properties depend on the component type. You can add properties for components in the Properties tab of the Connection View.

For an example of using the Button template to create a button and styling it, see Creating a Push Button in the Log In UI - Part 1 tutorial.

Moving Component Instances into Separate Files

An alternative way of creating reusable components is to move component instances into separate component files (.ui.qml). Right-click a component instance in Navigator or Form Editor, and select Move Component into Separate File in the context menu.

Give the new component a name, and select whether properties are set for the new component or for the original one.

When you select OK, a new component file is created and an instance of the component is added to the code in the current component file. The look of your UI in Form Editor does not change.

To open the new component file for editing the properties that you want to change for all instances of the component, right-click the component, and then select Go into Component in the context menu. For additional ways of opening base components, see Moving Within Components.

For an example of creating a reusable custom component, see Progress Bar. Custom components are listed in Library > Components > My Components, and you can use instances of them to build more components.

Creating UIs for MCUs

Qt for MCUs enables you to use subsets of components to create UIs for devices that are powered by microcontroller units (MCU). The subset of supported components depends on the Qt for MCUs version that you use for development. In this manual, we indicate which components are supported at the time of writing.

To develop for MCUs, create an MCU project. Only the components available on MCUs are displayed in Library > Components. Only a subset of properties is supported for the supported components. The properties that are not available on MCUs are marked in the Properties view by enclosing them in square brackets.

"Components and Image properties supported for MCUs"

For more information about the supported components and their properties, see Qt for MCUs - All QML Types.

Merging Files with Templates

You can merge the current component file against an existing second component file using the second file in a way similar to using a CSS stylesheet.

To use this experimental feature, right-click a component in the Navigator or Form Editor view and select Merge File with Template in the context menu.

"Merge with Template dialog"

In the Template field, select the file to use as a template.

Available under certain Qt licenses.
Find out more.