Modéliser en C++, designer avec QML : le jeu de patience

Tout d'abord on crée un nouveau fichier QML, Board.qml (attention la majuscule est importante !). Un fichier QML commençant par une majuscule met en place un composant réutilisable, que l'on pourra réutiliser à l'envi dans d'autres fichiers QML. Placer ce fichier dans le même répertoire que le fichier main.qml, de manière à être accessible directement. Une fois le fichier ouvert, il est possible de l'éditer en mode texte ou via le QML designer. Les deux sont complètement synchronisés, les modifications effectuées via l'un sont automatiquement répercutées sur l'autre.

Le langage QML est assez intuitif : il s'agit d'un langage déclaratif dans lequel on décrit l'interface, les composants et leur comportement. Il se présente sous la forme d'un arbre d'objets décrits par leurs propriétés.

Ajouter un élément texte, le positionner au centre (via les ancres) et dans le bas du tapis de jeu (board), avec une marge de 50 pixels par exemple. L'élément texte se place sous l'élément board dans l'arbre, il sera donc affiché par-dessus ce dernier. Dans le QML designer il est possible de glisser les éléments d'un niveau à l'autre à l'aide de la souris (l'arbre des objets est affiché en haut à gauche de l'écran). On peut obtenir après quelques manipulations simples le résultat montré ci-dessous. Les ancres sont le mécanisme de placement des objets de QML, on décrit simplement comment on positionne un objet par rapport aux autres (par exemple, placer la défausse à droite de la pile de cartes avec une marge de 50 pixels).

Toutes les fonctions de base sont accessibles dans le designer : on peut choisir la couleur, la police de caractères, l'alignement, etc. C'est assez facile à utiliser et l'avantage est que l'on voit tout de suite l'effet des modifications. Ci-dessous l'équivalent dans l'éditeur texte du code QML. Quelques points qui méritent explication :

• l'attribut id est un attribut réservé, il attribue un nom à notre élément pour y faire référence par la suite ;
• on positionne l'élément texte vis-à-vis du rectangle parent. On décide de le placer en bas, avec une marge de 10 pixels. Il est important de remarquer que le texte est entièrement contraint, positionné via les ancres. Il est centré horizontalement et attaché par le bas au rectangle. On ne lui fixe pas de taille (via width et height) car elle est déterminée par le texte et la police utilisée ;
• la taille donnée au rectangle vert (600x400) est une taille par défaut. Comme on définit le tapis en tant que nouvel élément réutilisable, il est de bonne pratique d'attribuer une taille par défaut.

import QtQuick 1.1

Rectangle {
    id: mainRectangle
    width: 600
    height: 400
    color: "#246612"

    Text {
        id: gameText
        color: "#f3eaea"
        text: "Game Name"
        font.pointSize: 50
        opacity: 0.3
        anchors.bottom: mainRectangle.bottom
        anchors.bottomMargin: 10
        anchors.horizontalCenter: mainRectangle.horizontalCenter
        font.family: "Verdana"
    }
}

Afin d'afficher le nouveau tapis dans l'application, éditer le fichier main.qml et y ajouter l'élément Board. Cela va simplement le positionner comme seul élément (on va en ajouter d'autres bientôt) de la fenêtre. Démarrer l'application : et voilà, ce n'est pas plus compliqué !

import QtQuick 1.1
Board {

}

Pour modifier le nom de la réussite, on va donner accès à la propriété text de l'élément texte du tapis à l'extérieur du composant. Pour ce faire, on définit un alias dans Board.qml de la manière suivante :

Rectangle {
    id: mainRectangle
     property alias gameName: gameText.text

    ...

On peut maintenant modifier cette propriété depuis main.qml :

Board {
    gameName: "nouveau jeu"
}

II-A-2-a. Exploration de main.cpp▲

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);  
    QmlApplicationViewer viewer;
    viewer.setOrientation(QmlApplicationViewer::ScreenOrientationAuto);
    viewer.setMainQmlFile(QLatin1String("qml/patience/main.qml"));
    viewer.showExpanded();  
    return app.exec();
}

II-A-2-b. Contexte▲

viewer.rootContext()->setContextProperty("m_gameName", "Solitaire");

Board {
    gameName: m_gameName
    ...
}

