�tendre QML en C++

La syntaxe du QML d�crit d�clarativement comment construire un arbre d'objets en m�moire. Dans Qt, QML est principalement utilis� pour d�crire une sc�ne visuelle mais n'est pas conceptuellement limit� � cela : le format QML est une description abstraite d'un arbre d'objets. Tous les �l�ments QML inclus dans Qt sont impl�ment�s en utilisant les m�canismes d'extension du QML � partir du C++ d�crits dans cette page. Les programmeurs peuvent utiliser ces biblioth�ques pour ajouter de nouveaux types qui interagissent avec les types Qt existants ou pour adapter QML � un usage diff�rent de celui pr�vu.

Ajouter des types

 import People 1.0
 
 Person {
     name: "Bob Jones"
     shoeSize: 12
 }

L'exemple ci-dessus de QML instancie une personne Person et d�finit les propri�t�s de nom name et de taille de chaussure shoeSize. Tout en QML revient � instancier un objet ou affecter une valeur.

Le QML s'appuie fortement sur le syst�me de m�taobjets de Qt et ne peut instancier que les classes qui d�rivent de QObject. Pour les �l�ments visuels, cela est normalement fait en cr�ant des sous-classes de QDeclarativeItem ; pour les mod�les utilis�s avec les �l�ments de la vue, des sous-classes de QAbstractItemModel ; et pour les objets arbitraires poss�dant des propri�t�s, des sous-classes directes de QObject.

Le moteur QML n'a aucune connaissance intrins�que des classes. � la place, le programmeur doit enregistrer les types C++ avec leur nom QML correspondant.

Les types C++ personnalis�s sont enregistr�s en utilisant une fonction template :

 template<typename T>
 int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)

L'appel � la fonction qmlRegisterType() enregistre le type C++ T dans le syst�me QML et le rend disponible en QML sous le nom qmlName dans la biblioth�que uri en version versionMajor.versionMinor. Le qmlName peut �tre le m�me que le nom du type C++.

Le type T doit �tre un type concret h�ritant de QObject et poss�dant un constructeur par d�faut.

#include <QtDeclarative> pour utiliser qmlRegisterType().

Les types peuvent �tre enregistr�s par des biblioth�ques, du code applicatif ou par des plug-ins (voir QDeclarativeExtensionPlugin).

Une fois l'enregistrement effectu�, toutes les propri�t�s des types connus sont disponibles en QML. QML conna�t intrins�quement les propri�t�s des types list�s dans le document ajout de propri�t�s, qui inclut les types suivants :

• bool, unsigned int, int, float, double, qreal ;
• QString, QUrl, QColor ;
• QDate, QTime, QDateTime ;
• QPoint, QPointF, QSize, QSizeF, QRect, QRectF ;
• QVariant.

Lorsqu'une propri�t� d'un type connu est ajout�e � une classe C++, l'�l�ment QML bas� sur cette classe aura un gestionnaire de signal value-changed. Voir support des signaux ci-dessous.

QML b�n�ficie de ce qu'on appelle un typage s�r (il est typesafe). Si vous tentez d'affecter une valeur invalide � une propri�t�, la propri�t� g�n�rera une erreur. Par exemple, prenons la propri�t� nom (name) de l'�l�ment personne (Person) ayant pour type QString, ce code causerait une erreur :

 Person {
     // Ne fonctionnera pas
     name: 12
 }

�tendre le QML - exemple d'ajout de types pr�sente un code complet utilis� pour cr�er le type Person.

Les propri�t�s de type objet et liste

 BirthdayParty {
     host: Person {
         name: "Bob Jones"
         shoeSize: 12
     }
     guests: [
         Person { name: "Leo Hodges" },
         Person { name: "Jack Smith" },
         Person { name: "Anne Brown" }
     ]
 }

L'exemple de QML ci-dessus affecte un objet Person � la propri�t� h�te host de BirthdayParty et affecte trois objets Person comme invit�s � la propri�t� guests.

