QRangeModel Class

Description détaillée

QRangeModel permet de mettre les données de n'importe quel type C++ itérable de manière séquentielle à la disposition du framework modèle/vue de Qt. Cela facilite l'affichage des structures de données existantes dans les vues d'éléments « Qt Widgets » et « Qt Quick », et permet à l'utilisateur de l'application de manipuler les données à l'aide d'une interface utilisateur graphique.

Pour utiliser QRangeModel, instanciez-le avec une plage C++ et définissez-le comme modèle d’une ou plusieurs vues :

std::array<int, 5> numbers = {1, 2, 3, 4, 5};
QRangeModel model(numbers);
listView.setModel(&model);

Construction du modèle

La plage peut être n’importe quel type C++ pour lequel les méthodes standard ` std::begin ` et ` std::end ` sont implémentées, et pour lequel le type d’itérateur renvoyé satisfait à std::forward_iterator. Certaines opérations du modèle seront plus performantes si ` std::size ` est disponible et si l’itérateur satisfait à std::random_access_iterator.

La plage doit être fournie lors de la construction du modèle et peut l’être par valeur, par wrapper de référence ou par pointeur. La manière dont le modèle a été construit détermine si les modifications apportées via l’API du modèle modifieront les données d’origine. Utilisez QRangeModelAdapter pour construire implicitement un modèle tout en bénéficiant d’un accès direct, sécurisé au niveau des types et pratique au modèle en tant que plage.

Lorsqu’il est construit par valeur, le modèle crée une copie de la plage, et les API d’ QAbstractItemModel qui modifient le modèle, telles que setData() ou insertRows(), n’ont aucun impact sur la plage d’origine.

QRangeModel model(numbers);

Les modifications apportées aux données peuvent être surveillées en se connectant aux signaux émis par le modèle, tels que dataChanged().

Pour que les modifications apportées au modèle affectent la plage d’origine, fournissez cette dernière soit par pointeur :

QRangeModel model(&numbers);

ou via un wrapper de référence :

QRangeModel model(std::ref(numbers));

Dans ce cas, les API QAbstractItemModel qui modifient le modèle modifient également la plage. Les méthodes qui modifient la structure de la plage, telles que insertRows() ou removeColumns(), utilisent les API de conteneurs C++ standard resize(), insert(), erase(), en plus de déréférencer un itérateur mutant pour définir ou effacer les données.

L’appelant doit s’assurer que la durée de vie de la plage dépasse celle du modèle.

Utilisez des pointeurs intelligents pour vous assurer que la plage ne soit supprimée que lorsque tous les clients en ont fini avec elle.

auto shared_numbers = std::make_shared<std::vector<int>>(numbers);
QRangeModel model(shared_numbers);

QRangeModel prend en charge à la fois les pointeurs partagés et les pointeurs uniques.

En lecture seule ou modifiable

Pour les plages qui sont des objets const, pour lesquelles l’accès renvoie toujours des valeurs constantes, ou lorsque les API de conteneur requises ne sont pas disponibles, QRangeModel implémente des API d’accès en écriture qui ne font rien et renvoient ` false`. Dans l’exemple utilisant ` std::array`, le modèle ne peut ni ajouter ni supprimer de lignes, car le nombre d’entrées dans un tableau C++ est fixe. Mais les valeurs peuvent être modifiées à l’aide de ` setData()` et l’utilisateur peut déclencher la modification des valeurs dans la vue de liste. En rendant le tableau `const`, les valeurs deviennent également en lecture seule.

const std::array<int, 5> numbers = {1, 2, 3, 4, 5};

Les valeurs sont également en lecture seule si le type de l’élément est de type const, comme dans

std::array<const int, 5> numbers = {1, 2, 3, 4, 5};

Dans les exemples ci-dessus utilisant ` std::vector`, le modèle peut ajouter ou supprimer des lignes, et les données peuvent être modifiées. Le fait de passer la plage en tant que référence constante rendra le modèle en lecture seule.

QRangeModel model(std::cref(numbers));

Lignes et colonnes

