QRangeModel Class

Descripción detallada

QRangeModel puede hacer que los datos de cualquier tipo C++ secuencialmente iterable estén disponibles para el framework modelo/vista de Qt. Esto facilita la visualización de estructuras de datos existentes en las vistas de elementos Qt Widgets y Qt Quick, y permite al usuario de la aplicación manipular los datos utilizando una interfaz gráfica de usuario.

Para utilizar QRangeModel, hay que instanciarlo con un rango C++ y establecerlo como modelo de una o más vistas:

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

Construcción del modelo

El rango puede ser cualquier tipo C++ para el que estén implementados los métodos estándar std::begin y std::end, y para el que el tipo de iterador devuelto satisfaga std::forward_iterator. Algunas operaciones del modelo funcionarán mejor si std::size está disponible y si el iterador cumple std::random_access_iterator.

El rango debe proporcionarse al construir el modelo y puede proporcionarse por valor, envoltura de referencia o puntero. La forma en que se construyó el modelo define si los cambios a través de la API del modelo modificarán los datos originales. Utilice QRangeModelAdapter para construir implícitamente un modelo y disponer al mismo tiempo de un acceso directo, seguro y cómodo al modelo como rango.

Cuando se construye por valor, el modelo hace una copia del rango, y las API de QAbstractItemModel que modifican el modelo, como setData() o insertRows(), no afectan al rango original.

QRangeModel model(numbers);

Los cambios realizados en los datos pueden controlarse conectándose a las señales emitidas por el modelo, como dataChanged().

Para que las modificaciones del modelo afecten al rango original, proporcione el rango bien mediante un puntero

QRangeModel model(&numbers);

o a través de una envoltura de referencia:

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

En este caso, las API de QAbstractItemModel que modifican el modelo también modifican el rango. Los métodos que modifican la estructura del rango, como insertRows() o removeColumns(), utilizan las API contenedoras estándar de C++ resize(), insert(), erase(), además de desreferenciar un iterador mutante para establecer o borrar los datos.

El invocador debe asegurarse de que el tiempo de vida del rango excede el tiempo de vida del modelo.

Utilice punteros inteligentes para asegurarse de que el rango sólo se elimina cuando todos los clientes han terminado con él.

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

QRangeModel admite tanto punteros compartidos como punteros únicos.

Sólo lectura o mutable

Para rangos que son objetos const, para los que el acceso siempre produce valores constantes, o donde las APIs contenedoras requeridas no están disponibles, QRangeModel implementa APIs de acceso de escritura para no hacer nada y devolver false. En el ejemplo que utiliza std::array, el modelo no puede añadir ni eliminar filas, ya que el número de entradas de una matriz C++ es fijo. Pero los valores pueden cambiarse utilizando setData(), y el usuario puede activar la edición de los valores en la vista de lista. Al hacer el array const, los valores también pasan a ser de sólo lectura.

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

Los valores también son de sólo lectura si el tipo de elemento es const, como en

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

En los ejemplos anteriores utilizando std::vector, el modelo puede añadir o eliminar filas, y los datos pueden ser modificados. Si se pasa el rango como una referencia constante, el modelo será de sólo lectura.

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

Filas y columnas

Los elementos del rango se interpretan como filas del modelo. Dependiendo del tipo de estos elementos de fila, QRangeModel expone el rango como una lista, una tabla o un árbol.

Si los elementos de la fila son valores simples, el rango se representa como una lista.

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

Si el tipo de los elementos de fila es un rango iterable, como un vector, una lista o una matriz, el rango se representa como una tabla.

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 el tipo de fila proporciona las API contenedoras estándar de C++ resize(), insert(), erase(), entonces se pueden añadir y eliminar columnas a través de insertColumns() y removeColumns(). Todas las filas deben tener el mismo número de columnas.

Estructuras y gadgets como filas

Si el tipo de fila implementa the C++ tuple protocol, entonces el rango se representa como una tabla con un número fijo de columnas.

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