QML peut d�finir des propri�t�s plus complexes que les types basiques intrins�ques tels que les entiers et les cha�nes de caract�res. Les propri�t�s peuvent aussi �tre des pointeurs sur des objets, des pointeurs sur des interfaces Qt, des listes de points et des listes de pointeurs sur des interfaces Qt. Comme le QML est typesafe il garantit que seuls des types valides sont affect�s � ces propri�t�s, tout comme il le fait avec les types primitifs.

Les propri�t�s qui sont des pointeurs sur des objets ou sur des interfaces Qt sont d�clar�es avec la macro Q_PROPERTY(), tout comme les autres propri�t�s. La d�claration de la propri�t� h�te host est la suivante :

     Q_PROPERTY(Person *host READ host WRITE setHost)

Tant que la propri�t� de type, dans ce cas Person, est enregistr�e dans QML, la propri�t� peut �tre affect�e.

QML permet aussi l'affectation d'interfaces Qt. Pour affecter une propri�t� dont le type est un pointeur sur une interface Qt, l'interface doit aussi �tre enregistr�e dans QML. Comme elles ne peuvent pas �tre instanci�es directement, l'enregistrement d'une interface Qt est diff�rent de l'enregistrement d'un nouveau type QML. La fonction suivante est utilis�e � la place :

 template<typename T>
 int qmlRegisterInterface(const char *typeName)

Cela enregistre l'interface C++ T dans le syst�me QML comme typeName.

Apr�s l'enregistrement, QML peut forcer des objets impl�mentant cette interface pour des affectations � des propri�t�s de types appropri�s.

La propri�t� guests est une liste d'objets Person. Les propri�t�s qui sont des listes d'objets ou d'interfaces Qt sont aussi d�clar�es avec la macro Q_PROPERTY(), tout comme les autres propri�t�s. Les propri�t�s de listes doivent avoir le type QDeclarativeListProperty<T>. Comme pour les propri�t�s objets, le type T doit �tre enregistr� dans QML.

La d�claration de la propri�t� guest ressemble � ceci :

     Q_PROPERTY(QDeclarativeListProperty<Person> guests READ guests)

�tendre QML - exemple de propri�t�s de type objet et liste pr�sente le code complet utilis� pour cr�er le type BirthdayParty.

H�ritage et for�age

 BirthdayParty {
     host: Boy {
         name: "Bob Jones"
         shoeSize: 12
     }
     guests: [
         Boy { name: "Leo Hodges" },
         Boy { name: "Jacck Smith" },
         Girl { name: "Anne Brown" }
     ]
 }

L'exemple de code QML ci-dessus affecte l'objet Boy � la propri�t� h�te (host) de BirthdayParty et affecte trois autres objets � la propri�t� invit�s (guests).

QML g�re les hi�rarchies d'h�ritage du C++ et peut librement effectuer des for�ages entre des types d'objets valides et connus. Cela permet la cr�ation de classes de base communes autorisant l'affectation de classes sp�cialis�es aux propri�t�s de types objet ou liste. Dans l'exemple ci-dessus, les deux propri�t�s h�te (host) et invit�s (guests) conservent le type Person utilis� dans la section pr�c�dente mais l'affection est valide car les objets Boy et Girl h�ritent de Person.

Pour affecter une valeur � une propri�t�, le type de la propri�t� doit �tre enregistr� dans QML. Les deux fonctions templates qmlRegisterType() et qmlRegisterInterface() pr�sent�es pr�c�demment peuvent �tre utilis�es pour enregistrer un type dans QML. De plus, si un type agissant purement comme une classe de base qui ne peut pas �tre instanci�e dans QML, il a besoin d'�tre enregistr�, la fonction suivante peut �tre utilis�e :

     template<typename T>
     int qmlRegisterType()

