<qqmlintegration.h>

Documentation des macros

QML_ADDED_IN_VERSION(MAJOR, MINOR)

Déclare que le type ou l'espace de noms englobant a été ajouté dans la version spécifiée MAJOR.MINOR. La version est supposée être en ligne avec toutes les révisions données par les macros Q_REVISION() sur les méthodes, les slots ou les signaux, et tous les attributs REVISION() sur les propriétés déclarées avec Q_PROPERTY().

QML_ADDED_IN_VERSION() ne prend effet que si le type ou l'espace de noms est disponible dans QML, en ayant une macro QML_ELEMENT, QML_NAMED_ELEMENT(), QML_ANONYMOUS, ou QML_INTERFACE.

Si le module QML auquel le type appartient est importé avec une version inférieure à celle déterminée de cette manière, le type QML est invisible.

Voir également QML_ELEMENT et QML_NAMED_ELEMENT.

QML_ANONYMOUS

Déclare que le type englobant est disponible, mais anonyme en QML. Le type ne peut pas être créé ou utilisé pour déclarer des propriétés en QML, mais lorsqu'il est transmis depuis C++, il est reconnu. En QML, vous pouvez utiliser les propriétés de ce type si elles sont déclarées en C++.

Voir également QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE() et QML_INTERFACE.

QML_ATTACHED(ATTACHED_TYPE)

Déclare que le type englobant attache ATTACHED_TYPE en tant que propriété attachée à d'autres types. Cette déclaration prend effet si le type est exposé à QML à l'aide d'une macro QML_ELEMENT ou QML_NAMED_ELEMENT().

Voir aussi QML_ELEMENT, QML_NAMED_ELEMENT(), qmlAttachedPropertiesObject(), et Providing Attached Properties.

[since 6.5] QML_CONSTRUCTIBLE_VALUE

Marque le type de valeur environnante comme constructible. En d'autres termes, tous les constructeurs Q_INVOKABLE du type qui prennent exactement un argument peuvent être utilisés lors de l'affectation d'une valeur JavaScript à une propriété de ce type.

Vous pouvez déclarer un type de valeur constructible comme suit :

class MyValueType
{
    Q_GADGET
    QML_VALUE_TYPE(myValueType)
    QML_CONSTRUCTIBLE_VALUE
public:
    Q_INVOKABLE MyValueType(double d);

    // ...
};

Avec le type ci-dessus, le code QML suivant produira une valeur MyValueType à l'aide du constructeur donné et l'affectera à la propriété.

QtObject {
    property myValueType v: 5.4
}

Vous pouvez également construire des listes de valeurs de cette manière :

QtObject {
    property list<myValueType> v: [5.4, 4.5, 3.3]
}

Depuis Qt 6.8, si vous importez le module QML auquel appartient le type de valeur dans un espace de noms, vous pouvez utiliser l'opérateur new de JavaScript pour l'instancier.

import MyModule as MM

QtObject {
    function process(d: real) {
        let v = new MM.myValueType(d);
        // v is a myValueType now
    }
}

Cette macro a été introduite dans Qt 6.5.

Voir aussi QML_VALUE_TYPE.

QML_ELEMENT

Déclare que le type ou l'espace de noms englobant est disponible en QML, en utilisant son nom de classe ou d'espace de noms comme nom d'élément QML.

Par exemple, cela rend la classe C++ Slider disponible en tant que type QML nommé Slider. Toutes ses propriétés, méthodes invocables et enums sont exposés.

class Slider : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    Q_PROPERTY(int value READ value WRITE setValue NOTIFY valueChanged FINAL)
    // ...
public:
    enum Slippiness {
        Dry, Wet, Icy
    };
    Q_ENUM(Slippiness)

    Q_INVOKABLE void slide(Slippiness slippiness);

    // ...
}

Vous pouvez utiliser le système de construction pour enregistrer le type dans l'espace de noms de types com.mycompany.qmlcomponents avec la version majeure 1. Pour qmake, spécifiez ce qui suit dans votre fichier de projet :