Les éléments de la plage sont interprétés comme des lignes du modèle. En fonction du type de ces éléments de ligne, QRangeModel expose la plage sous forme de liste, de tableau ou d’arborescence.

Si les éléments de ligne sont des valeurs simples, la plage est alors représentée sous forme de liste.

QList<int> numbers = {1, 2, 3, 4, 5};
QRangeModel model(numbers); // columnCount() == 1
QListView listView;
listView.setModel(&model);

Si le type des éléments de ligne est une plage itérable, telle qu’un vecteur, une liste ou un tableau, la plage est alors représentée sous forme de tableau.

std::vector<std::vector<int>> gridOfNumbers = {
    {1, 2, 3, 4, 5},
    {6, 7, 8, 9, 10},
    {11, 12, 13, 14, 15},
};
QRangeModel model(&gridOfNumbers); // columnCount() == 5
QTableView tableView;
tableView.setModel(&model);

Si le type de ligne fournit les API de conteneurs C++ standard resize(), insert(), erase(), alors les colonnes peuvent être ajoutées et supprimées via insertColumns() et removeColumns(). Toutes les lignes doivent comporter le même nombre de colonnes.

Structures et gadgets en tant que lignes

Si le type de ligne implémente the C++ tuple protocol, alors la plage est représentée sous la forme d’un tableau comportant un nombre fixe de colonnes.

using TableRow = std::tuple<int, QString>;
QList<TableRow> numberNames = {
    {1, "one"},
    {2, "two"},
    {3, "three"}
};
QRangeModel model(&numberNames); // columnCount() == 2
QTableView tableView;
tableView.setModel(&model);

Une alternative plus simple et plus flexible à l’implémentation du protocole `tuple` pour un type C++ consiste à utiliser le système de méta-objets de Qt pour déclarer un type doté de propriétés. Il peut s’agir d’un type de valeur déclaré comme ` gadget`, ou d’une sous-classe de ` QObject `.

class Book
{
    Q_GADGET
    Q_PROPERTY(QString title READ title)
    Q_PROPERTY(QString author READ author)
    Q_PROPERTY(QString summary MEMBER m_summary)
    Q_PROPERTY(int rating READ rating WRITE setRating)
public:
    Book(const QString &title, const QString &author);

    // C++ rule of 0: destructor, as well as copy/move operations
    // provided by the compiler.

    // read-only properties
    QString title() const { return m_title; }
    QString author() const { return m_author; }

    // read/writable property with input validation
    int rating() const { return m_rating; }
    void setRating(int rating)
    {
        m_rating = qBound(0, rating, 5);
    }

private:
    QString m_title;
    QString m_author;
    QString m_summary;
    int m_rating = 0;
};

L'utilisation de sous-classes de ` QObject ` permet de lier des propriétés ou de disposer de signaux de notification de modification. Cependant, l'utilisation d'instances de ` QObject ` pour les éléments entraîne une surcharge mémoire importante.

L'utilisation de gadgets ou d'objets Qt est plus pratique et peut s'avérer plus flexible que l'implémentation du protocole tuple. Ces types sont également directement accessibles depuis QML. Cependant, l'accès via le système de propriétés entraîne une certaine surcharge à l'exécution. Pour les modèles où les performances sont cruciales, envisagez d'implémenter le protocole tuple afin de générer le code d'accès lors de la compilation.

Éléments à rôles multiples

Le type des éléments sur lesquels portent les implémentations de ` data()`, ` setData()`, ` clearItemData()` etc. peut être le même dans l’ensemble du modèle — comme dans l’exemple « gridOfNumbers » ci-dessus. Mais la plage peut également comporter différents types d’éléments pour différentes colonnes, comme dans le cas « numberNames ».

Par défaut, la valeur est utilisée pour les rôles « Qt::DisplayRole » et « Qt::EditRole ». La plupart des vues s’attendent à ce que la valeur soit « convertible to and from a QString » (mais un délégué personnalisé peut offrir davantage de flexibilité).

Conteneurs associatifs à rôles multiples

