ELCa11 - Tuto : créer un composant QML réutilisable¶

Objectifs¶

Créer un composant QML personnalisé (MyComponent) à partir d’éléments simples (Rectangle, Text).
Exposer une propriété via la mécanique des alias pour la rendre modifiable depuis l’extérieur.
Instancier le composant plusieurs fois dans une fenêtre.
Ajouter de l’interactivité : réactions aux touches du clavier et aux clics souris.

Prérequis¶

Qt installé avec le composant Qt Quick (voir TutoInstallQT).
Un projet Qt Quick déjà créé au moins une fois (ce tuto guide la création depuis zéro).

Note système de build — pour ce tuto on utilise CMake (et non qmake comme dans les BEs C++ du cours). Qt 6 recommande CMake pour les projets Qt Quick, et c’est ce que propose Qt Creator par défaut. CMake est livré avec Qt : rien de plus à installer.

Étape 1 — Créer le projet Qt Quick¶

Lancer Qt Creator.
Menu Fichier > Nouveau projet….
Sélectionner Application (Qt) > Application Qt Quick > Choisir….
Renseigner :
- le nom du projet : TestPluginComponent ;
- le répertoire où il sera créé.
Système de build : CMake.
Minimal Qt version : Qt 6.x (la plus récente disponible).
Sélectionner le kit auto-détecté (Desktop Qt 6.x.y …).
Valider les écrans suivants par défaut, puis Terminer.

Qt Creator génère un projet contenant :

CMakeLists.txt — la configuration du projet (équivalent du .pro côté qmake).
Main.qml — l’écran principal de l’application.
main.cpp — le programme C++ qui charge Main.qml au démarrage.

Vous pouvez tester que tout marche avec Ctrl+R / Cmd+R : une petite fenêtre vide s’affiche.

Étape 2 — Créer le composant `MyComponent`¶

Un composant QML est simplement un fichier .qml dont le premier caractère du nom est en majuscule (convention obligatoire en QML).

Clic droit sur le projet dans la barre latérale > Ajouter un nouveau….
Sélectionner Qt > Fichier QML (Qt Quick) > Choisir….
Nom du fichier : MyComponent (Qt ajoute l’extension .qml). Important : la majuscule à M est obligatoire.
Valider.

Qt Creator crée le fichier MyComponent.qml et l’ajoute automatiquement au module QML (CMakeLists.txt est mis à jour pour vous — pas d’action manuelle nécessaire, contrairement à l’ancien système .qrc).

Ouvrir MyComponent.qml et basculer en mode Conception (icône en bas à gauche, ou Mode > Design).

Construire le composant :

Identifiant du Rectangle racine : monPlugin (à modifier dans le panneau Propriétés > champ id).
Réduire la taille du rectangle à 90×60 pixels (panneau Propriétés > Geometry > Width, Height).
Ajouter un élément Text (depuis le panneau Bibliothèque à gauche, glisser-déposer).
- lui donner l’identifiant plugTexte ;
- le centrer dans le rectangle (drag, ou Anchors > centrer) ;
- taille de police : 24 pixels ;
- texte affiché : votre prénom (par exemple Ahmed).

Étape 3 — Exposer la propriété texte via un alias¶

Un alias QML rend une propriété d’un élément interne accessible depuis l’extérieur. C’est la base pour pouvoir réutiliser le composant avec des contenus différents.

Sélectionner l’élément Text (plugTexte).
Dans le panneau Propriétés, cliquer sur l’icône en forme d’engrenage à droite du champ Text.
Choisir Export Property as Alias.

Cette action génère automatiquement, dans la section Code du fichier MyComponent.qml, la ligne :

property alias plugTextText: plugTexte.text

plugTextText est désormais une propriété publique du composant MyComponent. Toute instance pourra fixer son texte via cette propriété.

Refaire la même opération pour la couleur du texte : sélectionner plugTexte, cliquer sur l’engrenage à côté de Color, choisir Export Property as Alias. Cela génère :

property alias plugTextColor: plugTexte.color

Étape 4 — Intégrer le composant dans `Main.qml`¶

Ouvrir Main.qml, basculer en mode Conception.

