Qt Qml Reference Documentation

Functions to register C++ types to QML

Registering C++ types to QML

Alias cycle

Alias property is part of an alias cycle

What happened?

Why is this bad?

Example

Android: Activity

Android: ClassCastException

Android: InvalidParameterException

Android: SYSTEM_ALERT_WINDOW

Android: View

Android: View binding

Attached property reuse

Using attached type already initialized in a parent scope

What happened?

Why is this bad?

Example

Cannot access singleton as a property of an object

Access singleton via object

What happened?

Why is this bad?

Example

Changes to Qt QML

QML language

URL resolution

Variant Properties

Source Incompatible API Changes

Changed API

Removed API

Component is missing a required property

Component is missing a required property

What happened?

Why is this bad?

Example

Configuring the JavaScript Engine

{QV4_GC_TIMELIMIT}

Creating C++ Plugins for QML

Creating a Plugin

Reference

Data Type Conversion Between QML and C++

QTime to JavaScript Date

Data Ownership

Basic Qt Data Types

QObject-derived Types

Conversion Between Qt and JavaScript Types

QVariantList and QVariantMap to JavaScript Array-like and Object

QDateTime to JavaScript Date

QDate and JavaScript Date

QTime and JavaScript Date

Sequence Type to JavaScript Array

QByteArray to JavaScript ArrayBuffer

Value Types

Enumeration Types

Enumeration Types as Signal and Method Parameters

Defining JavaScript Resources in QML

Code-Behind Implementation Resource

Shared JavaScript Resources (Libraries)

Defining Object Types through QML Documents

Defining an Object Type with a QML File

Naming Custom QML Object Types

Custom QML Type Definition

Inline Components

Importing Types Defined Outside the Current Directory

Accessible Attributes of Custom Types

Defining QML Types from C++

Integrating QML and C++ - Attached Properties

Registering C++ Types with the QML Type System

Preconditions

Registering an Instantiable Object Type

Using CMake

Using QMake

Registering Value Types

Value Types with Enumerations

Registering Non-Instantiable Types

Registering Singleton Objects with a Singleton Type

Final properties

Type Revisions and Versions

Registering Extension Objects

Registering Foreign Types

Defining QML-Specific Types and Attributes

Providing Attached Properties

Steps for Implementing Attached Objects

Implementing Attached Objects: An Example

Propagating Attached Properties

Property Modifier Types

Property Value Sources

Specifying Default and Parent Properties for QML Object Types

Defining Visual Items with the Qt Quick Module

Receiving Notifications for Object Initialization

Deprecated

Deprecated binding or type

What happened?

Why is this bad?

Duplicate bindings

Duplicate interceptor on property

What happened?

Why is this bad?

Example

Duplicate value source on property

What happened?

Why is this bad?

Example

Cannot combine value source and binding

What happened?

Why is this bad?

Example

Duplicate id

Found a duplicated id

What happened?

Why is this bad?

Example

Duplicated name

Duplicated Property Name

What happened?

Why is this bad?

Example

Duplicated signal mame

What happened?

Why is this bad?

Example

Dynamic QML Object Creation from JavaScript

Creating Objects Dynamically

Creating a Component Dynamically

Creating an Object from a String of QML

Maintaining Dynamically Created Objects

Deleting Objects Dynamically

ECMA-262

ECMAScript Specification of Date

Embedding C++ Objects into QML with Context Properties

Setting a Simple Context Property

Setting an Object as a Context Property

Exposing Attributes of C++ Types to QML

Integrating QML and C++ - Grouped Properties

Data Type Handling and Ownership

Exposing Properties

Notes on Use of Notify Signals

Properties with Object Types

Properties with Object-List Types

Grouped Properties

Exposing Methods (Including Qt Slots)

C++ methods and the 'this' object

Exposing Signals

Exposing State from C++ to QML

Using Singletons

Using Object Properties

Felgo QML Hot Reload Tool

Font Awesome

GammaRay Manual

Id quotation

Ids do not need quotation marks