Avec le layout pour positionner le texte, on peut voir que le texte reste centré lorsqu'on redimensionne la fenêtre. Tout se passe très bien, excepté pour le texte, qui reste avec une grosse police quelle que soit la taille de la fenêtre. On peut remédier à cela en introduisant un peu de JavaScript. Dans l'élément texte, on place :

    font.pixelSize: Math.min(200, parent.width / text.length * 1.5)

Plutôt que d'avoir une taille de pixels fixe pour le texte, on lui donne une taille variable en fonction de divers paramètres que sont la taille de la fenêtre, le nombre de caractères du texte à afficher, etc. Il faut jouer avec la formule pour en voir l'effet, redimensionner la fenêtre et comparer avec une taille fixe.

On peut donc affecter une expression JavaScript à une propriété QML. Cette manière de faire est descriptive et non impérative (au contraire du C++) dans le sens où on décrit comment doit être le texte en fonction d'autres données (largeur de fenêtre ou autre). Ce lien est fort, car si la largeur est modifiée, la taille du texte sera mise à jour automatiquement, c'est un binding.

Les sources de cette partie sont disponibles : https://gitorious.org/patience/patience/trees/Chap_II-A-3.

On crée une nouvelle classe Card, qui hérite de QObject, modèle d'une carte à jouer. Pour le moment le modèle est très simple, on définit les propriétés de la carte via Q_PROPERTY :

• suite : cœur, carreau, trèfle ou pique ;
• valeur : de l'as au roi ;
• couleur : rouge ou noir ;
• retourné : si la carte est visible ou non.

class Card : public QObject
{
    Q_OBJECT
    Q_ENUMS(Color) 
    Q_ENUMS(Suit) 
    Q_ENUMS(Value) 
    Q_PROPERTY(Color color READ color NOTIFY colorChanged) 
    Q_PROPERTY(Suit suit READ suit NOTIFY suitChanged) 
    Q_PROPERTY(Value value READ value NOTIFY valueChanged) 
    Q_PROPERTY(bool flipped READ flipped() WRITE setFlipped NOTIFY flippedChanged)
public:
    enum Color { Red, Black };
    enum Suit { Hearts = 0, Diamonds, Clubs, Spades }; 
    enum Value { Ace = 1, Two, Three, Four, Five, Six, Seven, Height, Nine, Ten, Jack, Queen, King };
  
    ...
};

Les énumérations sont déclarées avec Q_ENUMS, c'est important afin que Qt et QML les reconnaissent comme si elles provenaient de Qt. Les propriétés sont ensuite définies et sont toujours accompagnées d'une clause NOTIFY qui renseigne le signal émis lorsque la propriété est modifiée. C'est du ressort du modèle C++ d'émettre ce signal à bon escient. La clause de notification est nécessaire pour maintenir la partie QML et la partie C++ synchronisée, c'est par ce biais que la partie QML saura que le modèle a changé et qu'elle pourra se mettre à jour. Techniquement, ces macros assurent l'indexation dans le système de métaobjets, pour plus de précisions techniques à ce sujet, je conseille la lecture de De QObject auxmétaobjets, une plongée au cœur des fondations de Qt .

Les propriétés couleur, suite et valeur sont en lecture seule (pas de méthode WRITE), ce qui signifie qu'elles ne pourront pas changer au cours du temps. C'est logique car une carte ne se transforme pas en une autre. Par contre la propriété flipped peut être modifiée, lorsqu'on veut retourner la carte par exemple.

Le constructeur initialise la valeur et la suite de la carte :

Card::Card(Suit s, Value v, bool flipped, QObject *parent) :
    m_suit(s),
    m_value(v), 
    QObject(parent), 
    m_flipped(flipped) 
{
    m_color = (s == Hearts || s == Diamonds) ? Red : Black;
}

La carte est invisible par défaut et la couleur est déduite de la suite dans le constructeur.

Les variables privées, accesseurs aux propriétés, etc. ne sont pas montrés ici, le code est simple et peut être examiné en détail dans le code source. Deux slots sont créés pour retourner la carte, on prend soin de n'émettre le signal de notification que lorsque l'état de la carte est modifié.

void Card::flip() {
    m_flipped = !m_flipped;
    emit flippedChanged(m_flipped); 
}