CONFIG += qmltypes
QML_IMPORT_NAME = com.mycompany.qmlcomponents
QML_IMPORT_MAJOR_VERSION = 1

Avec CMake, vous transmettez l'URI et la version à qt_add_qml_module.

qt6_add_qml_module(myapp
  URI com.mycompany.qmlcomponents
  VERSION 1.0
)

Une fois enregistré, le type peut être utilisé dans QML en important le même espace de noms de type et le même numéro de version :

import com.mycompany.qmlcomponents 1.0

Slider {
    value: 12
    Component.onCompleted: slide(Slider.Icy)

    // ...
}

Vous pouvez également rendre les espaces de noms étiquetés avec Q_NAMESPACE disponibles de cette manière, afin d'exposer tous les enums étiquetés avec Q_ENUM_NS qu'ils contiennent :

namespace MyNamespace {
  Q_NAMESPACE
  QML_ELEMENT

  enum MyEnum {
      Key1,
      Key2,
  };
  Q_ENUM_NS(MyEnum)
}

En QML, vous pouvez alors utiliser les enums :

Component.onCompleted: console.log(MyNamespace.Key2)

REMARQUE : Lorsque des classes portent le même nom mais sont situées dans des espaces de noms différents, l'utilisation de QML_ELEMENT pour chacune d'entre elles provoquera un conflit. Veillez à utiliser QML_NAMED_ELEMENT() pour l'une d'entre elles.

Voir aussi Choisir la bonne méthode d'intégration entre C++ et QML, QML_NAMED_ELEMENT(), Q_REVISION(), et QML_ADDED_IN_VERSION().

QML_EXTENDED(EXTENDED_TYPE)

Déclare que le type englobant utilise EXTENDED_TYPE comme extension pour fournir d'autres propriétés, méthodes et énumérations en QML. Cette déclaration prend effet si le type est exposé à QML à l'aide d'une macro QML_ELEMENT ou QML_NAMED_ELEMENT().

Voir aussi QML_ELEMENT, QML_NAMED_ELEMENT(), QML_EXTENDED_NAMESPACE(), et Enregistrer des objets d'extension.

QML_EXTENDED_NAMESPACE(EXTENSION_NAMESPACE)

Déclare que le type englobant utilise EXTENSION_NAMESPACE comme extension pour fournir d'autres énumérations en QML. Cette déclaration prend effet si le type est exposé à QML à l'aide d'une macro QML_ELEMENT ou QML_NAMED_ELEMENT(). Les énumérations doivent être exposées au système de métaobjets pour que cela fonctionne.

Par exemple, dans le code C++ suivant

namespace MyNamespace {
    Q_NAMESPACE
    enum MyEnum { MyEnumerator = 10 };
    Q_ENUM_NS(MyEnum)
}

class QmlType : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_EXTENDED_NAMESPACE(MyNamespace)
}

nous pouvons accéder à l'énumération en QML :

QmlType {
    property int i: QmlType.MyEnumerator // i will be 10
}

Voir aussi QML_NAMESPACE_EXTENDED(), QML_ELEMENT, QML_NAMED_ELEMENT(), QML_EXTENDED(), Enregistrer des objets d'extension, Q_ENUM, et Q_ENUM_NS.

QML_EXTRA_VERSION(MAJOR, MINOR)

Déclarer que le type doit également être disponible dans la version MAJOR.MINOR. Cela peut être utile si un type doit être disponible dans plusieurs versions majeures.

Les types sont automatiquement enregistrés pour :

• La version majeure dans laquelle ils ont été introduits, voir QML_ADDED_IN_VERSION.
• Toutes les versions majeures dans lesquelles leurs membres ont été introduits.
• La version majeure actuelle de leur module, à moins qu'ils n'aient été QML_REMOVED_IN_VERSION avant cela.