Cela enregistre le type C++ T dans le syst�me QML. L'appel sans param�tre de la fonction template qmlRegisterType() ne d�finit pas de correspondance entre la classe C++ et le nom d'�l�ment QML, donc il n'est pas possible de cr�er un �l�ment de ce type dans QML, mais il est utilisable pour le for�age de type.

Le type T doit h�riter de QObject mais il n'y a aucune restriction sur le fait qu'il soit concret ou sur la signature de son constructeur.

QML forcera automatiquement les types C++ lors de l'affectation � une propri�t� objet ou � une propri�t� liste. Une erreur d'affectation appara�tra uniquement si le for�age �choue.

�tendre le QML - exemple d'h�ritage et de for�age montre le code complet utilis� pour cr�er les types Boy et Girl.

Propri�t� par d�faut

 BirthdayParty {
     host: Boy {
         name: "Bob Jones"
         shoeSize: 12
     }
 
     Boy { name: "Leo Hodges" }
     Boy { name: "Jack Smith" }
     Girl { name: "Anne Brown" }
 }

Le code QML ci-dessus montre l'affectation d'une collection d'objets � la propri�t� par d�faut de BirthdayParty.

La propri�t� par d�faut est une commodit� syntaxique permettant au concepteur d'un type de sp�cifier une propri�t� unique comme propri�t� par d�faut du type. La propri�t� par d�faut re�oit les affectations dans les cas o� la propri�t� � affecter n'est pas sp�cifi�e explicitement. Le comportement est identique � l'affectation explicite de la propri�t� par son nom.

Depuis C++, le d�veloppeur marque la propri�t� par d�faut en utilisant une annotation Q_CLASSINFO():

 Q_CLASSINFO("DefaultProperty", "property")

Cela marque la propri�t� property comme propri�t� par d�faut de la classe. La propri�t� property doit �tre soit une propri�t� objet, soit une propri�t� liste.

La d�claration d'une propri�t� par d�faut est optionnelle. Une classe d�riv�e h�rite de la propri�t� par d�faut de la classe de base mais peut la surcharger dans sa propre d�claration. La propri�t� property peut faire r�f�rence � une propri�t� d�clar�e dans la classe ou � une propri�t� h�rit�e de la classe de base.

�tendre le QML - exemple de propri�t� par d�faut montre le code complet utilis� pour sp�cifier une propri�t� par d�faut.

Propri�t�s group�es

     Boy {
         name: "Jack Smith"
         shoe {
             size: 8
             color: "blue"
             brand: "Puma"
             price: 19.95
         }
     }

Le code QML ci-dessus attribue plusieurs propri�t�s � l'objet Boy, incluant quatre propri�t�s utilisant la syntaxe des propri�t�s group�es.

Les propri�t�s group�es rassemblent plusieurs propri�t�s similaires en un seul bloc nomm�. Les propri�t�s group�es peuvent �tre utilis�es pour pr�senter une interface plus agr�able aux d�veloppeurs et peut aussi simplifier l'impl�mentation de collections de propri�t�s communes � diff�rents types gr�ce � la r�utilisation de l'impl�mentation.

Un bloc de propri�t�s group�es est impl�ment� sous forme d'une propri�t� objet en lecture seule. La propri�t� chaussure shoe pr�sent�e dans l'exemple de code est d�clar�e comme suit :

     Q_PROPERTY(ShoeDescription *shoe READ shoe)

Le type ShoeDescription d�clare les propri�t�s disponibles pour le bloc de propri�t�s group�es - dans ce cas, les propri�t�s de taille size, de couleur color, de marque brand et de prix price.

Les blocs de propri�t�s group�es peuvent �tre d�clar�s et acc�d�s r�cursivement.

�tendre le QML - exemple de propri�t�s group�es pr�sente le code complet utilis� pour impl�menter le groupe de propri�t�s shoe.

Propri�t�s attach�es

     Boy {
         name: "Leo Hodges"
         shoe { size: 10; color: "black"; brand: "Reebok"; price: 59.95 }
 
         BirthdayParty.rsvp: "2009-07-06"
     }