Si l’élément est un conteneur associatif utilisant int, Qt::ItemDataRole ou QString comme type de clé, et QVariant comme type mappé, alors QRangeModel interprète ce conteneur comme le stockage des données pour plusieurs rôles. Les fonctions ` data()` et ` setData()` renvoient et modifient la valeur mappée dans le conteneur, tandis que ` setItemData()` modifie toutes les valeurs fournies, ` itemData()` renvoie toutes les valeurs stockées et ` clearItemData()` efface l’intégralité du conteneur.

using ColorEntry = QMap<Qt::ItemDataRole, QVariant>;

const QStringList colorNames = QColor::colorNames();
QList<ColorEntry> colors;
colors.reserve(colorNames.size());
for (const QString &name : colorNames) {
    const QColor color = QColor::fromString(name);
    colors << ColorEntry{{Qt::DisplayRole, name},
                        {Qt::DecorationRole, color},
                        {Qt::ToolTipRole, color.name()}};
}
QRangeModel colorModel(colors);
QListView list;
list.setModel(&colorModel);

Les types de données les plus efficaces à utiliser comme clé sont Qt::ItemDataRole ou int. Lorsque vous utilisez int, la fonction itemData() renvoie le conteneur tel quel et n’a pas besoin de créer une copie des données.

Gadgets et objets en tant qu’éléments à rôles multiples

Les gadgets et les types de QObject peuvent également être représentés en tant qu’éléments à rôles multiples. Les propriétés de ces éléments seront utilisées pour le rôle auquel correspond l’ name of a role. Si tous les éléments sont du même type de gadget ou de QObject, alors l’implémentation de roleNames() dans QRangeModel renverra la liste des propriétés de ce type.

class ColorEntry
{
    Q_GADGET
    Q_PROPERTY(QString display READ colorName)
    Q_PROPERTY(QColor decoration READ decoration)
    Q_PROPERTY(QString toolTip READ toolTip)
public:
    ColorEntry(const QString &color = {})
        : m_colorName(color)
    {}

    QString colorName() const
    {
        return m_colorName;
    }
    QColor decoration() const
    {
        return QColor::fromString(m_colorName);
    }
    QString toolTip() const
    {
        return QColor::fromString(m_colorName).name();
    }

private:
    QString m_colorName;
};

Lorsqu’ils sont utilisés dans un tableau, il s’agit de la représentation par défaut des gadgets :

QList<QList<ColorEntry>> colorTable;

// ...

QRangeModel colorModel(colorTable);
QTableView table;
table.setModel(&colorModel);

Lorsqu’ils sont utilisés dans une liste, ces types sont toutefois représentés par défaut sous forme de lignes à plusieurs colonnes, chaque propriété étant représentée par une colonne distincte. Pour forcer la représentation d’un gadget en tant qu’élément à rôles multiples dans une liste, déclarez le gadget comme un type à rôles multiples en spécialisant QRoleModel::RowOptions, avec une variable membre static constexpr auto rowCategory définie sur MultiRoleItem.

class ColorEntry
{
    Q_GADGET
    Q_PROPERTY(QString display READ colorName)
    Q_PROPERTY(QColor decoration READ decoration)
    Q_PROPERTY(QString toolTip READ toolTip)
public:
    ...
};
template <>
struct QRangeModel::RowOptions<ColorEntry>
{
    static constexpr auto rowCategory = QRangeModel::RowCategory::MultiRoleItem;
};

Vous pouvez également encapsuler ces types dans un tuple à un seul élément, transformant ainsi la liste en un tableau à une seule colonne :

const QStringList colorNames = QColor::colorNames();
QList<std::tuple<ColorEntry>> colors;

// ...

QRangeModel colorModel(colors);
QListView list;
list.setModel(&colorModel);

Dans ce cas, notez que l’accès direct aux éléments des données de la liste doit passer par std::get:

ColorEntry firstEntry = std::get<0>(colors.at(0));

ou bien une liaison structurée :

auto [firstEntry] = colors.at(0);

Lignes en tant que valeurs ou pointeurs