Notamment, ils ne sont pas automatiquement enregistrés dans les PAST_MAJOR_VERSIONS situées entre les versions ci-dessus. Vous pouvez utiliser QML_EXTRA_VERSION pour enregistrer manuellement vos types dans les versions majeures suivantes.

Voir aussi QML_ELEMENT et QML_ADDED_IN_VERSION.

QML_FOREIGN(FOREIGN_TYPE)

Déclare que les macros QML_ELEMENT, QML_NAMED_ELEMENT(), QML_ANONYMOUS, QML_INTERFACE, QML_UNCREATABLE(), QML_SINGLETON, QML_ADDED_IN_VERSION(), QML_REMOVED_IN_VERSION(), QML_ADDED_IN_MINOR_VERSION(), QML_REMOVED_IN_MINOR_VERSION(), QML_EXTENDED(), QML_EXTENDED_NAMESPACE() ou QML_NAMESPACE_EXTENDED() du type C++ englobant ne s'appliquent pas au type englobant mais à FOREIGN_TYPE. Le type englobant doit toujours être enregistré auprès du système de métaobjets à l'aide d'une macro Q_GADGET ou Q_OBJECT.

Ceci est utile pour enregistrer des types qui ne peuvent pas être modifiés pour ajouter les macros, par exemple parce qu'ils appartiennent à des bibliothèques tierces. Pour enregistrer un espace de noms, voir QML_FOREIGN_NAMESPACE().

Voir aussi QML_ELEMENT, QML_NAMED_ELEMENT(), et QML_FOREIGN_NAMESPACE().

QML_FOREIGN_NAMESPACE(FOREIGN_NAMESPACE)

Déclare que les macros QML_ELEMENT, QML_NAMED_ELEMENT(), QML_ANONYMOUS, QML_INTERFACE, QML_UNCREATABLE(), QML_SINGLETON, QML_ADDED_IN_VERSION(), QML_REMOVED_IN_VERSION(), QML_ADDED_IN_MINOR_VERSION() ou QML_REMOVED_IN_MINOR_VERSION() de l'espace de noms C++ englobant ne s'appliquent pas au type englobant mais à FOREIGN_NAMESPACE. L'espace de noms englobant doit toujours être enregistré auprès du système de métaobjets à l'aide d'une macro Q_NAMESPACE.

Ceci est utile pour enregistrer des espaces de noms qui ne peuvent pas être modifiés pour ajouter les macros, par exemple parce qu'ils appartiennent à des bibliothèques tierces.

Voir également QML_ELEMENT, QML_NAMED_ELEMENT(), et QML_FOREIGN().

QML_IMPLEMENTS_INTERFACES(interfaces)

Cette macro indique à Qt quel QML interfaces la classe implémente. Cette macro ne doit être utilisée que pour l'interfaçage avec des classes utilisant QML_INTERFACE, sinon utilisez Q_INTERFACES. Elle est nécessaire pour que l'enregistrement déclaratif via QML_ELEMENT fonctionne correctement.

Voir aussi QML_INTERFACE et Q_INTERFACES.

QML_INTERFACE

Cette macro enregistre le type C++ englobant dans le système QML en tant qu'interface.

Les types enregistrés en tant qu'interface dans QML doivent également se déclarer en tant qu'interface auprès du système de métaobjets. C'est le cas par exemple :

struct FooInterface
{
    QML_INTERFACE
public:
    virtual ~FooInterface();
    virtual void doSomething() = 0;
};

Q_DECLARE_INTERFACE(FooInterface, "org.foo.FooInterface")

Lorsqu'ils sont enregistrés de cette manière dans QML, ils peuvent être utilisés comme types de propriété :

Q_PROPERTY(FooInterface *foo READ foo WRITE setFoo)

Lorsque vous attribuez une sous-classe QObject à cette propriété, le moteur QML effectue automatiquement le cast de l'interface vers FooInterface*.

