QML Attached Types | Qt Qml | Qt 6.11.2
Description: Using attached properties and signals in QML

- Qt 6.11
- Qt Qml
- The QML Reference
- The QML Type System
- QML Attached Types
- Qt 6.11.2 Reference Documentation

Singletons in QML ◦ QML Namespaces

# QML Attached Types

Attached properties and signals are a mechanism for objects to be annotated with extra properties or signals that are not part of their base type. Attached properties are accessed through a namespaced syntax that identifies the type providing the attached properties.

## Overview

Some types have properties or signals that can be attached to other objects, providing additional functionality without requiring inheritance. An attached property or signal is accessed by prefixing the property or signal name with the name of the attaching type.

For example, the ListView type has an attached property called `isCurrentItem` that can be accessed on any item within the ListView's delegate:

     ListView {
         width: 240
         height: 320
         model: 3
         delegate: Rectangle {
             width: 100
             height: 30
             color: ListView.isCurrentItem ? "red" : "yellow"
         }
     }

Here, `ListView.isCurrentItem` is an attached property that is made available to each delegate item by the ListView.

## Attached Properties

Attached properties allow you to add properties to objects that are otherwise defined by a base type. The property values are stored externally to the object and accessed through the attaching type's name.

Common examples include:

- ListView attached properties (`isCurrentItem`, `view`)
- GridView attached properties
- Keys attached properties for keyboard event handling
- Component attached properties (`onCompleted`, `onDestruction`)

## Attached Signals

Similar to attached properties, attached signals allow types to provide additional signal handlers to objects. These are commonly used for lifecycle events.

For example, the Component type provides attached signals:

     Rectangle {
         Component.onCompleted: {
             console.log("Rectangle creation completed")
         }

         Component.onDestruction: {
             console.log("Rectangle is being destroyed")
         }
     }

## Creating Attached Properties in C++

To create attached properties for your own types from C++, you need to:

1. Create an attached properties class that inherits from QObject
2. Implement the attached properties in this class
3. Add the `QML_ATTACHED` macro to your main type
4. Implement a static `qmlAttachedProperties()` method

Example:

     class MyAttachedType : public QObject
     {
         Q_OBJECT
         Q_PROPERTY(int value READ value WRITE setValue NOTIFY valueChanged)
         QML_ANONYMOUS

     public:
         MyAttachedType(QObject *parent = nullptr) : QObject(parent) {}

         int value() const { return m_value; }
         void setValue(int value)
         {
             if (m_value != value) {
                 m_value = value;
                 emit valueChanged();
             }
         }

     signals:
         void valueChanged();

     private:
         int m_value = 0;
     };

     class MyType : public QObject
     {
         Q_OBJECT
         QML_ELEMENT
         QML_ATTACHED(MyAttachedType)

     public:
         static MyAttachedType *qmlAttachedProperties(QObject *object)
         {
             return new MyAttachedType(object);
         }
     };

Usage in QML:

     Item {
         MyType.value: 42
     }

If the attaching type (`MyType` in this case) does nothing but attach properties to other objects, you can phrase this as a single class:

     class MyType : public QObject
     {
         Q_OBJECT
         Q_PROPERTY(int value READ value WRITE setValue NOTIFY valueChanged)
         QML_ELEMENT
         QML_ATTACHED(MyType)

     public:
         static MyType *qmlAttachedProperties(QObject *object)
         {
             return new MyType(object);
         }

         MyType(QObject *parent = nullptr) : QObject(parent) {}

         int value() const { return m_value; }
         void setValue(int value)
         {
             if (m_value != value) {
                 m_value = value;
                 emit valueChanged();
             }
         }

     signals:
         void valueChanged();

     private:
         int m_value = 0;
     };

## When to Use Attached Properties

Attached properties are useful when:

- You want to add context-specific information to items (like ListView's `isCurrentItem`)
- Properties logically belong to a container or context rather than the item itself
- You want to avoid cluttering base types with specialized properties

See also QML Object Types, The QML Type System, and Defining QML Types from C++.

Singletons in QML ◦ QML Namespaces