Le code QML ci-dessus affecte une date � la propri�t� rsvp en utilisant la syntaxe de propri�t� attach�e.

Les propri�t�s attach�es permettent � des types d'ajouter des propri�t�s � d'autres types avec lesquels ils n'ont pas de relation, g�n�ralement pour leur propre usage. Les propri�t�s attach�es sont identifi�es par l'utilisation du nom du type cr�ateur de l'attache, dans le cas pr�sent BirthdayParty, comme pr�fixe au nom de propri�t�.

Dans l'exemple ci-dessus, BirthdayParty est appel� le type attacheur ; l'instance Boy, l'objet receveur.

Pour le type attacheur, un bloc de propri�t�s attach�es est impl�ment� comme un nouveau type d�rivant de QObject, appel� objet d'attachement. Les propri�t�s de l'objet d'attachement sont celles qui deviennent disponibles comme bloc de propri�t�s attach�es.

N'importe quel type QML peut devenir un type attacheur en d�clarant la fonction publique qmlAttachedProperties() et en d�clarant l'information de type QML_HAS_ATTACHED_PROPERTIES:

 class MyType : public QObject {
     Q_OBJECT
 public:
 
     ...
 
     static AttachedPropertiesType *qmlAttachedProperties(QObject *object);
 };
 
 QML_DECLARE_TYPEINFO(MyType, QML_HAS_ATTACHED_PROPERTIES)

La fonction retourne un objet d'attachement, du type AttachedPropertiesType, pour l'objet receveur object. Il est d'usage, mais pas strictement obligatoire, que l'objet d'attachement ait comme parent l'objet object afin d'�viter les fuites de m�moire.

Le type AttachedPropertiesType doit �tre un type d�riv� de QObject. Les propri�t�s de ce type vont �tre accessibles gr�ce � la syntaxe des propri�t�s attach�es.

Cette m�thode va �tre appel�e au moins une fois pour chaque objet attach�. Le moteur QML mettra en cache le pointeur retourn� pour les prochains acc�s � la propri�t�. Par cons�quent, l'objet d'attachement ne peut pas �tre d�truit tant que l'objet object n'est pas d�truit.

Dans le principe, les propri�t�s attach�es sont un type exportant un ensemble de propri�t�s additionnelles qui peuvent �tre d�finies dans n'importe quel autre objet. Les propri�t�s attach�es ne peuvent pas �tre limit�es � l'attachement � un sous-ensemble d'objets, bien que leurs effets puissent �tre limit�s � ce sous-ensemble.

Par exemple, un sc�nario courant est d'utiliser un type pour �tendre les propri�t�s disponibles pour ses enfants afin de r�cup�rer des donn�es sp�cifiques � l'instance. Ici nous ajoutons un champ rsvp pour tous les invit�s venant � une f�te d'anniversaire :

 BirthdayParty {
     Boy { BirthdayParty.rsvp: "2009-06-01" }
 }

Cependant, comme un type ne peut pas limiter les instances auxquelles l'objet d'attachement doit s'attacher, le code suivant est aussi permis, m�me si l'ajout d'une date de f�te d'anniversaire dans ce contexte n'a aucun int�r�t.

 GraduationParty {
     Boy { BirthdayParty.rsvp: "2009-06-01" }
 }

Depuis C++, y compris depuis l'impl�mentation du type attacheur, on peut acc�der � l'objet d'attachement d'une instance en utilisant la m�thode suivante :

 template<typename T>
 QObject *qmlAttachedPropertiesObject<T>(QObject *attachee, bool create = true);

La fonction retourne l'objet d'attachement attach� � attachee (le receveur) par le type attacheur T. Si le type T n'est pas un type attacheur valide, la m�thode retourne toujours 0.

