Apostille au MVC : les délégués

Tous les modèles fournis par Qt sont basés sur la classe QAbstractItemModel. Cette classe est la plus abstraite et la plus haute dans la hiérarchie des classes des différents modèles. Cette classe fournit une interface que tous les modèles doivent respecter, afin d'être utilisés correctement avec une vue.

• QStringListModel : stockage d'une liste de QString ;
• QFileSystemModel : un ensemble d'informations sur un fichier ou un répertoire du système de fichier local (anciennement QDirModel) ;
• QStandardItemModel : gestion de tout type de structure, complexe ou non ;
• QSqlTableModel, QSqlRelationalTableModel : accès à une base de données (SQLite, MySQL...).

Cependant, il arrive parfois (voire souvent) que ces modèles ne conviennent pas à l'utilisation et que l'on souhaite créer ses propres modèles. Pour cela, rien de réellement complexe. Il suffit en effet de créer une classe dérivant d'une des classes suivantes :

• QAbstractItemModel : comme évoqué plus haut, il s'agit de la classe la plus abstraite ;
• QAbstractListModel : classe abstraite fournissant une interface pour un modèle de type liste (associé à une QListView) ;
• QAbstractTableModel : classe abstraite fournissant une interface pour un modèle de type tableau (associé à une QTableView).

À noter qu'il n'existe pas de classe séparée pour un modèle de type hiérarchique (QTreeView). Il s'agit simplement de QAbstractItemModel.

Vous remarquerez que toutes ces classes utilisent la même racine, à savoir QAbstractXModel.

Une fois que l'on a choisi la classe de base convenant le mieux à notre utilisation, il ne reste plus qu'à redéfinir certaines méthodes virtuelles comme :

• int QAbstractItemModel::rowCount(const QModelIndex & parent = QModelIndex()) const : fonction retournant le nombre de lignes du modèle ;
• QVariant QAbstractItemModel::data(const QModelIndex & index, int role = Qt::DisplayRole) const : fonction renvoyant la donnée associée au rôle role pour l'index index.

Pour des modèles modifiables, il est aussi nécessaire de redéfinir la fonction bool QAbstractItemModel::setData(const QModelIndex & index, const QVariant & value, int role = Qt::EditRole).

La création de modèles personnalisés n'est cependant pas l'objet de ce tutoriel. Bien que nous l'aborderons brièvement au travers d'un exemple, je vous renvoie à la documentation traitant le sujet en profondeur.

• QListView : liste d'éléments ;
• QTableView : tableau d'éléments ;
• QTreeView : représentation d'éléments sous forme hiérarchique (arbre d'éléments).

Une fois la vue choisie, le modèle y est affecté en utilisant la fonction void QAbstractItemView::setModel(QAbstractItemModel * model).

Pour davantage de précisions, libre à vous de vous reporter à la documentation.

class TableModel : public QAbstractTableModel
{
    Q_OBJECT
public:
    enum Columns { Element = 0, Value, Count = Value + 1 };

    explicit TableModel(QObject *parent = 0);

    Qt::ItemFlags flags(const QModelIndex &index) const;
    int rowCount(const QModelIndex &parent = QModelIndex()) const;
    int columnCount(const QModelIndex &parent = QModelIndex()) const;

    QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const;
    QVariant headerData(int section, Qt::Orientation orientation, int role = Qt::DisplayRole) const;
    bool setData(const QModelIndex &index, const QVariant &value, int role = Qt::DisplayRole);

    void addElement(const QString &element, int value);

private:
    QList<QPair<QString, int> > mElements;

};

Pour des raisons de lisibilité et flexibilité, on définit une énumération Columns permettant de lister les différentes colonnes. Count est une petite astuce pour obtenir le nombre d'éléments et servira pour la méthode columnCount().

La méthode Qt::ItemFlags flags(const QModelIndex & index) const; sera utile pour décider quelles parties de notre modèle seront éditables ou non (la colonne des éléments sera en lecture seule).

Les éléments seront stockés à l'intérieur d'une liste de QPair. Pour rappel, une paire est un ensemble composé de deux éléments. Le premier élément sera le texte QString et le deuxième la valeur associée (int). La méthode void addElement(const QString & element, int value); permettra d'ajouter un élément à l'intérieur du modèle.

Qt::ItemFlags TableModel::flags(const QModelIndex &index) const
{
    if (index.column() == Element)
    {
        return Qt::ItemIsEnabled | Qt::ItemIsSelectable;
    }
    else if (index.column() == Value)
    {
        return Qt::ItemIsEnabled | Qt::ItemIsSelectable | Qt::ItemIsEditable;
    }

    return QAbstractTableModel::flags(index);
}

À l'intérieur de la fonction, on vérifie la colonne visée grâce à la méthode column() de index. Si la colonne est la colonne des éléments (Element), on retourne les drapeaux Qt::ItemIsEnabled | Qt::ItemIsEnabled. Ceci signifie que notre élément sera activé et sélectionnable mais pas éditable. Si la colonne est la colonne des valeurs (Value), on y ajoute le drapeau Qt::ItemIsEditable, permettant à l'utilisateur d'éditer l'élément.