What happened?

Why is this bad?

Example

Identified Modules

Locally Installed Identified Modules

An Example

Remotely Installed Identified Modules

Semantics of Identified Modules

Import Statements

Syntax of an Import Statement

Module (Namespace) Imports

C++ Module Imports

Importing into a Qualified Local Namespace

Directory Imports

JavaScript Resource Imports

JavaScript Resources from Modules

Further Information

QML Import Path

Debugging

Important C++ Classes Provided By The Qt Qml Module

QML Runtime

The QQmlEngine Class

The QQmlContext Class

Dynamic Object Instantiation and Expression Evaluation

The QQmlComponent Class

The QQmlExpression Class

Usage of the Classes within QML Applications

Importing JavaScript Resources in QML

Importing a JavaScript Resource from a QML Document

Imports Within JavaScript Resources

Importing a JavaScript Resource from Another JavaScript Resource

Importing a QML Module from a JavaScript Resource

Importing QML Document Directories

Local Directory Imports

An Example

The Implicit Import

Remotely Located Directories

Directory Listing qmldir Files

Incompatible type

Cannot assign to default property of incompatible type

What happened?

Why is this bad?

Example

On-binding for property has wrong type

What happened?

Why is this bad?

Example

Construction from string is deprecated; Use structured value type construction instead

What happened?

Why is this bad?

Example

Function without return type annotation returns

What happened?

Why is this bad?

Example

Cannot assign binding/object/literal

What happened?

Why is this bad?

Example

Inheritance cycle

Component is part of an inheritance cycle

What happened?

Why is this bad?

Example

Integrating QML and JavaScript

JavaScript Expressions

Dynamic QML Object Creation from JavaScript

JavaScript Resources

JavaScript Imports

JavaScript Host Environment

Configuring the JavaScript engine

Integrating with JavaScript values from C++

QJSValue as a Container Type

Primitive and Managed Values

QJSManagedValue

QJSPrimitiveValue

Interacting with QML Objects from C++

Loading QML Objects from C++

Accessing QML Objects via well-defined C++ Interfaces

Singletons

Initial properties

Accessing Loaded QML Objects by Object Name

Accessing Members of a QML Object Type from C++

Properties

Invoking QML Methods

Connecting to QML Signals

Invalid qmllint directives

Invalid qmllint directive provided

What happened?

Why is this bad?

Example

Qmllint directive on unknown category

What happened?

Why is this bad?

Example

JavaScript Expressions in QML Documents

JavaScript in property bindings

JavaScript in signal handlers

JavaScript in standalone functions

JavaScript in custom methods

Functions defined in a JavaScript file

Connecting signals to JavaScript functions

JavaScript in application startup code

JavaScript Host Environment

Common Base

Type annotations and assertions

QML Global Object

JavaScript Objects and Functions

JavaScript Environment Restrictions

JavaScriptCore Macro Assembler

Kotlin: Int

Kotlin: String

Legacy Modules

Installed Legacy Modules

Located Legacy Modules

List of JavaScript Objects and Functions

The Global Object

Value Properties

Function Properties

Constructor Properties

Other Properties

The Object Object

Object Constructor

Function Properties

Object Prototype

Function Properties

Function Objects

Function Prototype

Function Properties

Array Objects

Array Prototype Object

Function Properties

String Objects

String Prototype Object

Function Properties

Boolean Objects

Boolean Prototype Object

Function Properties

Number Objects

Number Prototype Object

Function Properties

The Number Object

Value Properties

Function Properties

The Math Object

Value Properties

Function Properties

Date Objects

Date Prototype Object

Function Properties

RegExp Objects

RegExp Prototype Object

Function Properties

Error Objects

Error Prototype Object

Value Properties

Function Properties

The JSON Object

Function Properties

Making Applications Scriptable

Scripting Classes

Basic Usage

Making a QObject Available to the Script Engine

Implications for Application Security

Memory Management in the JavaScript Engine

Introduction

Basic Principles