Les types d'interface sont implicitement anonymes et non créables en QML.

NOTE : Lorsque vous héritez de types utilisant QML_INTERFACE, utilisez QML_IMPLEMENTS_INTERFACES au lieu de Q_INTERFACES.

Voir également QML_IMPLEMENTS_INTERFACES(), QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE() et QML_ANONYMOUS.

QML_NAMED_ELEMENT(name)

Déclare que le type ou l'espace de noms englobant est disponible en QML, en utilisant name comme nom d'élément. Sinon, il se comporte de la même manière que QML_ELEMENT.

class SqlEventDatabase : public QObject
{
    Q_OBJECT
    QML_NAMED_ELEMENT(EventDatabase)

    // ...
};

Voir aussi Choisir la bonne méthode d'intégration entre C++ et QML et QML_ELEMENT.

QML_REMOVED_IN_VERSION(MAJOR, MINOR)

Déclare que le type ou l'espace de noms englobant a été supprimé dans la version MAJOR.MINOR spécifiée. Ceci est principalement utile lors du remplacement de l'implémentation d'un type QML. Si un QML_ADDED_IN_VERSION() correspondant est présent sur un autre type ou espace de noms du même nom QML, le type supprimé est utilisé lors de l'importation de versions du module inférieures à MAJOR.MINOR, et le type ajouté est utilisé lors de l'importation de versions du module supérieures ou égales à MAJOR.MINOR.

QML_REMOVED_IN_VERSION() ne prend effet que si le type ou l'espace de noms est disponible dans QML, en ayant une macro QML_ELEMENT, QML_NAMED_ELEMENT(), QML_ANONYMOUS, ou QML_INTERFACE.

Voir également QML_ELEMENT et QML_NAMED_ELEMENT.

QML_SEQUENTIAL_CONTAINER(VALUE_TYPE)

Cette macro déclare le type englobant ou référencé comme un conteneur séquentiel gérant une séquence d'éléments VALUE_TYPE. VALUE_TYPE peut être un type de valeur réel ou un pointeur vers un type d'objet. Il est rare que vous puissiez ajouter cette macro à la déclaration du conteneur proprement dit, car les conteneurs sont généralement des modèles. Vous devez utiliser QML_FOREIGN pour attacher l'enregistrement du type à l'instanciation d'un modèle. En utilisant cette technique, vous pouvez, par exemple, déclarer des conteneurs séquentiels comme ceci :

class IntDequeRegistration
{
  Q_GADGET
  QML_FOREIGN(std::deque<int>)
  QML_ANONYMOUS
  QML_SEQUENTIAL_CONTAINER(int)
};

Ensuite, vous pouvez utiliser le conteneur comme un tableau JavaScript en QML.

class Maze
{
  Q_OBJECT
  Q_ELEMENT
  // 0: North, 1: East, 2: South, 3: West
  Q_PROPERTY(std::deque<int> solution READ solution CONSTANT FINAL)
  [...]
}

Item {
  Maze {
    id: maze
  }

  function showSolution() {
      maze.solution.forEach([...])
  }
}

Voir également QML_ANONYMOUS et QML_FOREIGN().

QML_SINGLETON

Déclare que le type englobant est un singleton en QML. Ceci ne prend effet que si le type est un Q_OBJECT et est disponible en QML (en ayant une macro QML_ELEMENT ou QML_NAMED_ELEMENT()). Par défaut, chaque QQmlEngine essaiera de créer une instance de singleton en utilisant soit le constructeur par défaut du type, soit une fonction d'usine statique de la signature T *create(QQmlEngine *, QJSEngine *) lorsque le type est accédé pour la première fois. Si les deux existent et sont accessibles, le constructeur par défaut est préféré. S'il n'y a ni constructeur par défaut ni fonction d'usine, le singleton est inaccessible. Le moteur QML assume généralement la propriété du singleton et le supprimera lorsque le moteur lui-même sera détruit. Vous pouvez empêcher cela en appelant QJSEngine::setObjectOwnership() sur le singleton.

