QRangeModel Class

Ausführliche Beschreibung

QRangeModel kann die Daten eines beliebigen sequenziell durchlaufbaren C++-Typs für das Modell-View-Framework von Qt verfügbar machen. Dies erleichtert die Darstellung bestehender Datenstrukturen in den Elementansichten „ Qt Widgets “ und „ Qt Quick “ und ermöglicht es dem Benutzer der Anwendung, die Daten über eine grafische Benutzeroberfläche zu bearbeiten.

Um QRangeModel zu verwenden, instanziieren Sie es mit einem C++-Bereich und legen Sie es als Modell für eine oder mehrere Ansichten fest:

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

Erstellen des Modells

Der Bereich kann ein beliebiger C++-Typ sein, für den die Standardmethoden ` std::begin ` und ` std::end ` implementiert sind und bei dem der zurückgegebene Iterator-Typ die Anforderung ` std::forward_iterator` erfüllt. Bestimmte Modelloperationen erzielen eine bessere Leistung, wenn ` std::size ` verfügbar ist und der Iterator die Anforderung ` std::random_access_iterator` erfüllt.

Der Bereich muss beim Erstellen des Modells angegeben werden und kann als Wert, Referenz-Wrapper oder Zeiger übergeben werden. Die Art und Weise, wie das Modell erstellt wurde, bestimmt, ob Änderungen über die Modell-API die Originaldaten modifizieren. Verwenden Sie QRangeModelAdapter, um implizit ein Modell zu erstellen und gleichzeitig direkten, typsicheren und bequemen Zugriff auf das Modell als Bereich zu erhalten.

Bei der Erstellung nach Wert erstellt das Modell eine Kopie des Bereichs, und APIs von „ QAbstractItemModel “, die das Modell ändern, wie z. B. ` setData()` oder ` insertRows()`, haben keine Auswirkungen auf den ursprünglichen Bereich.

QRangeModel model(numbers);

Änderungen an den Daten können durch Anbindung an die vom Modell ausgegebenen Signale, wie z. B. ` dataChanged()`, überwacht werden.

Damit sich Änderungen am Modell auf den ursprünglichen Bereich auswirken, übergeben Sie den Bereich entweder über einen Zeiger:

QRangeModel model(&numbers);

oder über einen Referenz-Wrapper:

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

In diesem Fall ändern QAbstractItemModel -APIs, die das Modell modifizieren, auch den Bereich. Methoden, die die Struktur des Bereichs verändern, wie z. B. insertRows() oder removeColumns(), verwenden Standard-C++-Container-APIs resize(), insert(), erase() und dereferenzieren zusätzlich einen mutierenden Iterator, um die Daten zu setzen oder zu löschen.

Der Aufrufer muss sicherstellen, dass die Lebensdauer des Bereichs die Lebensdauer des Modells übersteigt.

Verwenden Sie Smart-Pointer, um sicherzustellen, dass der Bereich erst gelöscht wird, wenn alle Clients ihn nicht mehr benötigen.

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

QRangeModel unterstützt sowohl gemeinsam genutzte als auch eindeutige Zeiger.

Schreibgeschützt oder veränderbart

Für Bereiche, die „const“-Objekte sind, bei denen der Zugriff stets konstante Werte liefert oder bei denen die erforderlichen Container-APIs nicht verfügbar sind, implementiert QRangeModel Schreibzugriffs-APIs, die keine Aktion ausführen und „ false “ zurückgeben. Im Beispiel mit „ std::array “ kann das Modell keine Zeilen hinzufügen oder entfernen, da die Anzahl der Einträge in einem C++-Array feststeht. Die Werte können jedoch mit ` setData()` geändert werden, und der Benutzer kann die Bearbeitung der Werte in der Listenansicht auslösen. Indem das Array als `const` deklariert wird, werden die Werte ebenfalls schreibgeschützt.

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

Die Werte sind ebenfalls schreibgeschützt, wenn der Elementtyp `const` ist, wie in

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

In den obigen Beispielen mit ` std::vector` kann das Modell Zeilen hinzufügen oder entfernen, und die Daten können geändert werden. Wird der Bereich als konstante Referenz übergeben, wird das Modell schreibgeschützt.

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

Zeilen und Spalten

Die Elemente im Bereich werden als Zeilen des Modells interpretiert. Je nach Typ dieser Zeilenelemente stellt QRangeModel den Bereich als Liste, Tabelle oder Baumstruktur dar.

