Tipos adjuntos de QML

Las propiedades y señales adjuntas son un mecanismo para anotar objetos con propiedades o señales adicionales que no forman parte de su tipo base. Se accede a las propiedades adjuntas mediante una sintaxis de espacios de nombres que identifica el tipo que proporciona las propiedades adjuntas.

Visión general

Algunos tipos tienen propiedades o señales que pueden adjuntarse a otros objetos, proporcionando funcionalidad adicional sin necesidad de herencia. Se accede a una propiedad o señal adjunta anteponiendo al nombre de la propiedad o señal el nombre del tipo que la adjunta.

Por ejemplo, el tipo ListView tiene una propiedad adjunta llamada isCurrentItem a la que se puede acceder en cualquier elemento dentro del delegado de ListView:

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

En este caso, ListView.isCurrentItem es una propiedad adjunta que ListView pone a disposición de cada elemento delegado.

Propiedades adjuntas

Las propiedades adjuntas permiten añadir propiedades a objetos definidos por un tipo base. Los valores de las propiedades se almacenan externamente al objeto y se accede a ellos a través del nombre del tipo adjunto.

Algunos ejemplos comunes son:

• ListView propiedades adjuntas (isCurrentItem, view)
• GridView propiedades adjuntas
• Keys propiedades adjuntas para el manejo de eventos de teclado
• Component propiedades adjuntas (onCompleted, onDestruction)

Señales adjuntas

Similar a las propiedades adjuntas, las señales adjuntas permiten a los tipos proporcionar manejadores de señales adicionales a los objetos. Se suelen utilizar para los eventos del ciclo de vida.

Por ejemplo, el tipo Componente proporciona señales adjuntas:

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

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

Creación de propiedades adjuntas en C

Para crear propiedades adjuntas para tus propios tipos desde C++, necesitas:

1. Crear una clase de propiedades adjuntas que herede de QObject
2. Implementar las propiedades adjuntas en esta clase
3. Añadir la macro QML_ATTACHED a su tipo principal
4. Implementar un método estático qmlAttachedProperties()

Ejemplo:

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);
    }
};

Uso en QML:

Item {
    MyType.value: 42
}

Si el tipo que adjunta (MyType en este caso) no hace nada más que adjuntar propiedades a otros objetos, puedes expresarlo como una sola clase:

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;
};

Cuándo utilizar propiedades adjuntas

Las propiedades adjuntas son útiles cuando:

• Desea añadir información específica del contexto a los elementos (como ListView's isCurrentItem)
• Las propiedades pertenecen lógicamente a un contenedor o contexto y no al propio elemento.
• Desea evitar saturar los tipos base con propiedades especializadas.