Pour déclarer une classe constructible par défaut comme singleton, il suffit d'ajouter QML_SINGLETON:

class MySingleton : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_SINGLETON
    // Q_PROPERTY( ... )
public:
    // members, Q_INVOKABLE functions, etc.
};

Si la classe singleton n'est pas constructible par défaut, mais que vous pouvez la modifier, vous pouvez lui ajouter une fonction factory, afin de la rendre accessible :

class MySingleton : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_SINGLETON
    // Q_PROPERTY( ... )

public:
    static MySingleton *create(QQmlEngine *qmlEngine, QJSEngine *jsEngine)
    {
        MySingleton *result = nullptr;
        // Create the object using some custom constructor or factory.
        // The QML engine will assume ownership and delete it, eventually.
        return result;
    }

    // members, Q_INVOKABLE functions, etc
};

Si vous ne pouvez pas modifier la classe et qu'elle n'a pas de constructeur par défaut ou de fonction d'usine appropriée, vous pouvez fournir un wrapper QML_FOREIGN pour définir la fonction d'usine :

struct SingletonForeign
{
    Q_GADGET
    QML_FOREIGN(MySingleton)
    QML_SINGLETON
    QML_NAMED_ELEMENT(MySingleton)
public:

    static MySingleton *create(QQmlEngine *, QJSEngine *engine)
    {
        MySingleton *result = nullptr;
        // Create the instance using some custom constructor or factory.
        // The QML engine will assume ownership and delete it, eventually.
        return result;
    }
};

Enfin, si vous souhaitez fournir un objet singleton spécifique, dont vous ne pouvez pas contrôler la création, vous pouvez le renvoyer à partir d'une fonction factory. Il s'agit d'un remplacement de la fonction qmlRegisterSingletonInstance. Si vous appeliez

qmlRegisterSingletonInstance("MyModule", 1, 0, "MySingleton", myObject);

avec monObjet étant de type MySingleton *, vous pouvez faire ce qui suit à la place :

struct SingletonForeign
{
    Q_GADGET
    QML_FOREIGN(MySingleton)
    QML_SINGLETON
    QML_NAMED_ELEMENT(MySingleton)
public:

    // Initialize this using myObject where you would previously
    // call qmlRegisterSingletonInstance().
    inline static MySingleton *s_singletonInstance = nullptr;

    static MySingleton *create(QQmlEngine *, QJSEngine *engine)
    {
        // The instance has to exist before it is used. We cannot replace it.
        Q_ASSERT(s_singletonInstance);

        // The engine has to have the same thread affinity as the singleton.
        Q_ASSERT(engine->thread() == s_singletonInstance->thread());

        // There can only be one engine accessing the singleton.
        if (s_engine)
            Q_ASSERT(engine == s_engine);
        else
            s_engine = engine;

        // Explicitly specify C++ ownership so that the engine doesn't delete
        // the instance.
        QJSEngine::setObjectOwnership(s_singletonInstance,
                                      QJSEngine::CppOwnership);
        return s_singletonInstance;
    }

private:
    inline static QJSEngine *s_engine = nullptr;
};

De cette manière, la classe préexistante MySingleton est déclarée comme étant un singleton QML, appelé MySingleton. Vous pouvez spécifier une instance pour elle à tout moment avant qu'elle ne soit utilisée en définissant le membre s_singletonInstance. Rien de tout cela ne nécessite de modifier MySingleton.

Voir aussi QML_ELEMENT, QML_NAMED_ELEMENT(), qmlRegisterSingletonInstance(), QQmlEngine::singletonInstance(), et Singletons in QML.

[since 6.5] QML_STRUCTURED_VALUE

