QQuickAttachedPropertyPropagator Class | Qt Quick Controls | Qt 6.11.2
Description: The QQuickAttachedPropertyPropagator class provides a way to propagate attached properties.

- Qt 6.11
- Qt Quick Controls
- C++ Classes
- QQuickAttachedPropertyPropagator
- Qt 6.11.2 Reference Documentation

# QQuickAttachedPropertyPropagator Class

The QQuickAttachedPropertyPropagator class provides a way to propagate attached properties. More...

Header: | `#include <QQuickAttachedPropertyPropagator>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS QuickControls2)` `target_link_libraries(mytarget PRIVATE Qt6::QuickControls2)`
qmake: | `QT += quickcontrols2`
Since: | Qt 6.5
Inherits: | QObject

- List of all members, including inherited members

## Public Functions

| QQuickAttachedPropertyPropagator(QObject *parent = nullptr)
virtual | ~QQuickAttachedPropertyPropagator()
QList<QQuickAttachedPropertyPropagator *> | attachedChildren() const
QQuickAttachedPropertyPropagator * | attachedParent() const

## Protected Functions

virtual void | attachedParentChange(QQuickAttachedPropertyPropagator *newParent, QQuickAttachedPropertyPropagator *oldParent)
void | initialize()

## Detailed Description

In QML, it is possible to attach properties and signal handlers to objects. Providing Attached Properties goes into more detail about how to expose your own C++ attached types.

QQuickAttachedPropertyPropagator provides an API to propagate attached properties from a parent object to its children, similar to font and palette propagation. It supports propagation through items, popups, and windows.

If propagation of properties is not important, consider using a C++ or QML singleton instead, as it is better suited for that use case, and is more efficient in that it only requires one QObject.

To implement a custom attached property:

1. Derive a class that exposes the attached property from QQuickAttachedPropertyPropagator.

   For example, to implement an attached `MyStyle.theme` property, declare the `MyStyle` class:

        class MYSTYLE_EXPORT MyStyle : public QQuickAttachedPropertyPropagator

2. Call initialize() in the constructor of your class:

        MyStyle::MyStyle(QObject *parent)
            : QQuickAttachedPropertyPropagator(parent)
            , m_theme(globalTheme)
        {
            // A static function could be called here that reads globalTheme from a
            // settings file once at startup. That value would override the global
            // value. This is similar to what the Imagine and Material styles do, for
            // example.

            initialize();
        }

3. Define set/inherit/propagate/reset functions for the attached property as needed. For example, to define a `theme` attached property:

        MyStyle::Theme MyStyle::theme() const
        {
            return m_theme;
        }

        void MyStyle::setTheme(Theme theme)
        {
            // When this function is called, we know that the user has explicitly
            // set a theme on this attached object. We set this to true even if
            // the effective theme didn't change, because it's important that
            // the user's specified value is respected (and not inherited from
            // from the parent).
            m_explicitTheme = true;
            if (m_theme == theme)
                return;

            m_theme = theme;
            propagateTheme();
            themeChange();

        }

        void MyStyle::inheritTheme(Theme theme)
        {
            if (m_explicitTheme || m_theme == theme)
                return;

            m_theme = theme;
            propagateTheme();
            themeChange();
        }

        void MyStyle::propagateTheme()
        {
            const auto styles = attachedChildren();
            for (QQuickAttachedPropertyPropagator *child : styles) {
                MyStyle *myStyle = qobject_cast<MyStyle *>(child);
                if (myStyle)
                    myStyle->inheritTheme(m_theme);
            }
        }

        void MyStyle::resetTheme()
        {
            if (!m_explicitTheme)
                return;

            m_explicitTheme = false;
            MyStyle *myStyle = qobject_cast<MyStyle *>(attachedParent());
            inheritTheme(myStyle ? myStyle->theme() : globalTheme);
        }