Una alternativa más sencilla y flexible a la implementación del protocolo de tuplas para un tipo C++ es utilizar el sistema de metaobjetos de Qt para declarar un tipo con propiedades. Este puede ser un tipo de valor que se declara como gadget, o una subclase 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;
};

El uso de subclases de QObject permite que las propiedades sean vinculables, o que tengan señales de notificación de cambios. Sin embargo, el uso de instancias de QObject para los elementos tiene una sobrecarga de memoria significativa.

Utilizar gadgets u objetos Qt es más cómodo y puede ser más flexible que implementar el protocolo de tuplas. Estos tipos también son directamente accesibles desde QML. Sin embargo, el acceso a través del sistema de propiedades conlleva cierta sobrecarga en tiempo de ejecución. En el caso de los modelos de rendimiento crítico, se recomienda implementar el protocolo de tupla para generar el código de acceso en tiempo de compilación.

Elementos polivalentes

El tipo de los elementos sobre los que operan las implementaciones de data(), setData(), clearItemData(), etc. puede ser el mismo en todo el modelo, como en el ejemplo anterior de gridOfNumbers. Pero el rango también puede tener diferentes tipos de elementos para diferentes columnas, como en el caso de numberNames.

Por defecto, el valor se utiliza para los roles Qt::DisplayRole y Qt::EditRole. La mayoría de las vistas esperan que el valor sea convertible to and from a QString (pero un delegado personalizado puede proporcionar más flexibilidad).

Contenedores asociativos con varios roles

Si el elemento es un contenedor asociativo que utiliza int, Qt::ItemDataRole, o QString como tipo clave, y QVariant como tipo mapeado, entonces QRangeModel interpreta ese contenedor como el almacenamiento de los datos para múltiples roles. Las funciones data() y setData() devuelven y modifican el valor mapeado en el contenedor, y setItemData() modifica todos los valores proporcionados, itemData() devuelve todos los valores almacenados, y clearItemData() borra todo el contenedor.

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

El tipo de datos más eficiente para utilizar como clave es Qt::ItemDataRole o int. Cuando se utiliza int, itemData() devuelve el contenedor tal cual, y no tiene que crear una copia de los datos.

Gadgets y objetos como elementos con múltiples funciones

Los gadgets y los tipos QObject también pueden representarse como elementos multi-función. Las propiedades de estos elementos se utilizarán para el rol con el que coincida name of a role. Si todos los elementos contienen el mismo tipo de gadget o QObject, la implementación de roleNames() en QRangeModel devolverá la lista de propiedades de ese tipo.

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

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

private:
    QString m_colorName;
};

Cuando se utiliza en una tabla, ésta es la representación por defecto para los gadgets:

QList<QList<ColorEntry>> colorTable;

// ...

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

Sin embargo, cuando se utilizan en una lista, estos tipos se representan por defecto como filas de varias columnas, con cada propiedad representada como una columna independiente. Para forzar que un gadget se represente como un elemento multirol en una lista, declare el gadget como un tipo multirol especializando QRoleModel::RowOptions, con una variable miembro static constexpr auto rowCategory establecida en MultiRoleItem.

class ColorEntry
{
    Q_GADGET
    Q_PROPERTY(QString display MEMBER m_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;
};

También puede envolver estos tipos en una tupla de un solo elemento, convirtiendo la lista en una tabla con una sola columna:

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

// ...

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

En este caso, tenga en cuenta que para acceder directamente a los elementos de los datos de la lista es necesario utilizar std::get:

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

o alternativamente un enlace estructurado:

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

Filas como valores o punteros

En los ejemplos anteriores, siempre hemos utilizado QRangeModel con rangos que contienen valores. QRangeModel también puede operar con rangos que contengan punteros, incluidos los punteros inteligentes. Esto permite a QRangeModel operar con rangos de tipos polimorfos, como las subclases 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);

Al igual que con los valores, el tipo de la fila define si el rango se representa como una lista, tabla o árbol. Las filas que son QObjects presentarán cada propiedad como una columna, a menos que la plantilla QRangeModel::RowOptions esté especializada para declarar el tipo como un elemento polimorfo.

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

Subclase de QRangeModel