Sind die Zeilenelemente einfache Werte, wird der Bereich als Liste dargestellt.

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

Ist der Typ der Zeilenelemente ein iterierbarer Bereich, wie beispielsweise ein Vektor, eine Liste oder ein Array, wird der Bereich als Tabelle dargestellt.

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);

Wenn der Zeilentyp die Standard-C++-Container-APIs „ resize() “, „ insert() “ und „ erase() “ bereitstellt, können Spalten über „ insertColumns()“ und „ removeColumns()“ hinzugefügt und entfernt werden. Alle Zeilen müssen die gleiche Anzahl an Spalten aufweisen.

Strukturen und Gadgets als Zeilen

Wenn der Zeilentyp ` the C++ tuple protocol` implementiert, wird der Bereich als Tabelle mit einer festen Anzahl von Spalten dargestellt.

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);

Eine einfachere und flexiblere Alternative zur Implementierung des Tupel-Protokolls für einen C++-Typ ist die Verwendung des Metaobjekt-Systems von Qt, um einen Typ mit Eigenschaften zu deklarieren. Dabei kann es sich um einen Werttyp handeln, der als ` gadget` deklariert ist, oder um eine Unterklasse von ` 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;
};

Durch die Verwendung von Unterklassen von ` QObject ` können Eigenschaften gebunden werden oder über Signale zur Benachrichtigung bei Änderungen verfügen. Die Verwendung von ` QObject `-Instanzen für Elemente ist jedoch mit einem erheblichen Speicher-Overhead verbunden.

Die Verwendung von Qt-Gadgets oder -Objekten ist praktischer und kann flexibler sein als die Implementierung des Tuple-Protokolls. Auf diese Typen kann auch direkt aus QML heraus zugegriffen werden. Der Zugriff über das Eigenschaftssystem ist jedoch mit einem gewissen Laufzeitaufwand verbunden. Bei leistungskritischen Modellen sollte die Implementierung des Tuple-Protokolls zur Generierung des Zugriffscodes zur Kompilierungszeit in Betracht gezogen werden.

Elemente mit mehreren Rollen

Der Typ der Elemente, auf die die Implementierungen von ` data()`, ` setData()`, ` clearItemData()` usw. angewendet werden, kann im gesamten Modell einheitlich sein – wie im obigen Beispiel „ gridOfNumbers “. Der Bereich kann jedoch auch unterschiedliche Elementtypen für verschiedene Spalten enthalten, wie im Fall „ numberNames “.

Standardmäßig wird der Wert für die Rollen „ Qt::DisplayRole “ und „ Qt::EditRole “ verwendet. Die meisten Ansichten erwarten, dass der Wert „ convertible to and from a QString “ ist (ein benutzerdefinierter Delegat könnte jedoch mehr Flexibilität bieten).

Assoziative Container mit mehreren Rollen

Wenn es sich bei dem Element um einen assoziativen Container handelt, der „ int “, „ Qt::ItemDataRole “ oder „ QString “ als Schlüsseltyp und „ QVariant “ als zugeordneten Typ verwendet, interpretiert QRangeModel diesen Container als Speicher für die Daten mehrerer Rollen. Die Funktionen „ data()“ und „ setData()“ geben den zugeordneten Wert im Container zurück bzw. ändern ihn, „ setItemData()“ ändert alle angegebenen Werte, „ itemData()“ gibt alle gespeicherten Werte zurück und „ clearItemData()“ löscht den gesamten Container.

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);

Der effizienteste Datentyp, der als Schlüssel verwendet werden kann, ist „ Qt::ItemDataRole “ oder „ int “. Bei Verwendung von „ int “ gibt „ itemData “() den Container unverändert zurück und muss keine Kopie der Daten erstellen.

Gadgets und Objekte als Elemente mit mehreren Rollen

Gadgets und „ QObject “-Typen können ebenfalls als Elemente mit mehreren Rollen dargestellt werden. Die Eigenschaften dieser Elemente werden für die Rolle verwendet, auf die die „ name of a role “ zutrifft. Wenn alle Elemente denselben Gadget- oder „ QObject “-Typ aufweisen, gibt die Implementierung von „ roleNames()“ in „QRangeModel“ die Liste der Eigenschaften dieses Typs zurück.

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;
};

Bei Verwendung in einer Tabelle ist dies die Standarddarstellung für Gadgets:

QList<QList<ColorEntry>> colorTable;

// ...

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

Bei der Verwendung in einer Liste werden diese Typen jedoch standardmäßig als mehrspaltige Zeilen dargestellt, wobei jede Eigenschaft als separate Spalte dargestellt wird. Um zu erzwingen, dass ein Gadget in einer Liste als Element mit mehreren Rollen dargestellt wird, deklarieren Sie das Gadget als Typ mit mehreren Rollen, indem Sie `QRoleModel::RowOptions` spezialisieren und die Membervariable ` static constexpr auto rowCategory ` auf ` MultiRoleItem` setzen.

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;
};

Sie können solche Typen auch in ein Tupel mit einem Element verpacken, wodurch die Liste in eine Tabelle mit einer einzigen Spalte umgewandelt wird:

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

// ...

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

Beachten Sie in diesem Fall, dass für den direkten Zugriff auf die Elemente in den Listendaten „ std::get “ verwendet werden muss:

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

oder alternativ eine strukturierte Bindung:

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

Zeilen als Werte oder Zeiger

In den bisherigen Beispielen haben wir QRangeModel stets mit Bereichen verwendet, die Werte enthalten. QRangeModel kann auch mit Bereichen arbeiten, die Zeiger enthalten, einschließlich Smart-Zeiger. Dadurch kann QRangeModel mit Bereichen polymorpher Typen arbeiten, wie beispielsweise Unterklassen von ` 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);