Modifier les dimensions de la Window racine en 300×100.
Ajouter un Rectangle qui remplit la fenêtre, et lui donner l’identifiant fond. Lui donner une couleur de fond claire (par ex. lightyellow).
Dans la propriété Avancé du rectangle, mettre focus: true (nécessaire pour que les événements clavier soient reçus — voir Étape 5).
Le composant MyComponent apparaît automatiquement dans le panneau Composants > My Components à gauche. Glisser-déposer deux instances dans le rectangle :
- première instance : identifiant prenom1, positionnée à gauche ;
- seconde instance : identifiant prenom2, positionnée à droite.

Convention : les identifiants d’instances commencent par une minuscule, sans espaces (prenom1, prenom2). C’est la règle inverse de celle des composants.

Pour chaque instance, dans le panneau Propriétés > Exposed Custom Properties, modifier :
- plugTextText de prenom1 → Alba ;
- plugTextText de prenom2 → Irina.

Astuce : à côté du champ plugTextText, un petit bouton tr apparaît. Cliquer dessus pour qu’il devienne bleu — la chaîne sera alors enveloppée dans qsTr(...), ce qui la rend traduisible si on veut localiser l’application un jour.

Étape 5 — Interactivité clavier¶

On veut qu’appuyer sur la touche A change le texte de prenom1 en Alba.

Basculer Main.qml en mode Édition et ajouter, à l’intérieur du Rectangle (fond) :

Keys.onPressed: (event) => {
    if (event.key === Qt.Key_A) {
        prenom1.plugTextText = qsTr("Alba")
        console.log(event.key + " /// " + event.text)
        event.accepted = true
    }
}

event.accepted = true : indique au moteur QML que cet événement a été consommé. Sinon, l’événement remonte dans la hiérarchie et peut être attrapé par d’autres Keys.onPressed. Bonne pratique : marquer comme accepté quand on a effectivement agi sur l’événement.

Tester : Ctrl+R / Cmd+R, cliquer dans la fenêtre pour qu’elle prenne le focus, puis appuyer sur A. Le premier prénom doit changer.

Si rien ne se passe : vérifier que la propriété focus: true est bien sur le Rectangle (fond).

Étape 6 — Interactivité souris¶

On veut qu’un clic gauche sur le second prénom (Irina) change la couleur de sa police.

En mode Conception sur Main.qml, depuis le panneau Bibliothèque, ajouter un élément MouseArea dans le rectangle fond.
Déplacer prenom2 comme enfant de MouseArea (drag dans le panneau Navigateur).

La hiérarchie résultante doit être :

Window
└── Rectangle (fond)
    ├── prenom1
    └── MouseArea
        └── prenom2

Ajuster la taille et la position de MouseArea pour qu’elle englobe la zone de clic souhaitée (typiquement, l’emprise visuelle de prenom2).

Basculer en mode Édition, et dans MouseArea, ajouter :

onClicked: prenom2.plugTextColor = "#51c3e1"

Tester. Cliquer sur la zone qui contient Irina doit changer sa couleur en bleu clair. Cliquer en dehors ne doit rien faire.

Étape 7 — Code final attendu¶

MyComponent.qml :

import QtQuick

Rectangle {
    id: monPlugin
    width: 90
    height: 60

    property alias plugTextText:  plugTexte.text
    property alias plugTextColor: plugTexte.color

    Text {
        id: plugTexte
        anchors.centerIn: parent
        font.pixelSize: 24
        text: qsTr("Ahmed")
    }
}

Main.qml :

import QtQuick

Window {
    width: 300
    height: 100
    visible: true
    title: qsTr("TestPluginComponent")

    Rectangle {
        id: fond
        anchors.fill: parent
        color: "lightyellow"
        focus: true

        Keys.onPressed: (event) => {
            if (event.key === Qt.Key_A) {
                prenom1.plugTextText = qsTr("Alba")
                console.log(event.key + " /// " + event.text)
                event.accepted = true
            }
        }

        MyComponent {
            id: prenom1
            x: 20
            y: 20
            plugTextText: qsTr("Alba")
        }

        MouseArea {
            x: 180; y: 20
            width: 100; height: 60

            onClicked: prenom2.plugTextColor = "#51c3e1"

            MyComponent {
                id: prenom2
                anchors.fill: parent
                plugTextText: qsTr("Irina")
            }
        }
    }
}

Vérifier que la fenêtre lancée :

affiche les deux prénoms (Alba à gauche, Irina à droite) ;
réagit à l’appui de A (le prénom de gauche change) ;
réagit au clic gauche sur la zone d’Irina (sa couleur passe au bleu clair).