Dans les exemples présentés jusqu’à présent, nous avons toujours utilisé QRangeModel avec des plages contenant des valeurs. QRangeModel peut également opérer sur des plages contenant des pointeurs, y compris des pointeurs intelligents. Cela permet à QRangeModel d’opérer sur des plages de types polymorphes, telles que les sous-classes de QObject.

class Entry : public QObject
{
    Q_OBJECT
    Q_PROPERTY(QString display READ display WRITE setDisplay NOTIFY displayChanged)
    Q_PROPERTY(QIcon decoration READ decoration WRITE setDecoration NOTIFY decorationChanged)
    Q_PROPERTY(QString toolTip READ toolTip WRITE setToolTip NOTIFY toolTipChanged)

public:
    Entry() = default;

    QString display() const
    {
        return m_display;
    }

    void setDisplay(const QString &display)
    {
        if (m_display == display)
            return;
        m_display = display;
        emit displayChanged(m_display);
    }

signals:
    void displayChanged(const QString &);
    ...
};
std::vector<std::shared_ptr<Entry>> entries = {
    ...
};
QRangeModel model(std::ref(entries));
QListView listView;
listView.setModel(&model);

Comme pour les valeurs, le type de la ligne détermine si la plage est représentée sous forme de liste, de tableau ou d’arborescence. Les lignes qui sont des QObjects présenteront chaque propriété sous forme de colonne, à moins que le modèle QRangeModel::RowOptions ne soit spécialisé pour déclarer le type comme un élément à rôles multiples.

template <>
struct QRangeModel::RowOptions<Entry>
{
    static constexpr auto rowCategory = QRangeModel::RowCategory::MultiRoleItem;
};
std::vector<std::shared_ptr<Entry>> entries = {
    std::make_shared<Entry>(),
    ...
};

QRangeModel model(std::ref(entries));

Sous-classer QRangeModel

La sous-classification de QRangeModel permet d’ajouter des API pratiques qui prennent en compte le type de données et la structure de la plage.

class NumbersModel : public QRangeModel
{
    std::vector<int> m_numbers;

public:
    NumbersModel(const std::vector<int> &numbers)
        : QRangeModel(std::ref(m_numbers))
        , m_numbers(numbers)
    {
    }

Pour ce faire, ajoutez la plage en tant que membre privé, puis appelez le constructeur de QRangeModel avec un wrapper de référence ou un pointeur vers ce membre. Cela encapsule correctement les données et évite tout accès direct.

    void setNumber(int idx, int number)
    {
        setData(index(idx, 0), QVariant::fromValue(number));
    }

    int number(int idx) const
    {
        return m_numbers.at(idx);
    }
};

Ajoutez des fonctions membres pour fournir un accès sécurisé aux données, en utilisant l’API ` QAbstractItemModel ` pour effectuer toute opération modifiant la plage. L’accès en lecture seule peut opérer directement sur la structure de données.

Arbres de données

QRangeModel peut représenter une structure de données sous la forme d’un modèle arborescent. Une telle structure de données arborescente doit être homomorphe : à tous les niveaux de l’arborescence, la liste des lignes enfants doit utiliser exactement la même représentation que l’arborescence elle-même. De plus, le type de ligne doit être de taille statique : il peut s’agir soit d’un type « gadget » ou « QObject », soit d’un type implémentant l’interface the C++ tuple protocol.

Pour représenter ces données sous forme d’arbre, QRangeModel doit être capable de parcourir la structure de données : pour toute ligne donnée, le modèle doit pouvoir récupérer la ligne parente, ainsi que l’intervalle optionnel des lignes enfants. Ces fonctions de parcours peuvent être fournies implicitement via le type de ligne, ou via un type de protocole explicite.

Protocole implicite de traversée d’arbre

class TreeRow;

using Tree = std::vector<TreeRow>;

L’arbre lui-même est un vecteur de valeurs de type ` TreeRow `. Voir Tree Rows as pointers or values pour savoir s’il vaut mieux utiliser des valeurs ou des pointeurs vers des éléments pour les lignes.

