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