Si create est d�fini � true, un objet d'attachement valide sera toujours retourn�, et il sera cr�� s'il n'existe pas d�j�. Si create est d�fini � false, l'objet d'attachement va �tre retourn� seulement s'il a �t� cr�� pr�c�demment.

�tendre le QML - Exemple de propri�t�s attach�es montre le code complet utilis� pour impl�menter la propri�t� rsvp attach�e.

Gestion de la m�moire et type QVariant

Il est de la responsabilit� de l'�l�ment de s'assurer qu'il n'acc�de pas ou ne retourne pas de pointeur sur des objets invalides. QML fournit les garanties suivantes.

• Un objet affect� � une propri�t� pointeur sur un QObject (ou sur un objet d�riv� de QObject) sera valide au moment de l'affectation.

Apr�s l'affectation, il est de la responsabilit� de la classe de suivre la validit� de ce pointeur, soit par une m�thode sp�cifique de la classe, soit par la classe g�n�rique QPointer.

• Un objet affect� � un QVariant sera valide au moment de l'affectation.

Lors de l'affectation d'un objet � une propri�t� QVariant, QML utilisera toujours un QVariant de type QMetaType::QObjectStar. Il est de la responsabilit� de la classe de suivre la validit� de ce pointeur. Une r�gle g�n�rale lors de l'�criture d'une classe utilisant des propri�t�s QVariant est de v�rifier le type du QVariant lorsqu'il est affect�, et si le type n'est pas g�r� par votre classe, de r�affecter un QVariant invalide.

• Un objet affect� � une propri�t� liste de QObject (ou de d�riv�s de QObject) sera toujours valide au moment de l'affectation.

Apr�s affectation, il est de la responsabilit� de la classe de suivre la validit� de ce pointeur, soit par une m�thode sp�cifique de la classe, soit par la classe g�n�rique QPointer.

Les �l�ments doivent consid�rer que n'importe quel objet QML affect� peut �tre d�truit � tout moment, et r�agir en cons�quence. � condition de le documenter, un �l�ment peut ne plus fonctionner dans cette situation, mais il ne doit ne pas crasher.

Gestion des signaux

 BirthdayParty {
     onPartyStarted: console.log("This party started rockin' at " + time);
 }

Le code QML ci-dessus associe l'�valuation d'une expression JavaScript avec l'�mission d'un signal Qt.

Tous les signaux Qt d'une classe enregistr�e deviennent disponibles comme « propri�t�s signal » sp�ciales dans QML, des propri�t�s auxquelles l'utilisateur peut affecter une expression JavaScript unique. Le nom de la propri�t� signal est une version transform�e du nom du signal de Qt: « on » est ajout� au d�but et la premi�re lettre du nom du signal est mise en majuscule. Par exemple, le signal utilis� dans l'exemple ci-dessus poss�de la signature C++ suivante :

 signals:
     void partyStarted(const QTime &time);

Dans les classes poss�dant de multiples signaux avec le m�me nom, seul le signal final est accessible comme propri�t� signal. Notez que les signaux avec le m�me nom mais des param�tres diff�rents ne peuvent �tre distingu�s.

Les param�tres du signal deviennent accessibles par leur nom dans le script affect�. Un param�tre non nomm� ne peut �tre acc�d�, prenez donc soin de donner un nom � tous les param�tres du signal dans la d�claration C++. Les types intrins�ques list�s dans ajouter des types, ainsi que les types d'objets enregistr�s sont accept�s comme types de param�tre de signal. L'utilisation d'autres types n'est pas une erreur mais la valeur du param�tre ne sera pas accessible � partir du script.

�tendre le QML - l'exemple du support des signaux montre le code complet utilis� pour impl�menter la propri�t� signal onPartyStarted.

Si vous souhaitez utiliser les signaux � partir d'�l�ments cr��s en dehors de QML, vous pouvez acc�der � leurs signaux par le biais de l'�l�ment Connections.