Si on ne se trouve dans aucune de ces configurations (ce qui ne devrait pas être le cas ici), on laisse la responsabilité à la classe de base de retourner les drapeaux nécessaires.

int TableModel::columnCount(const QModelIndex &parent) const
{
    return parent.isValid() ? 0 : Count;
}

Si l'index parent est valide (ce modèle n'est pas hiérarchique), on renvoie 0, sinon Count (énumération précédemment définie).

int TableModel::rowCount(const QModelIndex &parent) const
{
    return parent.isValid() ? 0 : mElements.count();
}

Comme précédemment, on renvoie 0 si parent est valide. Sinon, le nombre de lignes du modèle correspond au nombre d'éléments de mElements : mElements.count().

QVariant TableModel::data(const QModelIndex &index, int role) const
{
    if (!index.isValid() || index.row() < 0 || index.row() >= mElements.count())
    {
        return QVariant();
    }

    switch (role)
    {
    case Qt::DisplayRole:
    case Qt::EditRole:
        if (index.column() == Element)
        {
            return mElements[index.row()].first;
        }
        else if (index.column() == Value)
        {
            return mElements[index.row()].second;
        }
        break;
    }

    return QVariant();
}

On commence par vérifier la validité de l'index. Si tel n'est pas le cas, on renvoie une donnée invalide : QVariant().

On renvoie ensuite, selon le rôle role, la donnée correspondante. Dans ce modèle, on prend en compte les rôles Qt::DisplayRole et Qt::EditRole. S'il s'agit d'un de ces deux rôles, on renvoie le premier élément de la paire correspondant à l'index index si la colonne est Element ou bien le second pour la colonne Value.

Pour tous les rôles restants, on retourne une donnée invalide.

QVariant TableModel::headerData(int section, Qt::Orientation orientation, int role) const
{
    if (orientation == Qt::Horizontal && role == Qt::DisplayRole)
    {
        switch (section)
        {
        case Element:
            return trUtf8("Elément");
            break;
        case Value:
            return trUtf8("Valeur");
            break;
        }
    }

    return QAbstractTableModel::headerData(section, orientation, role);
}

Ce code ne devrait pas avoir besoin de descriptions supplémentaires. Si on est dans l'orientation Horizontal avec le rôle DisplayRole, on renvoie le texte correspondant à la section (colonne).

bool TableModel::setData(const QModelIndex &index, const QVariant &value, int role)
{
    if (!index.isValid() || index.row() < 0 || index.row() >= mElements.count())
    {
        return false;
    }

    switch (role)
    {
    case Qt::DisplayRole:
    case Qt::EditRole:
        if (index.column() == Element)
        {
            mElements[index.row()].first = value.toString();
        }
        else if (index.column() == Value)
        {
            mElements[index.row()].second = value.toInt();
        }
        emit dataChanged(index, index);
        return true;
        break;
    }

    return false;
}

Voir la fonction data(). Il est par ailleurs important de prendre soin d'émettre le signal void QAbstractItemModel::dataChanged(const QModelIndex & topLeft, const QModelIndex & bottomRight), afin de notifier à la vue que les données ont changé.

void TableModel::addElement(const QString &element, int value)
{
    const int count = mElements.count();
    if (value < 0)
    {
        value = 0;
    }
    else if (value > 100)
    {
        value = 100;
    }
    beginInsertRows(QModelIndex(), count, count);
    mElements << qMakePair(element, value);
    endInsertRows();
}

On commence par récupérer le nombre d'éléments courant puis on s'assure que value est comprise entre 0 et 100. La fonction void QAbstractItemModel::beginInsertRows(const QModelIndex & parent, int first, int last) permet de commencer une opération d'insertion de ligne dans un modèle (il est nécessaire de l'appeler). Après avoir ajouté l'élément à l'intérieur de la liste en utilisant la fonction utilitaire QPair<T1, T2> qMakePair(const T1 & value1, const T2 & value2), on termine l'opération d'insertion avec endInsertRows().

En vous aidant de la documentation, modifiez le modèle afin que les éléments de la première colonne soient alignés de manière centrée.

Premier indice : la fonction à modifier est data().

Deuxième indice : le rôle à gérer est Qt::TextAligmentRole.

case Qt::TextAlignmentRole:
    if (index.column() == Element)
    {
         return Qt::AlignCenter;
    }
    break;

class TableDelegate : public QStyledItemDelegate
{
    Q_OBJECT
public:
    explicit TableDelegate(QObject *parent = 0);
    QWidget *createEditor(QWidget *parent, const QStyleOptionViewItem &option, const QModelIndex &index) const;
    void setEditorData(QWidget *editor, const QModelIndex &index) const;
    void setModelData(QWidget *editor, QAbstractItemModel *model, const QModelIndex &index) const;