void Card::setFlipped(bool flip) {
    if (m_flipped != flip) {
        m_flipped = flip; 
        emit flippedChanged(flip); 
    }  
}

On ajoute Card.qml au projet, de nouveau avec une majuscule car c'est un composant. Ce composant va dessiner une carte à l'écran. On commence par la définition de quelques propriétés : flipped pour savoir si la carte est retournée ou non, ainsi que la suite et la valeur de la carte. On utilise Item comme élément racine car la carte va être composée de plusieurs sous-éléments. Un item est l'élément de base dont héritent tous les autres items graphiques.

Item {
    id: card
    width: 100
    height: 145

    property bool flipped: true
    property int suit: 0
    property int value: 1
}

On ajoute ensuite l'élément flipable comme premier composant de la carte, il s'agit d'un composant qui possède un avant et un arrière et qui permet de retourner l'objet, cela convient donc très bien pour une carte à jouer. On utilise anchors.fill : parent afin de spécifier que le flipable prend toute la place disponible dans le parent, c'est-à-dire dans la carte. Sur la face avant, on dessine un rectangle et dans un premier temps, on affiche en texte la valeur et la suite de la carte. La face arrière affiche une image de dos de carte, il suffit de placer le fichier image dans le dossier des fichiers QML.
Un élément QML a une notion de machine d'états : par défaut, il se trouve dans l'état défini par ses propriétés, dont le nom est la chaîne vide. Ici, on définit un état supplémentaire, que l'on nomme back : dans cet état, il faut tourner la carte de 180 °. Enfin, on indique que l'on se trouve dans l'état back quand la propriété flipped de la carte est vraie. Remarquez la beauté et la concision de l'écriture déclarative.
Chaque item peut également se voir attribuer des transformations géométriques (voir la documentation pour plus de détails sur les possibilités). Ici on définit la rotation de l'élément autour de l'axe y, rotation qui est utilisée pour tourner la carte lorsque l'on passe dans l'état retourné.
Enfin, chaque item peut définir des transitions, il s'agit ici d'animer le retournement afin que celui-ci s'étale sur 500 ms et soit donc visible par l'utilisateur.

Flipable {
    id: flipable
    anchors.fill: parent
    
    front: Rectangle {
        ...
    }
    
    back: Image {
        anchors.fill: parent
        source: "back.svg"
    }
    
    states: State {
        name: "back"
        PropertyChanges { target: rotation; angle: 180 }
        when: card.flipped
    }
    
    transform: Rotation {
        id: rotation
        origin.x: flipable.width/2
        origin.y: flipable.height/2
        axis.x: 0; axis.y: 1; axis.z: 0     // set axis.y to 1 to rotate around y-axis
        angle: 0                            // the default angle
    }
    
    transitions: Transition {
        NumberAnimation { target: rotation; property: "angle"; duration: 500 }
    }
}

Pour tester, il reste une chose à ajouter : une MouseArea pour retourner la carte lorsqu'on clique dessus. On définit cette zone de clic sur toute la carte, et on change simplement la propriété flipped de la carte lorsqu'on clique dessus !

Item {
    id: card

    ...

    Flipable {
    
    ...
    
    }

    MouseArea {
        anchors.fill: parent
        onClicked: card.flipped = !card.flipped
    }
}

setContextProperty peut aussi être utilisée pour ajouter un QObject au contexte : dans ce cas, toutes les propriétés, tous les signaux et tous les slots (plus les méthodes marquées Q_INVOKABLE) sont accessibles depuis le contexte QML.
Il est maintenant assez simple de fournir les cartes depuis le C++ afin que le QML puisse les afficher. On ajoute tout simplement dans le main.cpp les cartes au contexte QML.

Q_DECL_EXPORT int main(int argc, char *argv[])
{
    QScopedPointer<QApplication> app(createApplication(argc, argv));

    Card* card1 = new Card(Card::Hearts, Card::Six, true);
    Card* card2 = new Card(Card::Spades, Card::King, false);

    ...

    viewer.rootContext()->setContextProperty("m_card1", card1);
    viewer.rootContext()->setContextProperty("m_card2", card2);
    viewer.showExpanded();

    QTimer* timer = new QTimer();
    timer->setInterval(1000);
    QObject::connect(timer, SIGNAL(timeout()), card1, SLOT(flip()));
    QObject::connect(timer, SIGNAL(timeout()), card2, SLOT(flip()));
    timer->start();

    return app->exec();
}