Subclasificar QRangeModel permite añadir APIs prácticas que tienen en cuenta el tipo de datos y la estructura del rango.

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

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

Al hacerlo, añada el rango como un miembro privado y llame al constructor de QRangeModel con una envoltura de referencia o un puntero a ese miembro. Esto encapsula adecuadamente los datos y evita el acceso directo.

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

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

Añada funciones miembro para proporcionar un acceso seguro a los datos, utilizando la API QAbstractItemModel para realizar cualquier operación que modifique el rango. El acceso de sólo lectura puede operar directamente sobre la estructura de datos.

Árboles de datos

QRangeModel puede representar una estructura de datos como un modelo de árbol. Una estructura de datos en forma de árbol debe ser homomórfica: en todos los niveles del árbol, la lista de filas secundarias debe utilizar exactamente la misma representación que el propio árbol. Además, el tipo de fila debe tener un tamaño estático: un tipo gadget o QObject, o un tipo que implemente the C++ tuple protocol.

Para representar estos datos como un árbol, QRangeModel tiene que ser capaz de recorrer la estructura de datos: para cualquier fila dada, el modelo tiene que ser capaz de recuperar la fila padre, y el tramo opcional de los hijos. Estas funciones transversales pueden proporcionarse implícitamente a través del tipo de fila, o a través de un tipo de protocolo explícito.

Protocolo implícito de recorrido del árbol

class TreeRow;

using Tree = std::vector<TreeRow>;

El árbol en sí es un vector de valores TreeRow. Véase Tree Rows as pointers or values para las consideraciones sobre si utilizar valores o punteros de elementos para las filas.

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 clase de fila puede ser de cualquier tipo de tamaño fijo descrito anteriormente: un tipo que implemente el protocolo de tupla, un gadget o un QObject. En este ejemplo, utilizamos un gadget.

Cada elemento de fila necesita mantener un puntero a la fila padre, así como un rango opcional de filas hijas. Ese rango debe ser idéntico a la estructura de rangos utilizada para el propio árbol.

Hacer que el tipo de fila por defecto sea construible es opcional, y permite al modelo construir nuevos elementos de datos de fila, por ejemplo en las implementaciones insertRow() o moveRows().

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

El protocolo de recorrido del árbol puede entonces implementarse como funciones miembro del tipo de datos fila. Una función const parentRow() tiene que devolver un puntero a un elemento de fila; y la función childRows() tiene que devolver una referencia a una const std::optional que pueda contener el rango hijo opcional.

Estas dos funciones son suficientes para que el modelo navegue por el árbol como una estructura de datos de sólo lectura. Para permitir al usuario editar datos en una vista, y al modelo implementar APIs de modelo mutante como insertRows(), removeRows(), y moveRows(), tenemos que implementar funciones adicionales para el acceso de escritura:

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

El modelo llama a la función setParentRow() y a la sobrecarga mutable childRows() para mover o insertar filas en una rama de árbol existente, y para actualizar el puntero padre en caso de que el valor antiguo haya dejado de ser válido. La sobrecarga no-const de childRows() proporciona además acceso de escritura a los datos de la fila.

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

El resto de la implementación de la clase no es relevante para el modelo, pero un ayudante de addChild() nos proporciona una forma conveniente de construir el estado inicial del árbol.

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 instanciado con una instancia de dicho rango representará los datos como un árbol.

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

Protocolo de recorrido del árbol en una clase separada

El protocolo de recorrido del árbol también puede implementarse en una clase independiente.

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

Pase una instancia de esta implementación de protocolo al constructor de QRangeModel:

QRangeModel model(&tree, TreeTraversal{});

Filas de árbol como punteros o valores

El tipo de fila del rango de datos puede ser un valor o un puntero. En el código anterior hemos estado utilizando las filas del árbol como valores en un vector, lo que evita que tengamos que ocuparnos de la gestión explícita de la memoria. Sin embargo, un vector como bloque contiguo de memoria invalida todos los iteradores y referencias cuando tiene que reasignar el almacenamiento, o cuando inserta o elimina elementos. Esto afecta al puntero al elemento padre, que es la ubicación de la fila padre dentro del vector. Asegurarse de que este elemento padre (y las instancias de QPersistentModelIndex que hacen referencia a elementos dentro de él) sigue siendo válido puede incurrir en una considerable sobrecarga de rendimiento. La implementación de QRangeModel tiene que asumir que todas las referencias al rango se vuelven inválidas cuando se modifica el rango.