QObject-based Types

Object Allocation

Internal Classes

Garbage Collection

Analyzing Memory Usage

Missing enum entry

Is not an entry of enum

What happened?

Why is this bad?

Example

Missing property

Can't assign to non-existent default property

What happened?

Why is this bad?

Example

Property does not exist

What happened?

Why is this bad?

Example

Member not found on type

What happened?

Why is this bad?

Example

Missing type

Cannot deduce type of alias

What happened?

Why is this bad?

Example

No type found for property

What happened?

Why is this bad?

Example

Modern QML modules

Use qt_standard_project_setup

Use the new standard resource path prefix

Use loadFromModule to load your QML files

Replace OUTPUT_DIRECTORY and IMPORT_PATH with DEPENDENCIES TARGET

Module Definition qmldir Files

Contents of a Module Definition qmldir File

Module Identifier Declaration

Object Type Declaration

Internal Object Type Declaration

JavaScript Resource Declaration

Plugin Declaration

Plugin Classname Declaration

Type Description File Declaration

Module Dependencies Declaration

Module Import Declaration

Designer Support Declaration

Preferred Path Declaration

Versioning Semantics

Example of a qmldir File

Type Description Files

Multiline strings

String contains unescaped line terminator, which is deprecated

What happened?

Why is this bad?

Example

Non-list property

Cannot assign multiple objects to a default non-list property

What happened?

Why is this bad?

Example

Nullish Coalescing

Optional Chaining

Overview - QML and C++ Integration

Choosing the Correct Integration Method Between C++ and QML

Exposing Attributes of C++ Classes to QML

Defining QML Types from C++

Embedding C++ Objects into QML with Context Properties

Interacting with QML Objects from C++

Data Type Conversion Between QML and C++

Port QML modules to CMake

Identify issues to fix

Prepare the project for qt_add_qml_module

Make qt_add_qml_module available in CMake

Use qt_standard_project_setup

Use qt_add_qml_module

Add a QML module to your executable target

Add a QML module to your library target

Use loadFromModule to load your QML files

Remove handwritten qmldir files

Remove qmltypes files generated by qmlplugindump

Remove handwritten type registration plugins

Remove qrc files

Replace directory imports with QML module imports

Property Binding

Overview

Creating Property Bindings from JavaScript

Debugging overwriting of bindings

Using <@keyword>this</@keyword> with Property Binding

QML Basic Types

QML Basic Types

QML Documents

Structure of a QML Document

Syntax of the QML Language

Defining Object Types Through QML Documents

Resource Loading and Network Transparency

Scope and Naming Resolution

QML Enumerations

Using Enumerations in QML

QML Global Object

QML Language Server

\QMLLS Reference

Supported Features

Linting

Formatting

Finding Definitions

Finding Usages

Renaming

Suggesting Autocompletion Items

Tracking Changes in C++ Files

Documentation Hints

Setting up the QML Language Server in Your Editor

Setting up the Build Directory

Setting up the import paths

Setting up the documentation path

Disabling Automatic CMake Builds

Configuration File

Known Limitations

QML Modules

Defining a QML Module

Supported QML Module Types

Providing Types and Functionality in a C++ Plugin

QML Namespaces

QML Object Attributes

QML.id

Attributes in Object Declarations

The id Attribute

Property Attributes

Defining Property Attributes

Valid Types in Custom Property Definitions

Assigning Values to Property Attributes

Value Assignment on Initialization

Imperative Value Assignment

Static Values and Binding Expression Values

Type Safety

Special Property Types

Object List Property Attributes

Grouped Properties

Property Aliases

Considerations for Property Aliases

Property Aliases and Types

Default Properties

Required Properties

Read-Only Properties

Property Modifier Objects

Signal Attributes

Defining Signal Attributes

Property Change Signals

Signal Handler Attributes

Property Change Signal Handlers

Method Attributes

Defining Method Attributes

Attached Properties and Attached Signal Handlers

A Note About Accessing Attached Properties and Signal Handlers