Marque le type de valeur environnant comme étant structuré. Les types de valeur structurés peuvent être et seront de préférence construits propriété par propriété à partir d'un objet JavaScript. Cependant, un type de valeur structuré est toujours QML_CONSTRUCTIBLE_VALUE. Cela signifie que vous pouvez toujours fournir des constructeurs Q_INVOKABLE afin de gérer la construction à partir de types primitifs.

Vous pouvez déclarer un type de valeur structuré comme suit :

class MyValueType
{
    Q_GADGET
    QML_VALUE_TYPE(myValueType)
    QML_STRUCTURED_VALUE
    Q_PROPERTY(double d READ d WRITE setD)
    Q_PROPERTY(string e READ e WRITE setE)

    // ...
};

Vous pouvez ensuite remplir une propriété de ce type comme suit :

QtObject {
    property myValueType v: ({d: 4.4, e: "a string"})
}

Les parenthèses supplémentaires sont nécessaires pour distinguer l'objet JavaScript de ce qui pourrait être interprété comme un bloc de code JavaScript.

Vous pouvez également construire des listes de valeurs de cette manière :

QtObject {
    property list<myValueType> v: [
        {d: 4.4, e: "a string"},
        {d: 7.1, e: "another string"}
    ]
}

Cette macro a été introduite dans Qt 6.5.

Voir également QML_VALUE_TYPE et QML_CONSTRUCTIBLE_VALUE.

QML_UNAVAILABLE

Cette macro déclare que le type englobant n'est pas disponible en QML. Elle enregistre un type factice interne appelé QQmlTypeNotAvailable en tant que type QML_FOREIGN(), en utilisant toutes les autres macros QML que vous spécifiez.

Normalement, les types exportés par un module devraient être fixes. Toutefois, si un type C++ n'est pas disponible, vous devez au moins "réserver" le nom du type QML et donner à l'utilisateur du type non disponible un message d'erreur significatif.

Exemple :

#ifdef NO_GAMES_ALLOWED
struct MinehuntGame
{
    Q_GADGET
    QML_NAMED_ELEMENT(Game)
    QML_UNAVAILABLE
    QML_UNCREATABLE("Get back to work, slacker!");
};
#else
class MinehuntGame : public QObject
{
    Q_OBJECT
    QML_NAMED_ELEMENT(Game)
    // ...
};
#endif

Tout QML qui tente d'utiliser le type "Game" produira un message d'erreur :

fun.qml: Get back to work, slacker!
   Game {
   ^

En utilisant cette technique, vous n'avez besoin que d'une structure Q_GADGET pour personnaliser le message d'erreur, et non d'une structure QObject à part entière. Sans QML_UNCREATABLE(), QML_UNAVAILABLE produit toujours un message d'erreur plus spécifique que l'habituel "is not a type" pour les types complètement inconnus.

Voir aussi QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE() et QML_FOREIGN().

QML_UNCREATABLE(reason)

Déclare que le type englobant ne doit pas pouvoir être créé à partir de QML. Cela prend effet si le type est disponible en QML, en ayant une macro QML_ELEMENT ou QML_NAMED_ELEMENT(). L'adresse reason sera émise comme message d'erreur si une tentative de création du type à partir de QML est détectée.

Certains types QML sont implicitement non créables, en particulier les types exposés avec QML_ANONYMOUS ou les espaces de noms exposés avec QML_ELEMENT ou QML_NAMED_ELEMENT().

Depuis Qt 6.0, vous pouvez utiliser "" à la place d'une raison pour utiliser un message standard.

Voir aussi QML_ELEMENT, QML_NAMED_ELEMENT(), et QML_ANONYMOUS.

QML_VALUE_TYPE(name)

Déclare que le type ou l'espace de noms englobant est disponible en QML, en utilisant name comme nom. Le type doit être un type de valeur et le nom doit être en minuscules.

class MyValueType
{
    Q_GADGET
    QML_VALUE_TYPE(myValueType)

    // ...
};

Voir aussi Choisir la bonne méthode d'intégration entre C++ et QML et QML_NAMED_ELEMENT.