Pour la démo, on ajoute un petit timer qui va retourner les deux cartes toutes les secondes. Ceci démontre que les propriétés des QObject sont liées au QML, et que lorsqu'elles changent de valeur le système en est averti (grâce au NOTIFY).
Ci-dessous on voit que le code QML de main.qml qui affiche les deux cartes est très simple : on place une carte via Card et on lie les propriétés flipped, suit et value à celles des données de la carte du modèle C++ (m_card).
Le désavantage de cette méthode est qu'il faut modifier le code à deux endroits, dans le QML et dans le C++ pour afficher un nouvel élément. Toute instance d'un objet que l'on veut afficher doit être créée côté C++ au préalable, on verra au point C qu'il existe une autre méthode qui permet au QML d'instancier directement autant d'objets C++ qu'il le désire !

Card {
    id: card1
    anchors.top: parent.top
    anchors.topMargin: 100
    anchors.left: parent.left
    anchors.leftMargin: 150
    suit: m_card1.suit
    value: m_card1.value
    flipped: m_card1.flipped
}

Vous l'aurez peut-être remarqué, le programme actuel comporte un petit bogue : en effet si on clique sur une carte pour la retourner manuellement, elle s'arrête de tourner toutes les secondes. En fait dans le MouseArea, on casse le binding original en effectuant une affectation directe de la propriété flipped :

onClicked: card.flipped = !card.flipped

Dans l'application finale, les clics de souris n'agiront plus directement sur l'état des cartes, mais enverront les signaux au modèle C++, qui décidera ce qu'il est bon de faire : de cette manière, on ne casse plus les binding des propriétés. Lien vers les sources du chapitre.

Afin de rendre le jeu moins austère, je propose un dessin à la main des cartes. N'étant pas un grand designer ce sera simple. On dispose de quatre images PNG des quatre couleurs de cartes : cœur, carreau, trèfle et pique. Les images sont placées dans le même répertoire que les fichiers QML et devront être distribuées avec les fichiers QML dans l'application finale. On crée un fichier QML supplémentaire, CardFace, qui représente la face d'une carte. Il s'architecture comme suit.