Wie bei Werten bestimmt der Typ der Zeile, ob der Bereich als Liste, Tabelle oder Baum dargestellt wird. Zeilen, die QObjects sind, stellen jede Eigenschaft als Spalte dar, es sei denn, die Vorlage „ QRangeModel::RowOptions “ ist so spezialisiert, dass der Typ als Element mit mehreren Rollen deklariert wird.

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));

Unterklassen von QRangeModel

Durch die Unterklassifizierung von `QRangeModel` lassen sich praktische APIs hinzufügen, die den Datentyp und die Struktur des Bereichs berücksichtigen.

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

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

Fügen Sie dabei den Bereich als privates Mitglied hinzu und rufen Sie den QRangeModel-Konstruktor mit einem Referenz-Wrapper oder einem Zeiger auf dieses Mitglied auf. Dadurch werden die Daten ordnungsgemäß gekapselt und ein direkter Zugriff vermieden.

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

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

Fügen Sie Mitgliedsfunktionen hinzu, um einen typsicheren Zugriff auf die Daten zu ermöglichen, und verwenden Sie die API „ QAbstractItemModel “, um alle Operationen durchzuführen, die den Bereich verändern. Bei schreibgeschütztem Zugriff kann direkt auf die Datenstruktur zugegriffen werden.

Datenstrukturen in Baumform

QRangeModel kann eine Datenstruktur als Baummodell darstellen. Eine solche Baumdatenstruktur muss homomorph sein: Auf allen Ebenen des Baums muss die Liste der untergeordneten Zeilen genau dieselbe Darstellung verwenden wie der Baum selbst. Zudem muss der Zeilentyp eine statische Größe haben: entweder ein „Gadget“- oder „ QObject “-Typ oder ein Typ, der ` the C++ tuple protocol` implementiert.

Um solche Daten als Baum darzustellen, muss QRangeModel in der Lage sein, die Datenstruktur zu durchlaufen: Für jede beliebige Zeile muss das Modell die übergeordnete Zeile sowie den optionalen Bereich der untergeordneten Zeilen abrufen können. Diese Durchlauffunktionen können implizit über den Zeilentyp oder über einen expliziten Protokolltyp bereitgestellt werden.

Implizites Protokoll zur Baumdurchquerung

class TreeRow;

using Tree = std::vector<TreeRow>;

Der Baum selbst ist ein Vektor aus „ TreeRow “-Werten. Siehe „ Tree Rows as pointers or values “ für Überlegungen dazu, ob für die Zeilen Werte oder Zeiger auf Elemente verwendet werden sollten.

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

Die Zeilenklasse kann ein beliebiger der oben beschriebenen Typen mit fester Größe sein: ein Typ, der das Tupel-Protokoll implementiert, ein Gadget oder ein ` QObject`. In diesem Beispiel verwenden wir ein Gadget.