class TreeRow
{
    Q_GADGET
    // properties

    TreeRow *m_parent;
    std::optional<Tree> m_children;

public:
    TreeRow() = default;

    // rule of 0: copy, move, and destructor implicitly defaulted

La classe de ligne peut être de n’importe quel type à taille fixe décrit ci-dessus : un type implémentant le protocole tuple, un gadget ou un ` QObject`. Dans cet exemple, nous utilisons un gadget.

Chaque élément de ligne doit conserver un pointeur vers la ligne parente, ainsi qu’une plage facultative de lignes enfants. Cette plage doit être identique à la structure de plage utilisée pour l’arbre lui-même.

Rendre le type de ligne constructible par défaut est facultatif et permet au modèle de construire de nouveaux éléments de données de ligne, par exemple dans les implémentations de ` insertRow()` ou ` moveRows()`.

    // tree traversal protocol implementation
    const TreeRow *parentRow() const { return m_parent; }
    const std::optional<Tree> &childRows() const { return m_children; }

Le protocole de traversée de l’arborescence peut alors être implémenté sous forme de fonctions membres du type de données « row ». Une fonction const parentRow() doit renvoyer un pointeur vers un élément de ligne ; et la fonction childRows() doit renvoyer une référence à un const std::optional pouvant contenir la plage optionnelle d’éléments enfants.

Ces deux fonctions suffisent pour que le modèle puisse parcourir l’arbre en tant que structure de données en lecture seule. Pour permettre à l’utilisateur de modifier les données d’une vue, et au modèle d’implémenter des API de modification telles que ` insertRows()`, ` removeRows()` et ` moveRows()`, nous devons implémenter des fonctions supplémentaires pour l’accès en écriture :

    void setParentRow(TreeRow *parent) { m_parent = parent; }
    std::optional<Tree> &childRows() { return m_children; }

Le modèle appelle la fonction setParentRow() et la surcharge mutable de childRows() pour déplacer ou insérer des lignes dans une branche existante de l’arborescence, et pour mettre à jour le pointeur parent si l’ancienne valeur est devenue invalide. La surcharge non-const de childRows() fournit en outre un accès en écriture aux données de la ligne.

    ...
    // Helper to assembly a tree of rows, not used by QRangeModel
    template <typename ...Args>
    TreeRow &addChild(Args &&...args)
    {
        if (!m_children)
            m_children.emplace(Tree{});
        auto &child = m_children->emplace_back(std::forward<Args>(args)...);
        child.m_parent = this;
        return child;
    }
};

Le reste de l’implémentation de la classe n’est pas pertinent pour le modèle, mais une fonction d’aide ` addChild() ` nous offre un moyen pratique de construire l’état initial de l’arborescence.

Tree tree = {
    {"..."},
    {"..."},
    {"..."},
};

// each toplevel row has three children
tree[0].addChild("...");
tree[0].addChild("...");
tree[0].addChild("...");

tree[1].addChild("...");
tree[1].addChild("...");
tree[1].addChild("...");

tree[2].addChild("...");
tree[2].addChild("...");
tree[2].addChild("...");

Un `QRangeModel` instancié avec une instance d’une telle plage représentera les données sous la forme d’un arbre.

// instantiate the model with a pointer to the tree, not a copy!
QRangeModel model(&tree);
QTreeView view;
view.setModel(&model);

Protocole de traversée d’arbre dans une classe distincte

Le protocole de parcours d’arbre peut également être implémenté dans une classe distincte.

struct TreeTraversal
{
    TreeRow newRow() const { return TreeRow{}; }
    const TreeRow *parentRow(const TreeRow &row) const { return row.m_parent; }
    void setParentRow(TreeRow &row, TreeRow *parent) const { row.m_parent = parent; }
    const std::optional<Tree> &childRows(const TreeRow &row) const { return row.m_children; }
    std::optional<Tree> &childRows(TreeRow &row) const { return row.m_children; }
};

Passez une instance de cette implémentation du protocole au constructeur de QRangeModel :

QRangeModel model(&tree, TreeTraversal{});