Rectangle {
    id: faceRoot
    property int suit: 0
    property int value: 10
    width: 100
    height: 145
    
    color: "#ffffff"
    radius: 6
    border.width: 1
    smooth: true
    border.color: "#000000"
    
    function imageSuitPath(suit) {
        if (suit === 0) return "Hearts.png"
        if (suit === 1) return "Diamonds.png"
        if (suit === 2) return "Clubs.png"
        if (suit === 3) return "Spades.png"
    }
    
    function valueToText(value) {
        if (value === 1) return "As"
        if (value < 11) return value + '';
        if (value === 11) return 'V';
        if (value === 12) return 'D';
        if (value === 13) return 'R';
    }
    
    Component {
        id: cardFaceCorner
        
        ...
    }

On commence par un rectangle, auquel on donne les propriétés suite et valeur (qui seront accessibles depuis l'extérieur) ainsi qu'une largeur et une hauteur par défaut et quelques caractéristiques de dessin : arrondis, etc. Ensuite on définit deux fonctions JavaScript utilisées plusieurs fois par la suite, la première donne le nom du fichier image en fonction de la suite de la carte, la seconde le texte à afficher en fonction de la valeur de la carte. On déclare un Component, il s'agit d'un composant QML, comme si on l'avait défini dans un fichier externe, qu'on va pouvoir répéter plusieurs fois. Le but ici est de dessiner le coin supérieur gauche, et de le répéter pour le coin inférieur droit.

Component {
    id: cardFaceCorner
    
    Item {
        Text {
            id: cornerText
            text: valueToText(value)
            anchors.left: parent.left
            anchors.top: parent.top
            font.pixelSize: faceRoot.width / 7
            ...
        }
        
        Image {
            id: cornerRightImage
            width: Math.min(faceRoot.width, faceRoot.height) / 7
            height: Math.min(faceRoot.width, faceRoot.height) / 7
            anchors.left: cornerText.right
            anchors.verticalCenter: cornerText.verticalCenter
            source: imageSuitPath(suit)
            ...
        }
        
        Image {
            id: cornerLowImage
            ...
        }
        
    }
}

Dans les grandes lignes on a : un texte et deux images, le dimensionnement des éléments se fait en fonction des dimensions de la carte (auxquelles on a accès grâce à la définition en ligne du composant). Il est intéressant de remarquer que le composant ne peut avoir qu'un seul item de premier niveau, tout comme dans un fichier QML. C'est pour cela que les trois éléments graphiques sont englobés dans un élément Item.

Loader {
    sourceComponent: cardFaceCorner
    anchors.top: faceRoot.top
    anchors.left: faceRoot.left
}

Loader {
    sourceComponent: cardFaceCorner
    rotation: 180
    anchors.bottom: faceRoot.bottom
    anchors.right: faceRoot.right
}

La déclaration du composant n'affiche rien, il faut instancier les éléments, une fois pour le coin supérieur gauche et une fois pour le coin inférieur droit. Afin de voir l'état d'avancement et surtout de peaufiner les paramètres de rendu (une marge de quatre pixels par-ci, un facteur d'échelle par-là), on peut lancer un aperçu du fichier CardFace.qml avec le QML Viewer. Dans Qt Creator, il suffit de presser F5 lorsqu'on édite le fichier QML, sinon menu Outils - Externe - QtQuick - Aperçu. C'est très pratique, on peut redimensionner la fenêtre, éditer le code (penser à sauver) et faire F5 dans le QML Viewer et le fichier QML se recharge automatiquement. Lien vers les sources de ce Chapitre.

Il est possible de créer un modèle très simplement en QML de la manière suivante :

ListModel {
    id: deckModel     
    ListElement {
        suit: 1
        value: 5
    }
    ListElement {
        suit: 2
        value: 10
    }
    ListElement {
        suit: 3
        value: 12
    }
}

Ceci crée un modèle liste de trois éléments, chacun disposant d'une propriété suit et value, ce qui permet de caractériser la carte à afficher. Chaque élément doit avoir les mêmes propriétés. Ce modèle n'est cependant pas un modèle C++, on ne s'y attardera donc pas dans cet article. Néanmoins, il peut s'avérer utile pour générer de petits modèles de test lors du prototypage de l'interface QML.

Le modèle exposé au paragraphe précédent peut être affiché par le code QML suivant :

Row {
    id: row1
    anchors.left: parent.left
    anchors.leftMargin: 0
    anchors.top: parent.top
    anchors.topMargin: 0
    Repeater {
        model: deckModel
        delegate: Card { suit: model.suit; value: model.value; flipped: false }
    }
}

Row est un élément QML qui n'affiche rien mais qui dispose simplement ses enfants en ligne, l'un à côté de l'autre (il existe l'équivalent Column). Chacun des éléments enfants de la ligne est créé par l'élément Repeater. Ce dernier prend en paramètres un modèle et un délégué pour l'affichage. Le modèle dans ce cas, est simplement l'identifiant du modèle de la section précédente. Le délégué est l'élément QML qui va être répété par le Repeater autant de fois que nécessaire (autant de fois que d'éléments dans le modèle) ; dans ce cas, il s'agit de l'élément Card auquel on passe les paramètres suit et value du modèle. Ci-dessous le résultat de ce code QML (à placer dans le main.qml par exemple).

La deuxième possibilité pour afficher une liste de cartes en QML est de transmettre une liste de QObject* de la manière suivante (main.cpp) :

  QList<QObject*> cardList;
  for (int i = 1; i < 14; i++) cardList.append(new Card(Card::Clubs, Card::Value(i), true));
  viewer.rootContext()->setContextProperty("m_cardList", QVariant::fromValue(cardList));

Cela transmet la liste d'objets comme valeur de la propriété m_cardList, qui peut ensuite être utilisée comme identifiant du modèle QML (dans le Repeater de la section précédente). La limitation de cette méthode réside dans le fait que, comme le suggère l'écriture QVariant::fromValue(cardList), une copie de la liste est passée au QML. Cette liste est donc statique, si plus tard on ajoute ou retire d'autres cartes de la liste, le système n'en sera pas averti, à moins d'appeler à nouveau la fonction setContextProperty.

La troisième solution, la plus puissante, requiert d'implémenter un QAbstractItemModel du framework modèle/vuew de Qt. Cette approche est puissante car elle utilise le modèle Qt déjà connu, cela permet d'utiliser une vue QML ou une vue classique très facilement. Cela requiert néanmoins un peu plus d'effort d'implémentation pour générer le modèle.

Voici le CardListModel très basique utilisé, il hérite de QAbstractListModel pour plus de facilité :

class CardListModel : public QAbstractListModel
{
    Q_OBJECT
public:
    enum CardRoles {
        SuitRole = Qt::UserRole + 1,
        ValueRole,
        FlippedRole,
        ColorRole
    };
public:
    explicit CardListModel(QObject *parent = 0);
    void pushCard(Card* card);
    void pushCards(QList<Card*> cards);
    Card* popCard();
    int rowCount(const QModelIndex &amp;parent = QModelIndex()) const;
    QVariant data(const QModelIndex &amp;index, int role) const;
public slots:
    void flipAll();
private:
    QList<Card*> m_cards;
};

Le stockage des cartes se fait dans une simple liste de Card*, les fonctions push et pop permettent d'ajouter et retirer des cartes du modèle. Attention de bien suivre les appels aux fonctions du modèle pour tout changement dans celui-ci (comme beginInsertRows) car sans cela la vue QML (ou n'importe quelle autre vue) ne sera pas synchronisée. Consultez la documentation (QAbstractItemModel) pour plus de détails à ce sujet si vous n'êtes pas familier du framework modèle vue de Qt.