Jedes Zeilenelement muss einen Zeiger auf die übergeordnete Zeile sowie optional einen Bereich von untergeordneten Zeilen enthalten. Dieser Bereich muss mit der für den Baum selbst verwendeten Bereichsstruktur identisch sein.

Es ist optional, den Zeilentyp standardmäßig konstruierbar zu machen; dies ermöglicht es dem Modell, neue Zeilendatenelemente zu konstruieren, beispielsweise in den Implementierungen von ` insertRow()` oder ` moveRows()`.

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

Das Baumdurchlaufprotokoll kann dann als Member-Funktionen des Zeilendatentyps implementiert werden. Eine ` parentRow() `-Funktion vom Typ `const` muss einen Zeiger auf ein Zeilenelement zurückgeben; und die ` childRows() `-Funktion muss eine Referenz auf ein `const`-` std::optional ` zurückgeben, das den optionalen Bereich der untergeordneten Zeilen enthalten kann.

Diese beiden Funktionen reichen aus, damit das Modell den Baum als schreibgeschützte Datenstruktur durchlaufen kann. Damit der Benutzer Daten in einer Ansicht bearbeiten kann und das Modell mutierende Modell-APIs wie ` insertRows()`, ` removeRows()` und ` moveRows()` implementieren kann, müssen wir zusätzliche Funktionen für den Schreibzugriff implementieren:

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

Das Modell ruft die Funktion ` setParentRow() ` und die überladene, veränderbare Version von ` childRows() ` auf, um Zeilen in einen bestehenden Baumzweig zu verschieben oder einzufügen und den Elternzeiger zu aktualisieren, falls der alte Wert ungültig geworden ist. Die nicht-konstante Überladung von ` childRows() ` bietet zusätzlich Schreibzugriff auf die Zeilendaten.

    ...
    // 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;
    }
};

Der Rest der Klassenimplementierung ist für das Modell nicht relevant, aber ein Hilfsfunktion „ addChild() “ bietet uns eine bequeme Möglichkeit, den Anfangszustand des Baums zu konstruieren.

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("...");

Ein QRangeModel, das mit einer Instanz eines solchen Bereichs instanziiert wird, stellt die Daten als Baum dar.

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

Baumdurchlaufprotokoll in einer separaten Klasse

Das Baumdurchlaufprotokoll kann auch in einer separaten Klasse implementiert werden.

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; }
};

Übergeben Sie eine Instanz dieser Protokollimplementierung an den QRangeModel-Konstruktor:

QRangeModel model(&tree, TreeTraversal{});

Baumzeilen als Zeiger oder Werte

Der Zeilentyp des Datenbereichs kann entweder ein Wert oder ein Zeiger sein. Im obigen Code haben wir die Baumzeilen als Werte in einem Vektor verwendet, wodurch wir uns nicht um die explizite Speicherverwaltung kümmern müssen. Ein Vektor als zusammenhängender Speicherblock macht jedoch alle Iteratoren und Referenzen ungültig, wenn Speicher neu zugewiesen werden muss oder wenn Elemente eingefügt oder entfernt werden. Dies wirkt sich auf den Zeiger auf das übergeordnete Element aus, der die Position der übergeordneten Zeile innerhalb des Vektors angibt. Sicherzustellen, dass dieses übergeordnete Element (und die „ QPersistentModelIndex “-Instanzen, die auf Elemente darin verweisen) gültig bleibt, kann einen erheblichen Leistungsaufwand verursachen. Die QRangeModel-Implementierung muss davon ausgehen, dass alle Verweise auf den Bereich bei einer Änderung des Bereichs ungültig werden.

Alternativ können wir auch einen Bereich von Zeilenzeigern als Baumtyp verwenden:

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

In diesem Fall müssen wir alle `TreeRow`-Instanzen explizit mit dem Operator ` new` zuweisen und den Destruktor so implementieren, dass alle Elemente im Vektor der untergeordneten Knoten mit ` delete ` freigegeben werden.

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

    // Nur Verschieben
    TreeRow(TreeRow&&) = default;
    TreeRow&operator=(TreeRow&&) = default;

   // Hilfsfunktion zum Befüllen
    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");

Bevor wir ein Modell erstellen können, das diese Daten als Baum darstellt, müssen wir auch das Protokoll zur Baumdurchquerung implementieren.

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; }
};