De plus, si une propri�t� est ajout�e � la classe C++, tous les �l�ments QML bas�s sur cette classe auront un gestionnaire de signal value-changed pour cette propri�t�. Le nom du gestionnaire de signal est on<nom-de-la-propri�t�>Changed, avec la premi�re lettre du nom de la propri�t� en majuscule.

Note : le gestionnaire de signal QML sera toujours nomm� on<nom-de-la-propri�t�>Changed, sans tenir compte du nom utilis� pour le signal NOTIFY en C++. Nous recommandons l'utilisation de <nom-de-la-propri�t�>Changed() pour le signal NOTIFY en C++.

Voir aussi �criture de composants QML : propri�t�s, m�thodes et signaux

M�thodes

Les slots et m�thodes marqu�s Q_INVOKABLE deviennent des fonctions pouvant �tre appel�es depuis QML.

 BirthdayParty {
     host: Person {
         name: "Bob Jones"
         shoeSize: 12
     }
     guests: [
         Person { name: "Leo Hodges" },
         Person { name: "Jack Smith" },
         Person { name: "Anne Brown" }
     ]
 
     Component.onCompleted: invite("William Green")
 }

Dans cet exemple, une invitation est ajout�e via la m�thode invite() de l'�l�ment BirthdayParty. Cette fonction est rendue accessible en QML en marquant la m�thode invite() avec Q_INVOKABLE dans la classe BirthdayParty:

     Q_INVOKABLE void invite(const QString &name);

�tendre le QML - Exemple de m�thodes montre le code complet utilis� pour impl�menter la m�thode invite() .

La m�thode invite() est �galement rendue accessible si elle est d�clar�e comme slot.

Sources de valeur de propri�t�

 BirthdayParty {
     HappyBirthdaySong on announcement { name: "Bob Jones" }
 }

Le code QML ci-dessus applique une source de valeur de propri�t� � la propri�t� announcement. Une source de valeur de propri�t� g�n�re une valeur de propri�t� changeant au fil du temps.

Les sources de valeur de propri�t� sont souvent utilis�es pour effectuer une animation. Plut�t que de construire un objet et de d�finir manuellement la propri�t� « cible » de l'animation, une source de valeur de propri�t� peut �tre affect�e directement � une propri�t� de n'importe quel type et cr�er directement cette association.

L'exemple montr� ici est assez artificiel : la propri�t� « annonce » (announcement) de l'objet BirthdayParty est une chaine de caract�res qui est affich�e � chaque fois qu'elle re�oit une affectation et la valeur source HappyBirthdaySong g�n�re les paroles de la chanson « Happy Birthday ».

     Q_PROPERTY(QString announcement READ announcement WRITE setAnnouncement)

Normalement, l'affectation d'un objet � une propri�t� de chaine de caract�res n'est pas permise. Dans le cas de la source de valeur de propri�t�, plut�t que d'affecter l'instance de l'objet elle-m�me, le moteur QML d�finit une association entre la valeur source et la propri�t�.

Les sources de valeur de propri�t� sont des types sp�ciaux qui d�rivent de la classe QDeclarativePropertyValeurSource. Cette classe contient une seule m�thode, QDeclarativePropertyValeurSource::setTarget(), que le moteur QML invoque lors de l'association de la source de valeur de propri�t� � une propri�t�. La partie importante de la d�claration du type HappyBirthdaySong est :

 class HappyBirthdaySong : public QObject, public QDeclarativePropertyValeurSource
 {
     Q_OBJECT
     Q_INTERFACES(QDeclarativePropertyValeurSource)
 public:
     HappyBirthdaySong(QObject *parent = 0);
 
     virtual void setTarget(const QDeclarativeProperty &);
 };

� tous les autres �gards, les sources de valeur de propri�t� sont des types QML normaux. Ils doivent �tre enregistr�s dans le moteur QML en utilisant les m�mes macros que les autres types et peuvent contenir des propri�t�s, signaux et m�thodes � l'identique des autres types.