On définit plusieurs rôles aux données du modèle, chacun étant une propriété de carte qui sera visible depuis le code QML. La fonction data est surchargée de manière à répondre aux demandes de données concernant ces nouveaux rôles :

QVariant CardListModel::data(const QModelIndex &index, int role) const {
    if (index.row() < 0 || index.row() > m_cards.count())
        return QVariant();  
    const Card *card = m_cards[index.row()];  
    if (role == SuitRole) return card->suit();
    if (role == ValueRole) return card->value();
    if (role == ColorRole) return card->color();
    if (role == FlippedRole) return card->flipped();
    return QVariant();
}

Afin que ces rôles nouvellement définis soient visibles depuis QML, il reste à les enregistrer, ce qui est fait dans le constructeur du modèle :

    QHash<int, QByteArray> roles;
    roles[SuitRole] = "suit";
    roles[ValueRole] = "value";
    roles[ColorRole] = "color";
    roles[FlippedRole] = "flipped";
    setRoleNames(roles);

Enfin le slot flipAll est là pour le show, il retourne chacune des cartes de la liste, et grâce au signal dataChanged, la vue QML sera toujours synchronisée.

void CardListModel::flipAll() {
    foreach(Card* card, m_cards) card->flip();
    emit dataChanged(index(0), index(rowCount() - 1));
}

Pour commencer, on réfléchit à la disposition des différents éléments sur l'écran les uns par rapport aux autres. On veut dessiner la donne et la défausse en haut à gauche, les as en haut à droite et le solitaire en bas de tout ça. Schématiquement, cela donne un dessin relativement flashy :

Grâce aux ancres QML, il est très facile de produire ce positionnement : il suffit d'indiquer à chaque rectangle où il se trouve par rapport aux autres éléments. On peut en voir l'effet très rapidement dans QtCreator via QML Viewer ou le designer.

Rectangle {
    property int globalMargin: 30

    height: 600
    width: 800

    Rectangle {
        id: deck
        anchors.left: parent.left
        anchors.top: parent.top
        anchors.leftMargin: globalMargin
        anchors.topMargin: globalMargin

        ...
    }

    Rectangle {
        id: discard
        anchors.left: deck.right
        anchors.top: parent.top
        anchors.topMargin: globalMargin
        anchors.leftMargin: globalMargin

        ...
    }

    Rectangle {
        id: aces
        anchors.right: parent.right
        anchors.top: parent.top
        anchors.topMargin: globalMargin
        anchors.rightMargin: globalMargin

        ...
    }

    Rectangle {
        id: solitaire
        anchors.top: aces.bottom
        anchors.left: parent.left
        anchors.right: parent.right
        anchors.bottom: parent.bottom
        anchors.margins: globalMargin

        ...
    }
}