Eine explizite Protokollimplementierung für veränderbare Bäume aus Zeigern muss zwei zusätzliche Member-Funktionen bereitstellen: ` newRow() ` und ` 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();
}

Das Modell ruft diese Funktionen auf, wenn neue Zeilen in ` insertRows()` angelegt und Zeilen in ` removeRows()` entfernt werden. Wenn das Modell zudem die Eigentumsrechte an den Daten besitzt, löscht es bei seiner Zerstörung außerdem alle Zeilen der obersten Ebene. Beachten Sie, dass wir in diesem Beispiel den Baum in das Modell verschieben, sodass wir keine Operationen mehr daran durchführen müssen. Wenn ein `QRangeModel` durch das Verschieben von Baumdaten mit Zeilenzeigern darin erstellt wird, übernimmt es die Eigentumsrechte an den Daten und löscht die Zeilenzeiger in seinem Destruktor.

Die Verwendung von Zeigern als Zeilen ist mit einem gewissen Aufwand bei der Speicherzuweisung und -verwaltung verbunden. Die Verweise auf die Zeilenelemente bleiben jedoch stabil, selbst wenn sie innerhalb des Bereichs verschoben werden oder wenn der Bereich neu zugewiesen wird. Dies kann den Aufwand für Änderungen an der Struktur des Modells bei Verwendung von ` insertRows()`, ` removeRows()` oder ` moveRows()` erheblich reduzieren.

Jede Option bringt unterschiedliche Kompromisse hinsichtlich Leistung und Speicherbedarf mit sich. Die beste Option hängt vom jeweiligen Anwendungsfall und der verwendeten Datenstruktur ab.

Anpassung durch Vorlagenspezialisierung

QRangeModel deklariert zwei verschachtelte Vorlagentypen, die Sie spezialisieren können, um das Standardverhalten zu überschreiben.

Die oben bereits vorgestellte Vorlage „ RowOptions “ dient zur Anpassung von Funktionen, die spezifisch für den Zeilentyp sind, wie z. B. Kopfdaten, oder die einheitlich für alle Elemente in einer Zeile gelten sollen, wie z. B. Standardkennzeichen. Die Vorlage „ ItemAccess “ ermöglicht die Anpassung von elementtypspezifischem Verhalten, wie z. B. das Lesen oder Schreiben von Rollendaten.

Diese beiden Vorlagen müssen immer für den zugrunde liegenden Typ spezialisiert werden. Selbst wenn der Bereich also Zeilen vom Typ „ Row “ als „ std::unique_ptr<Row> “ oder Elemente vom Typ „ Item “ als „ std::shared_ptr<Item> “ enthält, muss die Spezialisierung für „ Row “ und „ Item “ erfolgen.

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

Zeilen- und elementspezifische Flags

Die Standardimplementierung von ` flags()` gibt eine Kombination aus ` Qt::ItemIsSelectable`, ` Qt::ItemIsEnabled` und – mit Ausnahme von Elementen in Spalte 0 eines Baummodells – ` Qt::ItemNeverHasChildren` zurück. Die Flags ` Qt::ItemIsEditable ` und ` Qt::ItemIsDropEnabled ` sind für alle Elemente in Modellen gesetzt, die nicht schreibgeschützt sind, und ` Qt::ItemIsDragEnabled ` ist gesetzt, solange das Modell mindestens ein ` mime type` unterstützt.

Um das Standardverhalten für alle Elemente in einer Zeile anzupassen, verwenden Sie die Vorlage „ RowOptions “. Um auf die Flag-Daten der einzelnen Elemente zuzugreifen, verwenden Sie die Vorlage „ ItemAccess “. Sie können beides tun: Mit „ RowOptions “ können Sie Flags setzen, die für alle Elemente in einer Zeile gelten, und mit „ ItemAccess “ können Sie Flags für Elemente setzen, die auf einem bestimmten Typ basieren.

Drag-and-Drop-Verarbeitung

Seit Qt 6.12 implementiert `QRangeModel` die virtuelle Funktion ` flags()` zum Setzen des Flags ` Qt::ItemIsDragEnabled ` für alle gültigen Elemente in einem Modell, sofern das Modell mindestens ein ` mime type` unterstützt. Dies ist die Standardeinstellung, da ` QAbstractItemModel ` den Qt-internen MIME-Typ „application/x-qabstractitemmodeldatalist“ bereitstellt. Zudem wird das Flag „ Qt::ItemIsDropEnabled “ für Elemente in einem solchen Modell gesetzt, sofern dieses Modell nicht schreibgeschützt ist. Dies schließt auch das nicht vorhandene Element am ungültigen Index ein, sodass Benutzer Daten in leere Bereiche einer Ansicht ziehen können, um die Daten anzuhängen.

Die Unterstützung für weitere MIME-Typen lässt sich implementieren, ohne QRangeModel zu unterklassen und die entsprechenden virtuellen Funktionen zu überschreiben. QRangeModel erkennt und nutzt Funktionen in den Anpassungsvorlagen „ ItemAccess “ und „ RowOptions “, um Zeilen oder Elemente als „ mime data “ zu kodieren und sie in „ decode mime data “ in Sequenzen von Zeilen oder Elementen umzuwandeln. Diese Anpassungsfunktionen können direkt auf die Zeilen- und Elementtypen angewendet werden, ohne Umwege über „ QModelIndex “ und „ QVariant “ zu nehmen.

Auf diese Weise kann der Code zur Serialisierung von Daten typsicher sein und bei der Implementierung des Typs verbleiben, der zur Speicherung der Daten verwendet wird.

Darüber hinaus sind supportedDragActions und supportedDropActions Eigenschaften, die für jede QRangeModel-Instanz konfiguriert werden können.

Fortgeschrittene C++-Themen

Das C++-Tupel-Protokoll

Wie im obigen Beispiel „ numberNames “ zu sehen ist, kann der Zeilentyp ein Tupel sein – und tatsächlich jeder Typ, der das Tupel-Protokoll implementiert. Dieses Protokoll wird durch die Spezialisierung von ` std::tuple_size ` und ` std::tuple_element` sowie durch die Überladung der nicht qualifizierten Funktion ` get ` implementiert. Führen Sie dies für Ihren benutzerdefinierten Zeilentyp durch, um vorhandene strukturierte Daten dem Modell-View-Framework in Qt zur Verfügung zu stellen.

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>())); };
}

In der obigen Implementierung werden die Werte „ title “ und „ author “ des Typs „ Book “ als „ const “ zurückgegeben, sodass das Modell die Elemente in diesen beiden Spalten als schreibgeschützt markiert. Der Benutzer kann keine Bearbeitung auslösen, und „ setData()“ führt keine Aktion aus und gibt „false“ zurück. Für „ summary “ und „ rating “ gibt die Implementierung dieselbe Wertkategorie wie das Buch zurück. Wenn also „ get “ mit einer veränderbaren Referenz auf „ Book “ aufgerufen wird, gibt die Funktion eine veränderbare Referenz auf die jeweilige Variable zurück. Das Modell macht diese Spalten sowohl für den Benutzer als auch für den programmatischen Zugriff bearbeitbar.

Überlegungen zur Binärkompatibilität

QRangeModel ist keine Template-Klasse. Die Übergabe von QRangeModel-Instanzen (per Zeiger oder Referenz, wie bei allen QObject -Klassen) über Bibliotheks-APIs oder die Speicherung von QRangeModel per Wert in einer öffentlichen Klasse einer Bibliothek ist unbedenklich.

Der QRangeModel-Konstruktor ist jedoch ein Template und inline, und die interne Implementierung, die auf den Typ des Bereichs spezialisiert ist, auf dem das Modell operiert, wird im Konstruktor instanziiert. Sie sollten den Konstruktor nicht in einer inline-Implementierung einer Bibliotheks-API aufrufen. Dies führt zu ODR-Verstößen und kann die Binärkompatibilität dieser Bibliothek beeinträchtigen, wenn die Qt-Version, gegen die sie kompiliert wurde, sich von der Qt-Version unterscheidet, gegen die eine Anwendung, die diese Bibliothek nutzt, kompiliert wurde.

Neue und optimierte Implementierungen virtueller Funktionen, die in späteren Versionen von Qt eingeführt wurden, werden möglicherweise ebenfalls nicht verwendet, wenn QRangeModel feststellt, dass die Implementierung mit einer älteren Qt-Version kompiliert wurde. Beispielsweise sind die Implementierungen von ` sort()` und ` match()` neu in Qt 6.12, werden jedoch von einer Anwendung, die mit Qt 6.11 kompiliert wurde, nicht aufgerufen, selbst wenn die verwendete Qt-Bibliothek Qt 6.12 ist. Um von solchen neuen Überschreibungen zu profitieren, kompilieren Sie Ihre Anwendung neu.