    void paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const;
    void updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem &option, const QModelIndex &index) const;

};

Aucune surprise ici. On crée une classe TableDelegate héritant de QStyledItemDelegate et on redéfinit les méthodes nécessaires (voir précédemment).

QWidget *TableDelegate::createEditor(QWidget *parent, const QStyleOptionViewItem &option,
                                    const QModelIndex &index) const
{
    if (index.column() == TableModel::Value)
    {
        QSlider *editor = new QSlider(Qt::Horizontal, parent);
        editor->setRange(0, 100);
        editor->setAutoFillBackground(true);
        return editor;
    }

    return QStyledItemDelegate::createEditor(parent, option, index);
}

Comme à l'habitude, on agit en fonction de la colonne (column()). Dans le cas de la colonne Value, on crée un QSlider horizontal. On lui affecte un intervalle de valeurs de 0 à 100 et on place la propriété autoFillBackground à true afin d'obtenir un fond opaque. Sinon, on laisse la responsabilité à la classe parente de créer l'éditeur.

void TableDelegate::setEditorData(QWidget *editor, const QModelIndex &index) const
{
    if (index.column() == TableModel::Value)
    {
        QSlider *slider = qobject_cast<QSlider *>(editor);
        if (slider)
        {
            const int value = index.model()->data(index).toInt();
            slider->setValue(value);
        }
    }
    else
    {
        QStyledItemDelegate::setEditorData(editor, index);
    }
}

Afin d'initialiser correctement le curseur, on récupère la valeur correspondante dans le modèle à l'index index (que l'on n'oublie pas de convertir en int, la fonction data() renvoyant un QVariant) puis on l'affecte au curseur en appelant la fonction setValue(). Le paramètre editor étant de type QWidget, on n'oublie pas de le convertir en QSlider à l'aide de qobject_cast.

void TableDelegate::setModelData(QWidget *editor, QAbstractItemModel *model, const QModelIndex &index) const
{
    if (index.column() == TableModel::Value)
    {
        QSlider *slider = qobject_cast<QSlider *>(editor);
        if (editor)
        {
            model->setData(index, slider->value());
        }
    }
    else
    {
        QStyledItemDelegate::setModelData(editor, model, index);
    }
}

On réalise ici l'opération inverse. Lors de la fin de l'édition, on récupère la valeur du curseur puis on l'affecte à notre modèle à l'index index. Ceci permet donc de mettre à jour le modèle une fois l'édition terminée et l'éditeur fermé.

void TableDelegate::updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem &option,
                                         const QModelIndex &index) const
{
    Q_UNUSED(index);
    editor->setGeometry(option.rect);
}

Comme convenu, on met à jour la géométrie (position et taille) de l'éditeur via les informations du paramètre option. La macro Q_UNUSED permet de marquer le paramètre index comme non utilisé, afin de ne pas obtenir d'avertissement lors de la compilation (unused parameter).

void TableDelegate::paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const
{
    if (index.column() == TableModel::Value)
    {       
        painter->save();
        const int value = index.model()->data(index).toInt();
        QRect rect(option.rect);
        const int width = (value * rect.width()) / 100;
        rect.setWidth(width);
        QColor c;
        if (value <= 20)
        {
            c = Qt::red;
        }
        else if (value <= 50)
        {
            c = QColor(240, 96, 0);
        }
        else
        {
            c = Qt::green;
        }

        painter->fillRect(rect, c);
        QTextOption o;
        o.setAlignment(Qt::AlignCenter);
        painter->drawText(option.rect, QString("%1 %").arg(value), o);

        painter->restore();
    }
    else
    {
        QStyledItemDelegate::paint(painter, option, index);
    }
}

Pour finir, la partie rendu. Souhaitant uniquement agir sur la colonne des valeurs, on commence par vérifier si on est dans ce cas. Sinon, on laisse la responsabilité à la classe parente d'effectuer le rendu.

On commence par enregistrer (sauvegarder) l'état courant du painter. On récupère la valeur située à l'index correspondant afin de calculer la largeur effective de la barre grâce à un simple produit en croix. On obtient donc un rectangle QRect. On en profite pour affecter une couleur différente selon la valeur correspondante :

• rouge si la valeur est inférieure ou égale à 20 ;
• orange si la valeur est inférieure ou égale à 50 ;
• vert sinon.

Disposant du rectangle et de sa couleur, on utilise la fonction fillRect() pour dessiner et remplir le rectangle de la couleur correspondante. Pour finir, on dessine le texte correspondant à la valeur suivie du pourcentage, de manière centrée, avant de restaurer l'état du painter préalablement sauvegardé.

Ceci conclut donc le programme. Il est laissé au soin du lecteur de le compléter en créant la vue, le modèle puis le délégué avant de remplir le modèle des valeurs souhaitées, afin d'avoir un programme complet et opérationnel.