On applique maintenant les techniques décrites précédemment pour construire, bloc par bloc, le solitaire. Pour commencer, on met l'élément Board en fond et on crée l'élément SolitaireModel, ce qui va instancier la classe Solitaire côté C++. On récupère alors la propriété name pour la fournir à l'élément Board. Voici à quoi ressemblent Solitaire.qml et Main.qml.

Item {
    width: 800
    height: 600

    Solitaire {
        anchors.fill: parent
    }
}

Item {
    property int globalMargin: 30

    SolitaireModel {
        id: solitaireModel
    }

    Board {
        anchors.fill: parent
        gameName: solitaireModel.name

        Rectangle {
            id: deck
            ...
        }

        Rectangle {
            id: discard
            ...
        }

        Rectangle {
            id: aces
            ...
        }

        Rectangle {
            id: solitaire
            ...
        }
    }
}

Petite remarque : main est le fichier QML principal, celui qui est exécuté par l'application. Dans ce cas, width et height donnent les dimensions par défaut de la fenêtre qui sera créée. Par contre pour le composant Solitaire, on ne donne ni dimensions ni ancrage (dans Solitaire.qml) car c'est un composant réutilisable, c'est à celui qui utilise Solitaire de le positionner et de le dimensionner, comme on le fait avec l'élément Rectangle. De fait on positionne et dimensionne le Solitaire depuis main.qml avec la ligne anchors.fill : parent, ce qui a pour effet que le solitaire prend toute la place disponible dans la fenêtre. On verra plus loin pour améliorer le design afin de pouvoir afficher aussi le Freecell.

Le deck et la défausse sont basés sur le modèle de liste, on va donc les afficher avec un nouveau composant QML : CardListView.qml. Il affiche les cartes côte à côte, et dispose des propriétés horizontalSpacing et verticalSpacing pour choisir d'afficher en ligne ou en colonne (ou en diagonale). Lorsqu'il n'y a pas de carte à afficher (modèle vide) on affiche un rectangle afin de représenter visuellement l'emplacement vide de la pile. Ce rectangle est totalement recouvert par la première carte de la liste. Ci-dessous le code simplifié de la vue QML. On utilise un simple Repeater pour gérer la création et la destruction des délégués (Card.qml). On stipule les propriétés x et y pour en contrôler la disposition. Note : le property alias donne simplement accès au modèle du répéteur depuis l'extérieur du composant.

Item {
    id: root
    property alias cardListModel : cardListView.model
    property int horizontalSpacing: 25
    property int verticalSpacing: 25

    signal cardClicked(int index, int suit, int value)

    width: cardsWidth + horizontalSpacing * Math.max(0, (cardListView.count - 1))
    height: cardsHeight + verticalSpacing * Math.max(0, (cardListView.count - 1))

    Rectangle {
        anchors.left: parent.left
        anchors.top: parent.top
        anchors.leftMargin: 2
        anchors.topMargin: 2
        width: cardsWidth - 4
        height: cardsHeight - 4
        radius: 5
        border.width: 3
        color: "transparent"
        border.color: "black"

        MouseArea {
            anchors.fill: parent
            onClicked: root.cardClicked(-1, -1, -1);
            onDoubleClicked: root.cardDoubleClicked(-1, -1, -1);
        }
    }

    Repeater {
        id: cardListView

        delegate: Card {
            id: thiscard
            x: horizontalSpacing * index
            y: verticalSpacing * index
            value: model.value;
            suit: model.suit;
            flipped: model.flipped;
            onClicked: root.cardClicked(index, suit, value)
        }
    }
}

À présent, on remplace dans le mockup les rectangles de la pioche et de la défausse par CardListView. Sans changer quoi que ce soit aux ancres, on renomme les Rectangle par des CardListView et on ajoute les propriétés qui vont bien. Afin de démontrer le bon fonctionnement, on remonte le signal clicked sur le deck et on appelle le slot drawCards du solitaire. Le code QML reste élégamment simple. Le code C++ appelé met à jour les modèles sous-jacents et les vues se tiendront automatiquement synchronisées.

CardListView {
    id: deck
    cardListModel: solitaireModel.deckModel()
    horizontalSpacing: 0
    verticalSpacing: 0
    
    anchors.left: parent.left
    anchors.top: parent.top
    anchors.leftMargin: globalMargin
    anchors.topMargin: globalMargin
    
    MouseArea {
        anchors.fill: parent
        onClicked: { drawCards(); }
    }
}