Lorsqu'une source de valeur de propri�t� est affect�e � une propri�t�, QML essaie d'abord de l'affecter normalement, comme pour un type QML habituel. C'est seulement dans le cas o� cette affectation �choue que le moteur appelle la m�thode setTarget(). Cela permet au type d'�tre aussi utilis� dans d'autres contextes que celui des valeurs source.

�tendre le QML - l'exemple de Property value Source montre le code complet de l'impl�mentation de la source de valeur de propri�t� HappyBirthdaySong.

Liaison de propri�t�

 BirthdayParty {
     id: theParty
 
     HappyBirthdaySong on announcement { name: theParty.host.name }
 
     host: Boy {
         name: "Bob Jones"
         shoe { size: 12; color: "white"; brand: "Nike"; price: 90.0 }
     }
 }

Le code QML ci-dessus utilise une liaison de propri�t� pour s'assurer que la propri�t� nom (name) de HappyBirthdaySong reste �gale � celle de l'h�te (host).

La liaison de propri�t� est une fonctionnalit� ma�tresse de QML. En plus d'affecter des valeurs litt�rales, la liaison de propri�t� permet au d�veloppeur d'affecter une expression JavaScript complexe qui peut inclure des d�pendances � d'autres propri�t�s. � chaque changement du r�sultat de l'expression - � travers le changement de l'une des valeurs de l'expression - l'expression est automatiquement r��valu�e et le nouveau r�sultat est affect� � la propri�t�.

Toutes les propri�t�s des types personnalis�s g�rent automatiquement la liaison de propri�t�. Toutefois, afin que la liaison fonctionne correctement, QML doit �tre capable de d�terminer de mani�re fiable qu'une propri�t� a �t� modifi�e, pour savoir quand r��valuer les liaisons d�pendant de cette valeur. QML compte sur la pr�sence du signal NOTIFY pour cette d�termination.

Voici la d�claration de la propri�t� h�te host :

     Q_PROPERTY(Person *host READ host WRITE setHost NOTIFY hostChanged)

L'attribut NOTIFY est suivi par un nom de signal. Il est de la responsabilit� du cr�ateur de la classe de s'assurer qu'� chaque fois que la valeur change, le signal NOTIFY est �mis. La signature du signal NOTIFY n'est pas importante pour QML.

Afin d'�viter les boucles ou les �valuations excessives, les d�veloppeurs doivent s'assurer que le signal n'est �mis que lorsque la valeur est r�ellement modifi�e. Si une propri�t� ou un groupe de propri�t�s sont rarement utilis�s, il est permis d'utiliser le m�me signal NOTIFY pour plusieurs propri�t�s. Cela doit �tre effectu� avec pr�caution pour �viter une d�gradation des performances.

Pour que QML reste fiable, si la propri�t� ne poss�de pas de signal NOTIFY, elle ne pourra pas �tre utilis�e comme expression de liaison. Cependant, la propri�t� peut toujours recevoir une affectation � une liaison car QML n'a pas besoin de surveiller les changements de cette propri�t� dans ce sc�nario.

Supposez un type personnalis�, TestElement, poss�dant deux propri�t�s, « a » et « b ». La propri�t� « a » n'a pas de signal NOTIFY et la propri�t� « b » a un signal NOTIFY.

 TestElement {
     // Cela est correct
     a: b
 }
 TestElement {
     // Cela ne fonctionnera pas
     b: a
 }

La pr�sence d'un signal NOTIFY a un l�ger impact sur les performances. Dans certains cas la valeur de la propri�t� est d�finie � la construction de l'objet, et ne change plus par la suite. Le plus courant de ces cas est lorsqu'un type utilise les propri�t�s group�es et que le groupe est allou� une seule fois et n'est lib�r� que lors de la destruction de l'objet. Dans ces cas, l'attribut CONSTANT peut �tre ajout� � la d�claration de la propri�t� � la place d'un signal NOTIFY.

     Q_PROPERTY(ShoeDescription *shoe READ shoe CONSTANT)