Lignes de l’arbre sous forme de pointeurs ou de valeurs

Le type des nœuds de la plage de données peut être soit une valeur, soit un pointeur. Dans le code ci-dessus, nous avons utilisé les nœuds de l’arborescence comme des valeurs dans un vecteur, ce qui évite d’avoir à gérer explicitement la mémoire. Cependant, un vecteur, en tant que bloc de mémoire contigu, invalide tous les itérateurs et toutes les références lorsqu’il doit réallouer de l’espace de stockage, ou lors de l’insertion ou de la suppression d’éléments. Cela affecte le pointeur vers l’élément parent, qui correspond à l’emplacement de la ligne parente au sein du vecteur. S'assurer que ce parent (et les instances d'QPersistentModelIndex s faisant référence aux éléments qu'il contient) reste valide peut entraîner une surcharge de performances considérable. L'implémentation de QRangeModel doit partir du principe que toutes les références au plage deviennent invalides lors de la modification de celle-ci.

Comme alternative, nous pouvons également utiliser une plage de pointeurs de ligne comme type d’arbre :

struct TreeRow;
using Tree = std::vector<TreeRow *>;

Dans ce cas, nous devons allouer explicitement toutes les instances de `TreeRow` à l'aide de l'opérateur ` new`, et implémenter le destructeur pour ` delete ` tous les éléments du vecteur des enfants.

struct TreeRow
{
    Q_GADGET
public:
    TreeRow(const QString&value = {})
        : m_value(value)
    {}
    ~TreeRow()
    {
        if (m_children)
            qDeleteAll(*m_children);
    }

    // déplacement uniquement
    TreeRow(TreeRow&&) = default;
    TreeRow&operator=(TreeRow&&) = default;

   // fonction d'aide au remplissage
    template <typename...Args>
    TreeRow *addChild(Args&&...args)
    {
        if (!m_children)
            m_children.emplace(Tree{});
       auto *child = m_children->emplace_back(new TreeRow(std::forward<Args>(args)...));
        child->m_parent = this;
        return child;
    }

private:
    friend struct TreeTraversal;
    QString m_value;
    std::optional<Tree> m_children;
    TreeRow *m_parent = nullptr;
};
Tree tree = {
    new TreeRow("1"),
    new TreeRow("2"),
    new TreeRow("3"),
    new TreeRow("4"),
};
tree[0]->addChild("1.1");
tree[1]->addChild("2.1");
tree[2]->addChild("3.1")->addChild("3.1.1");
tree[3]->addChild("4.1");

Avant de pouvoir construire un modèle représentant ces données sous forme d'arbre, nous devons également implémenter le protocole de traversée de l'arbre.

struct TreeTraversal
{
    TreeRow *newRow() const { return new TreeRow; }
    void deleteRow(TreeRow *row) { delete row; }

    const TreeRow *parentRow(const TreeRow &row) const { return row.m_parent; }
    void setParentRow(TreeRow &row, TreeRow *parent) { row.m_parent = parent; }
    const std::optional<Tree> &childRows(const TreeRow &row) const { return row.m_children; }
    std::optional<Tree> &childRows(TreeRow &row) { return row.m_children; }
};

Une implémentation explicite du protocole pour les arbres mutables de pointeurs doit fournir deux fonctions membres supplémentaires : ` newRow() ` et ` deleteRow(RowType *)`.

int main(int argc, char **argv)
{
    QApplication app(argc, argv);

    Tree tree = make_tree_of_pointers();

    QRangeModel model(std::move(tree), TreeTraversal{});
    QTreeView treeView;
    treeView.setModel(&model);
    treeView.show();

    return app.exec();
}

Le modèle appellera ces fonctions lors de la création de nouvelles lignes dans insertRows() et lors de la suppression de lignes dans removeRows(). De plus, si le modèle détient la propriété des données, il supprimera également toutes les lignes de niveau supérieur lors de sa destruction. Notez que dans cet exemple, nous déplaçons l’arborescence dans le modèle ; nous n’avons donc plus besoin d’effectuer d’opérations sur celle-ci. Le `QRangeModel`, lorsqu’il est construit en y déplaçant des données d’arborescence avec des pointeurs de ligne, prendra possession des données et supprimera les pointeurs de ligne dans son destructeur.