CardListView {
    id: discard
    cardListModel: solitaireModel.discardModel()
    horizontalSpacing: 30
    verticalSpacing: 0
    
    anchors.left: deck.right
    anchors.top: parent.top
    anchors.topMargin: globalMargin
    anchors.leftMargin: globalMargin
}

Afin que tout ceci fonctionne, il faut enregistrer les classes modèles dans le main.cpp comme ci-dessous. Sans cela, rien ne s'affiche.

qmlRegisterType<Solitaire>("Patience", 1, 0, "SolitaireModel");

qmlRegisterType<CardListModel>();
qmlRegisterType<QAbstractItemModel>();
qmlRegisterType<CardStacksModel>();

Ci-dessous, le résultat, exécuter l'application et cliquer sur la pioche pour voir les cartes défiler dans la défausse. Une fois la pioche vide, c'est la défausse qui est rechargée sur le tas. Remarque : on ne voit toujours que les trois dernières cartes dans la défausse, cela est voulu dans le jeu du solitaire (celui de mon grand-père en tous cas :p). En fait si on examine le code C++, on voit que le modèle de la défausse renvoyé est un proxy sur la défausse totale, proxy qui filtre les cartes pour n'afficher que les trois dernières. Lien vers les sources de la section.

Les vues QML ne sont prévues que pour des modèles de liste : dès que le modèle devient plus compliqué, il faut ruser. C'est ici qu'intervient l'élément QML « VisualDataModel », assez compliqué ; on va essayer de le décrire au mieux. Tout d'abord, cet élément, comme son nom semble l'indiquer, est un modèle : il peut être utilisé partout où un modèle est demandé. Sa particularité est d'être visuel : en fait, il encapsule également le délégué (dans la terminologie Qt). C'est donc une espèce de modèle qui fournit des données mais aussi le délégué pour les visualiser.

Dans le cas présent, le VisualDataModel a une propriété très intéressante : on peut lui assigner un nœud du modèle via un QModelIndex, il se comporte alors comme la liste des enfants de ce nœud. De cette manière, il est possible d'itérer récursivement dans la profondeur d'un modèle en arbre de n'importe quel type (QAbstractItemModel). Afin d'afficher les colonnes du jeu, on crée un composant CardStackView, qui affiche les colonnes les unes à côté des autres ; pour afficher les colonnes, on réutilise le CardListView vu au paragraphe précédent.

Pour commencer, on modifie CardListView de manière à utiliser un VisualDataModel : pour la liste, cela ne change rien, car le nœud utilisé par défaut est la racine. Dans le code de CardListView, on donne accès aux propriétés model et rootIndex à l'extérieur du composant. On remplace le modèle qui était attribué directement par un composant VisualDataModel auquel on attribue le model et le rootIndex.

Item {
    id: root
    property alias cardListModel: cardListDataModel.model
    property alias cardListModelIndex: cardListDataModel.rootIndex

    ...

    Repeater {
        id: cardListView
        model: VisualDataModel {
            id: cardListDataModel

            delegate: Card {
            ...
            }
        }
    }
}

Ensuite, du côté de CardStackView, on crée une ligne dans laquelle on répète une CardListView. On utilise aussi ici un VisualDataModel, simplement pour avoir accès à la fonction modelIndex(int) qui renvoie un QModelIndex que l'on attribue au rootIdex de CardListView. Le code est somme toute assez simple, expressif et bien réutilisé.

Item {
    id: root
    property QtObject cardStackModel

    ...

    Row {
        spacing: horizontalSpacing

        Repeater {
            id: stackRow
            model: VisualDataModel {
                id: visualModel
                model: cardStackModel
                delegate: CardListView {
                    horizontalSpacing: 0
                    verticalSpacing: root.verticalSpacing

                    cardListModelIndex: visualModel.modelIndex(index)
                    cardListModel: cardStackModel
                }
            }
        }
    }
}

Il reste bien sûr à remplacer les rectangles du mockup, par les CardStackView, ce qui se fait aisément comme pour les listes. Voici le résultat actuel, le jeu commence à prendre forme.