4. Reimplement attachedParentChange() to handle property inheritance:

        void MyStyle::attachedParentChange(QQuickAttachedPropertyPropagator *newParent, QQuickAttachedPropertyPropagator *oldParent)
        {
            Q_UNUSED(oldParent);
            MyStyle *attachedParentStyle = qobject_cast<MyStyle *>(newParent);
            if (attachedParentStyle) {
                inheritTheme(attachedParentStyle->theme());
                // Do any other inheriting here...
            }
        }

5. Implement a static `qmlAttachedProperties` function and declare the type as an attached QML type with QML_ELEMENT and QML_ATTACHED, as detailed in Providing Attached Properties:

        MyStyle *MyStyle::qmlAttachedProperties(QObject *object)
        {
            return new MyStyle(object);
        }

The complete implementation is available in Qt Quick Controls - Attached Style Properties Example.

See also Styling Qt Quick Controls.

## Member Function Documentation

### `[explicit]` QQuickAttachedPropertyPropagator::QQuickAttachedPropertyPropagator(QObject *parent = nullptr)

Constructs a QQuickAttachedPropertyPropagator with the given parent.

The `parent` will be used to find this object's attached parent.

Derived classes should call initialize() in their constructor.

### `[virtual noexcept]` QQuickAttachedPropertyPropagator::~QQuickAttachedPropertyPropagator()

Destroys the QQuickAttachedPropertyPropagator.

### QList<QQuickAttachedPropertyPropagator *> QQuickAttachedPropertyPropagator::attachedChildren() const

This function returns the attached children of this attached object.

The attached children are used when propagating property values:

     void MyStyle::propagateTheme()
     {
         const auto styles = attachedChildren();
         for (QQuickAttachedPropertyPropagator *child : styles) {
             MyStyle *myStyle = qobject_cast<MyStyle *>(child);
             if (myStyle)
                 myStyle->inheritTheme(m_theme);
         }
     }

### QQuickAttachedPropertyPropagator *QQuickAttachedPropertyPropagator::attachedParent() const

This function returns the attached parent of this attached object.

The attached parent is used when inheriting property values:

     void MyStyle::resetTheme()
     {
         if (!m_explicitTheme)
             return;

         m_explicitTheme = false;
         MyStyle *myStyle = qobject_cast<MyStyle *>(attachedParent());
         inheritTheme(myStyle ? myStyle->theme() : globalTheme);
     }

### `[virtual protected]` void QQuickAttachedPropertyPropagator::attachedParentChange(QQuickAttachedPropertyPropagator *newParent, QQuickAttachedPropertyPropagator *oldParent)

This function is called whenever the attached parent of this QQuickAttachedPropertyPropagator changes from oldParent to newParent.

Subclasses should reimplement this function to inherit attached properties from `newParent`.

     void MyStyle::attachedParentChange(QQuickAttachedPropertyPropagator *newParent, QQuickAttachedPropertyPropagator *oldParent)
     {
         Q_UNUSED(oldParent);
         MyStyle *attachedParentStyle = qobject_cast<MyStyle *>(newParent);
         if (attachedParentStyle) {
             inheritTheme(attachedParentStyle->theme());
             // Do any other inheriting here...
         }
     }

### `[protected]` void QQuickAttachedPropertyPropagator::initialize()

Finds and sets the attached parent for this attached object, and then does the same for its children. This must be called upon construction of the attached object in order for propagation to work.

It can be useful to read global/default values before calling this function. For example, before calling `initialize()`, the Imagine style checks a static "globalsInitialized" flag to see if it should read default values from QSettings. The values from that file form the basis for any attached property values that have not been explicitly set.

     MyStyle::MyStyle(QObject *parent)
         : QQuickAttachedPropertyPropagator(parent)
         , m_theme(globalTheme)
     {
         // A static function could be called here that reads globalTheme from a
         // settings file once at startup. That value would override the global
         // value. This is similar to what the Imagine and Material styles do, for
         // example.

         initialize();
     }