L’utilisation de pointeurs en tant que lignes entraîne une certaine surcharge liée à l’allocation et à la gestion de la mémoire. Cependant, les références aux éléments de ligne restent stables, même lorsqu’ils sont déplacés au sein de la plage ou lorsque celle-ci est réallouée. Cela peut réduire considérablement le coût des modifications apportées à la structure du modèle lors de l’utilisation de ` insertRows()`, ` removeRows()` ou ` moveRows()`.

Chaque choix présente des compromis différents entre performances et surcoût mémoire. La meilleure option dépend du cas d’utilisation précis et de la structure de données employée.

Personnalisation par spécialisation de modèles

QRangeModel déclare deux types de modèles imbriqués que vous pouvez spécialiser pour remplacer le comportement par défaut.

Le modèle ` RowOptions `, que nous avons déjà présenté plus haut, sert à personnaliser les fonctionnalités spécifiques au type de ligne, telles que les données d’en-tête, ou celles qui doivent s’appliquer de manière uniforme à tous les éléments d’une ligne, comme les indicateurs par défaut. Le modèle ` ItemAccess ` permet de personnaliser le comportement spécifique à un type d’élément, comme la lecture ou l’écriture des données de rôle.

Ces deux modèles doivent toujours être spécialisés pour le type sous-jacent ; ainsi, même si la plage contient des lignes de type Row en tant que std::unique_ptr<Row>, ou des éléments de type Item en tant que std::shared_ptr<Item>, la spécialisation doit porter sur Row et Item.

template <>
struct QRangeModel::ItemAccess<ColorEntry>
{
    ...
};
std::vector<std::shared_ptr<ColorEntry>> colors;
// ...
QRangeModel model(colors);

Indicateurs spécifiques aux lignes et aux éléments

L’implémentation par défaut de ` flags()` renvoie une combinaison des indicateurs ` Qt::ItemIsSelectable`, ` Qt::ItemIsEnabled` et — sauf pour les éléments situés dans la colonne 0 d’un modèle d’arborescence — ` Qt::ItemNeverHasChildren`. Les indicateurs ` Qt::ItemIsEditable ` et ` Qt::ItemIsDropEnabled ` sont activés pour tous les éléments des modèles qui ne sont pas en lecture seule, et ` Qt::ItemIsDragEnabled ` est activé tant que le modèle prend en charge au moins une ` mime type`.

Pour personnaliser le comportement par défaut de tous les éléments d’une ligne, spécialisez le modèle RowOptions. Pour accéder aux données des indicateurs par élément, spécialisez le modèle ItemAccess. Vous pouvez faire les deux : RowOptions permet de définir des indicateurs communs à tous les éléments d’une ligne, tandis que ItemAccess permet de définir des indicateurs pour les éléments basés sur un type spécifique.

Gestion du glisser-déposer

Depuis Qt 6.12, QRangeModel implémente la fonction virtuelle ` flags()` pour définir le drapeau ` Qt::ItemIsDragEnabled ` pour tous les éléments valides d’un modèle, à condition que ce dernier prenne en charge au moins un ` mime type`. Il s’agit du comportement par défaut, car ` QAbstractItemModel ` fournit le type MIME interne à Qt « application/x-qabstractitemmodeldatalist ». De plus, l’indicateur « Qt::ItemIsDropEnabled » est activé pour les éléments d’un tel modèle, à condition que ce dernier ne soit pas en lecture seule. Cela inclut l’élément inexistant à l’index invalide, ce qui permet aux utilisateurs de déposer des données dans des zones vides d’une vue afin de les ajouter à la fin.