Enumeration Attributes

QML Object Types

Defining Object Types from QML

Defining Object Types Through QML Documents

Defining Anonymous Types with Component

Defining Object Types from C++

QML Sequence Types

QML Syntax Basics

Import Statements

Object Declarations

Child Objects

Comments

QML Value Type and Sequence References

QML Value Types

Available Value Types

Built-in Value Types Provided By The QML Language

Value Types Provided By QML Modules

Property Change Behavior for Value Types

QML script compiler

qmlcachegen

qmlsc

static mode

direct mode

Limitations when compiling JavaScript to C++

Obtaining statistics about the compilation of functions and bindings

QML type compiler

Using qmltc in a QML application

Compiling QML code with qmltc

Using the Generated C++

Using QQmlComponent

Using qmltc-generated class

QML engine

Generated Output Basics

Known Limitations

QTP0001

qt_cmake_policy_qtp0001

QTP0004

qt_cmake_policy_qtp0004

QTP0005

qt_cmake_policy_qtp0005

QT_QMLLINTER_TARGETS_FOLDER

QT_QMLTC_FILE_BASENAME

QT_QML_GENERATE_ANDROID_JAVA_CLASS

QT_QML_GENERATE_AOTSTATS

QT_QML_GENERATE_QMLLS_INI

QT_QML_INTERNAL_TYPE

QT_QML_NO_CACHEGEN

QT_QML_OUTPUT_DIRECTORY

QT_QML_SINGLETON_TYPE

QT_QML_SKIP_CACHEGEN

QT_QML_SKIP_QMLDIR_ENTRY

QT_QML_SKIP_QMLLINT

QT_QML_SKIP_TYPE_COMPILER

QT_QML_SOURCE_TYPENAME

QT_QML_SOURCE_VERSIONS

QmlLive Manual

Qt Creator: QML Debugger

Qt Creator: QML Preview On Desktop

Qt Creator: QML Profiler

Qt Qml

Using the Module

QML API

C++ API

Building with CMake

Building with qmake

Registering QML Types and QML Modules

Tweaking the engine

Articles and Guides

Reference

Licenses and Attributions

Qt Quick Compiler

The QML type compiler

The QML script compiler

Summary

Qt Quick I18N

Marking Text as Translatable

Enabling Translation

Creating Translation Files

Adding Translations

Quick: Attached property type

Attached property must be attached to an object deriving from a particular type

What happened?

Why is this bad?

Example

Readonly property

Cannot assign to read-only property

What happened?

Why is this bad?

Example

Recursion depths errors

Maximum statement or expression depth exceeded

What happened?

Why is this bad?

Example

Resource Loading and Network Transparency

Relative vs. Absolute URLs

QRC Resources

Limitations

Implications for Application Security

Restricted type

You can't access an unscoped enum from here

What happened?

Why is this bad?

Example

Scope and Naming Resolution

JavaScript Scope

Type Names and Imported JavaScript Files

Binding Scope Object

Component Scope

Component Instance Hierarchy

Overridden Properties

JavaScript Global Object

Signal and Handler Event System

Receiving signals with signal handlers

Property change signal handlers

Signal parameters

Using the Connections type

Attached signal handlers

Adding signals to custom QML types

Connecting signals to methods and signals

Signal to signal connect

Signal handler parameters

Type of parameter in signal was not found

What happened?

Why is this bad?

Example

Signal handler has more formal parameters than the signal it handles

What happened?

Why is this bad?

Example

The signal has a parameter of the same name

What happened?

Why is this bad?

Example

Missing Arguments

Swapped arguments

Singletons in QML

How can singletons be created in QML?

Defining singletons in QML

Using qt_add_qml_module (CMake)

Without qt_add_qml_module

Defining singletons in C++

Registering a class to provide singletons

Exposing an existing object as a singleton

Imperative type registration

Accessing singletons

Guidelines for (not) using singletons

Grouping together related data

Use object instances

Passing initial state

Squish GUI Test Automation Tool