Alternativamente, también podemos utilizar un rango de punteros de fila como tipo de árbol:

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

En este caso, tenemos que asignar todas las instancias TreeRow explícitamente utilizando el operador new, e implementar el destructor para delete todos los elementos del vector de hijos.

struct TreeRow { Q_GADGETpublic: TreeRow(const QString &valor = {}) : m_valor(valor) {} ~TreeRow() { if (m_hijos)            qDeleteAll(*m_children);
    ¡} // move-onlyTreeRow(TreeRow &&) = default; TreeRow &operator=(TreeRow &&) = default; // helper to populate 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");

Antes de que podamos construir un modelo que represente estos datos como un árbol, necesitamos implementar también el protocolo de recorrido del árbol.

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

Una implementación explícita del protocolo para árboles mutables de punteros tiene que proporcionar dos funciones miembro adicionales, newRow() y 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();
}

El modelo llamará a esas funciones cuando cree nuevas filas en insertRows(), y cuando elimine filas en removeRows(). Además, si el modelo es propietario de los datos, también borrará todas las filas de nivel superior al destruirlas. Observa cómo en este ejemplo, movemos el árbol dentro del modelo, por lo que ya no debemos realizar ninguna operación sobre él. QRangeModel, cuando se construye moviendo datos de árbol con punteros de fila en él, tomará la propiedad de los datos, y eliminará los punteros de fila en su destructor.

El uso de punteros como filas conlleva cierta sobrecarga en la asignación y gestión de memoria. Sin embargo, las referencias a los elementos de la fila permanecen estables, incluso cuando se mueven en el rango, o cuando el rango se reasigna. Esto puede reducir significativamente el coste de realizar modificaciones en la estructura del modelo cuando se utiliza insertRows(), removeRows(), o moveRows().

Cada opción tiene diferentes compensaciones de rendimiento y sobrecarga de memoria. La mejor opción depende del caso de uso exacto y de la estructura de datos utilizada.

El protocolo de tuplas de C

Como se ha visto en el ejemplo anterior de numberNames, el tipo de fila puede ser una tupla y, de hecho, cualquier tipo que implemente el protocolo de tuplas. Este protocolo se implementa especializando std::tuple_size y std::tuple_element, y sobrecargando la función no cualificada get. Hazlo para tu tipo de fila personalizado para que los datos estructurados existentes estén disponibles para el marco modelo/vista en 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>())); };
}

En la implementación anterior, los valores title y author del tipo Book se devuelven como const, por lo que el modelo marca los elementos de esas dos columnas como de sólo lectura. El usuario no podrá activar la edición, y setData() no hace nada y devuelve false. Para summary y rating la implementación devuelve la misma categoría de valor que el libro, por lo que cuando se llama a get con una referencia mutable a una Book, entonces devolverá una referencia mutable de la variable respectiva. El modelo hace que esas columnas sean editables, tanto para el usuario como para el acceso programático.

Consideraciones sobre compatibilidad binaria

QRangeModel no es una clase de plantilla. Pasar instancias de QRangeModel (por puntero o referencia, como con todas las clases QObject ) a través de APIs de bibliotecas, o almacenar QRangeModel por valor en una clase pública de una biblioteca, es seguro.

Sin embargo, el constructor de QRangeModel es una plantilla e inline, y la implementación interna especializada en el tipo de rango sobre el que opera el modelo se instancia en el constructor. No debería llamar al constructor en una implementación en línea de una API de biblioteca. Da lugar a violaciones de ODR, y podría romper la compatibilidad binaria de esa biblioteca si la versión de Qt con la que se construye es diferente de la versión de Qt con la que se construye una aplicación que utiliza esa biblioteca.