La prise en charge de types MIME supplémentaires peut être mise en œuvre sans créer de sous-classe de QRangeModel ni redéfinir les fonctions virtuelles correspondantes. QRangeModel détectera et utilisera les fonctions des modèles de personnalisation ItemAccess et RowOptions pour encoder les lignes ou les éléments en mime data, et pour les decode mime data en séquences de lignes ou d’éléments. Ces fonctions de personnalisation peuvent opérer directement sur les types de lignes et d’éléments, sans passer par QModelIndex et QVariant.

De cette manière, le code de sérialisation des données peut être sûr du point de vue des types et peut rester associé à l’implémentation du type utilisé pour stocker les données.

De plus, ` supportedDragActions ` et ` supportedDropActions ` sont des propriétés pouvant être configurées pour chaque instance de `QRangeModel`.

Sujets avancés en C++

Le protocole de tuples en C++

Comme le montre l’exemple numberNames ci-dessus, le type de ligne peut être un tuple, et en fait n’importe quel type implémentant le protocole de tuple. Ce protocole est implémenté en spécialisant std::tuple_size et std::tuple_element, et en surchargeant la fonction non qualifiée get. Procédez ainsi pour votre type de ligne personnalisé afin de rendre les données structurées existantes accessibles au framework modèle/vue de Qt.

struct Book
{
    QString title;
    QString author;
    QString summary;
    int rating = 0;

    template <size_t I, typename T>
        requires ((I <= 3) && std::is_same_v<std::remove_cvref_t<T>, Book>)
    friend inline decltype(auto) get(T &&book)
    {
        if constexpr (I == 0)
            return std::as_const(book.title);
        else if constexpr (I == 1)
            return std::as_const(book.author);
        else if constexpr (I == 2)
            return std::forward_like<T>(book.summary);
        else if constexpr (I == 3)
            return std::forward_like<T>(book.rating);
    }
};

namespace std {
    template <> struct tuple_size<Book> : std::integral_constant<size_t, 4> {};
    template <size_t I> struct tuple_element<I, Book>
    { using type = decltype(get<I>(std::declval<Book>())); };
}

Dans l’implémentation ci-dessus, les valeurs « title » et « author » du type « Book » sont renvoyées sous la forme « const », de sorte que le modèle marque les éléments de ces deux colonnes comme étant en lecture seule. L’utilisateur ne pourra pas déclencher d’édition, et la fonction « setData() » ne fait rien et renvoie « false ». Pour ` summary ` et ` rating `, l’implémentation renvoie la même valeur de catégorie que le livre ; ainsi, lorsque ` get ` est appelé avec une référence modifiable vers un ` Book`, il renvoie une référence modifiable de la variable correspondante. Le modèle rend ces colonnes modifiables, tant pour l’utilisateur que pour l’accès programmatique.

Considérations relatives à la compatibilité binaire

QRangeModel n'est pas une classe de modèle. Le passage d'instances de QRangeModel (par pointeur ou par référence, comme pour toutes les classes de la bibliothèque « QObject ») via les API de la bibliothèque, ou le stockage de QRangeModel par valeur dans une classe publique d'une bibliothèque, ne présente aucun risque.

Cependant, le constructeur de QRangeModel est un modèle et est inline, et l’implémentation interne, spécialisée en fonction du type de la plage sur laquelle le modèle opère, est instanciée dans le constructeur. Vous ne devez pas appeler le constructeur dans une implémentation inline d’une API de bibliothèque. Cela entraîne des violations de l’ODR et pourrait rompre la compatibilité binaire de cette bibliothèque si la version de Qt utilisée pour sa compilation diffère de celle utilisée pour la compilation d’une application utilisant cette bibliothèque.

Les nouvelles implémentations optimisées des fonctions virtuelles introduites dans les versions ultérieures de Qt pourraient également ne pas être utilisées si QRangeModel détecte que l’implémentation a été compilée avec une version plus ancienne de Qt. Par exemple, les implémentations de ` sort()` et ` match()` sont nouvelles dans Qt 6.12, mais ne seront pas appelées par une application compilée avec Qt 6.11, même si la bibliothèque Qt utilisée est Qt 6.12. Pour bénéficier de ces nouvelles redéfinitions, recompilez votre application.