Structure of a QML Document

Pragmas

Singleton

ListPropertyAssignBehavior

ComponentBehavior

FunctionSignatureBehavior

NativeMethodBehavior

ValueTypeBehavior

Translator

Imports

The Root Object Declaration

Syntax

Nested inline components are not supported

What happened?

Why is this bad?

Example

Inline component declaration must be followed by a typename

What happened?

Why is this bad?

Example

Invalid alias expression: an initializer is needed

What happened?

Why is this bad?

Example

Invalid alias expression: only ids and field member expressions can be aliased

What happened?

Why is this bad?

Example

Id must be followed by an identifier

What happened?

Why is this bad?

Example

Failed to parse id

What happened?

Why is this bad?

Example

Declaring an object which is not a QML object as a list member

What happened?

Why is this bad?

Example

Enums declared inside of inline components are ignored

What happened?

Why is this bad?

Example

Unknown argument to pragma

What happened?

Why is this bad?

Example

The QML Disk Cache

The QML Reference

The QML Type System

QML Value Types

QML Object Types

QML Sequence Types

Enumerations

QML Namespaces

JavaScript Types

Top level component

QML top level type can't be Component

What happened?

Why is this bad?

Example

Uncreatable type

Namespace must start with an upper case letter

What happened?

Why is this bad?

Example

Singleton type is not creatable

What happened?

Why is this bad?

Example

Type is not creatable

What happened?

Why is this bad?

Example

Attached type misuse

Interface misuse

Unqualified

Unqualified access

What happened?

Why is this bad?

Example

Unknown attached/grouped property scope

What happened?

Why is this bad?

Example

No matching signal found for handler

What happened?

Why is this bad?

Example

Implicitly defining signal handler in Connections is deprecated

What happened?

Why is this bad?

Example

Unresolved alias

Unresolved alias

What happened?

Why is this bad?

Example

Unresolved type

For QML module users

What happened?

Why is this bad?

Examples

Typo

Missing import statement

For QML module authors

What happened?

Why is this bad?

Examples

Missing type registration

Missing QML module dependency

Unused imports

Unused import

What happened?

Why is this bad?

Example

Use proper function

Property is a variant property: It may or may not be a method

What happened?

Why is this bad?

Example

Property is a QJSValue property: It may or may not be a method

What happened?

Why is this bad?

Example

Signal is shadowed by a property

What happened?

Why is this bad?

Example

Method is shadowed by a property

Slot is shadowed by a property

Property is not a method

What happened?

Why is this bad?

Example

Var used before declaration

Variable is used here before its declaration

What happened?

Why is this bad?

Example

W3Schools JavaScript Reference

Warnings occurred while importing

Failed to import module

What happened?

Why is this bad?

Examples

Typo In The Import Statement

User-defined module that was not built

Wrong import path

QT_QML_GENERATE_QMLLS_INI not being sert

Missing module

Component was not found

What happened?

Why is this bad?

Examples

Typo in the component name

Missing import statement

Import qualifier must start with a capital letter

What happened?

Why is this bad?

Examples

Unknown import syntax

What happened?

Why is this bad?

Examples

With

With statements

What happened?

Why is this bad?

Example

Writing QML Extensions with C++

Opening the Tutorial Sources

Creating Project from Scratch

Chapter 1: Creating a New Type

Class Declaration

qmake Setup

CMake Setup

Class Implementation

QML Usage

Project Build

Chapter 2: Connecting to C++ Methods and Signals

Chapter 3: Adding Property Bindings

Chapter 4: Using Custom Property Types

Chapter 5: Using List Property Types

Chapter 6: Writing an Extension Plugin

Chapter 7: Summary

Writing QML Modules

Multiple QML Modules in One Binary

Versions

If you add versions, add them everywhere

Versions are not transitive

Qualified access does not honor versioning

Versions and revisions

Exporting multiple major versions from the same module

Custom Directory Layouts

Eliminating Run Time File System Access

Integrating custom QML plugins

Writing advanced QML Extensions with C++