Ce cas doit faire l'objet d'un soin particulier car les applications utilisant votre type pourraient mal se comporter. L'attribut CONSTANT doit seulement �tre utilis� pour les propri�t�s dont les valeurs sont d�finies (et finalis�es) uniquement dans le constructeur de classe. Toutes les autres propri�t�s pouvant �tre utilis�es dans des liaisons doivent � la place poss�der un signal NOTIFY.

�tendre le QML - l'exemple de liaison pr�sente l'exemple BirthdayParty mis � jour pour inclure des signaux NOTIFY pour une utilisation dans des liaisons.

Les objets d'extension

 QLineEdit {
     leftMargin: 20
 }

Le code QML ci-dessus ajoute une nouvelle propri�t� � un type C++ existant sans modifier son code source.

Lors de l'int�gration de classes et de technologies existantes dans QML, leurs interfaces auront souvent besoin d'�tre ajust�es pour mieux s'adapter � l'environnement d�claratif. Bien que les meilleurs r�sultats soient normalement obtenus en modifiant directement les classes originales, si cela n'est pas possible ou trop compliqu� � cause d'autres contraintes, les objets d'extension permettent des extensions limit�es sans modification directe.

Les objets d'extension sont utilis�s pour ajouter des propri�t�s additionnelles � un type existant. Vous ne pouvez ajouter que des propri�t�s. Une d�finition de type �tendue permet au programmeur de fournir un type additionnel - appel� le type d'extension - lors de l'enregistrement d'une classe cible. Ces propri�t�s sont fusionn�es avec la classe de base et peuvent �tre utilis�es � partir de QML.

Une classe d'extension est un QObject normal, ayant un constructeur qui prend un pointeur sur QObject. Au moment o� cela est n�cessaire (la cr�ation d'une classe d'extension est retard�e jusqu'au premier acc�s � une propri�t� �tendue) la classe d'extension est cr��e et l'objet cible est pass� au constructeur comme parent. Lors de l'acc�s � une propri�t� �tendue de l'objet original, la propri�t� correspondante de l'objet �tendu est utilis�e � sa place.

Lorsqu'un type �tendu est d�fini, l'une de ces fonctions :

 template<typename T, typename ExtendedT>
 int qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
 
 template<typename T, typename ExtendedT>
 int qmlRegisterExtendedType()

doit �tre utilis�e � la place des variations de qmlRegisterType(). Les arguments sont les m�mes que pour les fonctions sans extension correspondantes, sauf pour le param�tre ExtendedT qui d�crit le type de l'objet d'extension.

Optimisation

Pour d�velopper des �l�ments � hautes performances, il est souvent utile d'en savoir plus sur l'�tat du moteur QML. Par exemple, il peut �tre b�n�fique d'effectuer l'initialisation de structure de donn�es co�teuses apr�s la fin de l'initialisation de toutes les propri�t�s.

Le moteur QML d�finit une classe d'interface appel�e QDeclarativeParserStatus, qui contient plusieurs m�thodes virtuelles appel�es � des moments divers de l'instanciation du composant. Pour recevoir ces notifications, l'impl�mentation d'un �l�ment doit h�riter de QDeclarativeParserStatus et doit informer le syst�me m�ta de Qt en utilisant la macro Q_INTERFACES().

Par exemple,

 class Example : public QObject, public QDeclarativeParserStatus
 {
     Q_OBJECT
     Q_INTERFACES(QDeclarativeParserStatus)
 public:
     virtual void componentComplete()
     {
         qDebug() << "Woohoo!  Now to do my costly initialization";
     }
 };

Remerciements

Merci � Alexandre Laurent pour la traduction ainsi qu'� Ilya Diallo, Jonathan Courtois, Thibaut Cuvelier et Claude Leloup pour leur relecture !