BirthdayParty Base Project

Inheritance and Coercion

Default Properties

Grouped Properties

Attached Properties

Property Value Source

Foreign objects integration

install(FILES)

prefixed-import-type

prefixed-import-type

What happened?

Why is this bad?

Example

qml

The qml utility

options

qmlcachegen

qmlformat

qmlformat

Options

Arguments

Details

Output

Grouping Properties, Functions, and Signals Together

Settings File

Formatting a List of Files

qmlimportscanner

qmlimportscanner

qmllint

qmllint Reference

Compiler warnings

Marking components and properties as deprecated

Disabling warnings inline

Settings

Scripting

qmlpreview

The Qml Preview

options

Arguments

Details

Enable QML Debugging

qmlprofiler

qmlprofiler

qmltyperegistrar

qt_add_qml_module

RESOURCE_PREFIX

NO_RESOURCE_TARGET_PATH

PAST_MAJOR_VERSIONS

IMPORT_PATH

PLUGIN_TARGET

NO_CREATE_PLUGIN_TARGET

CLASS_NAME

NO_GENERATE_PLUGIN_SOURCE

NO_PLUGIN

NO_PLUGIN_OPTIONAL

OUTPUT_DIRECTORY

ENABLE_TYPE_COMPILER

qt6_add_qml_module

Synopsis

Description

Target Structure

Separate backing and plugin targets

Plugin target with no backing target

Executable as a QML module

Auto-generating qmldir and typeinfo files

Caching compiled QML sources

Linting QML sources

Naming conventions for <@op>.</@op>js files

Singletons

Compiling QML to C++ with QML type compiler

Arguments

Required arguments

Versions

Adding sources and resources to the module

Registering past major versions

Declaring module dependencies

Targets and plugin targets

Automatic type registration

Qt Quick Designer compatibility

Keeping module versions in sync

C++ namespaces of generated code

qmlimportscanner and NO_IMPORT_SCAN

Arguments for qmltc

qt_add_qml_plugin

qt6_add_qml_plugin

Synopsis

Description

Arguments

qt_deploy_qml_imports

qt6_deploy_qml_imports

Synopsis

Description

Example

qt_generate_deploy_qml_app_script

qt6_generate_deploy_qml_app_script

Synopsis

Description

Example

qt_generate_foreign_qml_types

qt6_generate_foreign_qml_types

Synopsis

Description

qt_import_qml_plugins

qt6_import_qml_plugins

Synopsis

Description

qt_query_qml_module

qt6_query_qml_module

Synopsis

Description

Arguments

Example

qt_target_compile_qml_to_cpp

qt6_target_compile_qml_to_cpp

qt_target_qml_sources

PREFIX

QT_RESOURCE_ALIAS

qt_target_qml_sources_example

qt6_target_qml_sources

Synopsis

Description

Arguments

Source File Properties

svgtoqml

Overview

Usage

Comparison to other options

Comparison to Qt SVG

Comparison to VectorImage

Comparison to PathSvg

Binding

Binding to an Inaccessible Property

Conditional Bindings

Component

Creation Context

Connections

Date

Format Enumeration Values

Further Notes

Locale

FormatType

Locale String Format Types

LoggingCategory

Number

Qt

QmlGlobalQtObject

Enums

Types

Date/Time Formatters

Dynamic Object Creation

Other Functions

QtObject

Timer

XMLHttpRequest

Sending requests

Accessing local files

responseXML document

bool

date

double

int

list

Using the list Type

point

real

rect

size

string

url

var

Change Notification Semantics

Property Value Initialization Semantics

variant

void

CMake Global Properties in Qt6 Qml

CMake Source File Properties in Qt6 Qml

CMake Global Variables in Qt6 Qml

QML Lint Warning and Errors

Qt Qml Tooling

Developer tools

Designer tools

Internal tools

All Qml tools

Qt Qml C++ Classes

Qt Qml QML Types

Importing QtQml

Value Types

Sequence Types

Object Types