QRangeModel Class
QRangeModel implementa la interfaz « QAbstractItemModel » para cualquier rango de C++. Más información...
| Cabecera: | #include <QRangeModel> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
| Desde: | Qt 6.10 |
| Heredado de: | QAbstractItemModel |
Nota: Todas las funciones de esta clase son reentrantes.
Tipos públicos
(since 6.11) struct | ItemAccess |
(since 6.10) struct | RowOptions |
(since 6.11) enum class | AutoConnectPolicy { None, Full, OnRead } |
(since 6.12) enum class | DropOperation { DontDrop, Automatic, OverwriteAndIgnore, OverwriteAndExtend, InsertAsSiblings, InsertAsChildren } |
| enum class | RowCategory { Default, MultiRoleItem } |
Propiedades
|
|
Funciones públicas
| QRangeModel(Range &&range, QObject *parent = nullptr) | |
| QRangeModel(Range &&range, Protocol &&protocol, QObject *parent = nullptr) | |
| virtual | ~QRangeModel() override |
| QRangeModel::AutoConnectPolicy | autoConnectPolicy() const |
| void | resetRoleNames() |
| void | resetSortCollator() |
| void | resetSortRole() |
| void | resetSupportedDragActions() |
| void | resetSupportedDropActions() |
| void | setAutoConnectPolicy(QRangeModel::AutoConnectPolicy policy) |
| void | setRoleNames(const QHash<int, QByteArray> &names) |
| void | setSortCollator(const QCollator &collator) |
| void | setSortRole(int role) |
| void | setSupportedDragActions(Qt::DropActions actions) |
| void | setSupportedDropActions(Qt::DropActions actions) |
| QCollator | sortCollator() const |
| int | sortRole() const |
Funciones públicas reimplementadas
| virtual QModelIndex | buddy(const QModelIndex &index) const override |
| virtual bool | canDropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent) const override |
| virtual bool | canFetchMore(const QModelIndex &parent) const override |
| virtual bool | clearItemData(const QModelIndex &index) override |
| virtual int | columnCount(const QModelIndex &parent = {}) const override |
| virtual QVariant | data(const QModelIndex &index, int role = Qt::DisplayRole) const override |
| virtual bool | dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent) override |
| virtual void | fetchMore(const QModelIndex &parent) override |
| virtual Qt::ItemFlags | flags(const QModelIndex &index) const override |
| virtual bool | hasChildren(const QModelIndex &parent = QModelIndex()) const override |
| virtual QVariant | headerData(int section, Qt::Orientation orientation, int role = Qt::DisplayRole) const override |
| virtual QModelIndex | index(int row, int column, const QModelIndex &parent = {}) const override |
| virtual bool | insertColumns(int column, int count, const QModelIndex &parent = {}) override |
| virtual bool | insertRows(int row, int count, const QModelIndex &parent = {}) override |
| virtual QMap<int, QVariant> | itemData(const QModelIndex &index) const override |
| virtual QModelIndexList | match(const QModelIndex &start, int role, const QVariant &value, int hits, Qt::MatchFlags flags) const override |
| virtual QMimeData * | mimeData(const QModelIndexList &indexes) const override |
| virtual QStringList | mimeTypes() const override |
| virtual bool | moveColumns(const QModelIndex &sourceParent, int sourceColumn, int count, const QModelIndex &destinationParent, int destinationColumn) override |
| virtual bool | moveRows(const QModelIndex &sourceParent, int sourceRow, int count, const QModelIndex &destinationParent, int destinationRow) override |
| virtual void | multiData(const QModelIndex &index, QModelRoleDataSpan roleDataSpan) const override |
| virtual QModelIndex | parent(const QModelIndex &child) const override |
| virtual bool | removeColumns(int column, int count, const QModelIndex &parent = {}) override |
| virtual bool | removeRows(int row, int count, const QModelIndex &parent = {}) override |
| virtual QHash<int, QByteArray> | roleNames() const override |
| virtual int | rowCount(const QModelIndex &parent = {}) const override |
| virtual bool | setData(const QModelIndex &index, const QVariant &data, int role = Qt::EditRole) override |
| virtual bool | setHeaderData(int section, Qt::Orientation orientation, const QVariant &data, int role = Qt::EditRole) override |
| virtual bool | setItemData(const QModelIndex &index, const QMap<int, QVariant> &data) override |
| virtual QModelIndex | sibling(int row, int column, const QModelIndex &index) const override |
| virtual void | sort(int column, Qt::SortOrder order = Qt::AscendingOrder) override |
| virtual QSize | span(const QModelIndex &index) const override |
| virtual Qt::DropActions | supportedDragActions() const override |
| virtual Qt::DropActions | supportedDropActions() const override |
Señales
| void | autoConnectPolicyChanged(QRangeModel::AutoConnectPolicy policy) |
| void | roleNamesChanged() |
| void | sortCollatorChanged(const QCollator &collator) |
| void | sortRoleChanged(int role) |
| void | supportedDragActionsChanged(Qt::DropActions actions) |
| void | supportedDropActionsChanged(Qt::DropActions actions) |
Funciones protegidas reimplementadas
| virtual bool | event(QEvent *event) override |
| virtual bool | eventFilter(QObject *object, QEvent *event) override |
Ranuras protegidas
| virtual void | resetInternalData() override |
Descripción detallada
QRangeModel permite que los datos de cualquier tipo de C++ iterable secuencialmente estén disponibles para el marco de trabajo de modelos y vistas 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 mediante una interfaz gráfica de usuario.
Para utilizar QRangeModel, hay que instanciarlo con un rango de 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);Creación del modelo
El rango puede ser cualquier tipo de C++ para el que se hayan implementado los métodos estándar std::begin y std::end, y para el que el tipo de iterador devuelto cumpla con std::forward_iterator. Ciertas operaciones del modelo funcionarán mejor si se dispone de std::size y si el iterador cumple con std::random_access_iterator.
El rango debe proporcionarse al construir el modelo y puede proporcionarse por valor, mediante un envoltorio de referencia o mediante un puntero. La forma en que se ha construido el modelo determina si los cambios realizados a través de la API del modelo modificarán los datos originales. Utilice QRangeModelAdapter para construir implícitamente un modelo y, al mismo tiempo, disponer de un acceso directo, seguro en cuanto al tipo y cómodo al modelo como rango.
Cuando se construye por valor, el modelo realiza 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 supervisarse conectándose a las señales emitidas por el modelo, como dataChanged().
Para que las modificaciones del modelo afecten al rango original, hay que proporcionar el rango mediante un puntero:
QRangeModel model(&numbers);o mediante un envoltorio 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 estándar de contenedores de C++ resize(), insert(), erase(), además de desreferenciar un iterador mutante para establecer o borrar los datos.
Nota: Una vez que el modelo se ha construido y se ha pasado a una vista, el rango sobre el que opera el modelo ya no debe modificarse directamente. Las vistas del modelo no recibirían información sobre los cambios, y es probable que los cambios estructurales corrompan las instancias de QPersistentModelIndex que mantiene el modelo. Utiliza QRangeModelAdapter para interactuar de forma segura con el rango subyacente mientras se mantiene el modelo actualizado.
El llamante debe asegurarse de que la vida útil del rango supere la del modelo.
Utiliza punteros inteligentes para garantizar que el rango solo se elimine cuando todos los clientes hayan terminado de utilizarlo.
auto shared_numbers = std::make_shared<std::vector<int>>(numbers);
QRangeModel model(shared_numbers);QRangeModel admite tanto punteros compartidos como únicos.
Solo lectura o mutable
Para los rangos que son objetos const, en los que el acceso siempre devuelve valores constantes, o cuando no están disponibles las API de contenedor necesarias, QRangeModel implementa API de acceso de escritura que no realizan ninguna acción y devuelven un false. En el ejemplo en el que se utiliza ` std::array`, el modelo no puede añadir ni eliminar filas, ya que el número de entradas en un array de C++ es fijo. Sin embargo, los valores se pueden modificar mediante setData(), y el usuario puede activar la edición de los valores en la vista de lista. Al definir la matriz como const, los valores también pasan a ser de solo lectura.
const std::array<int, 5> numbers = {1, 2, 3, 4, 5};Los valores también son de solo lectura si el tipo del elemento es const, como en
std::array<const int, 5> numbers = {1, 2, 3, 4, 5};En los ejemplos anteriores que utilizan std::vector, el modelo puede añadir o eliminar filas, y los datos se pueden modificar. Al pasar el rango como una referencia constante, el modelo pasará a ser de solo lectura.
QRangeModel model(std::cref(numbers));Nota: Si los valores del rango son «const», tampoco es posible eliminar o insertar columnas y filas a través de la API « QAbstractItemModel ». Para un control más detallado, implementa « the C++ tuple protocol ».
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 las filas 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 las filas 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 estándar de contenedores de C++ resize(), insert(), erase(), entonces se pueden añadir y eliminar columnas mediante 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, 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 «tuple» para un tipo de C++ es utilizar el sistema de metaobjetos de Qt para declarar un tipo con propiedades. Puede tratarse de un tipo de valor declarado como « gadget » o de 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 cuenten con señales de notificación de cambios. Sin embargo, el uso de instancias de ` QObject ` para los elementos conlleva una sobrecarga de memoria significativa.
El uso de gadgets u objetos de Qt resulta más cómodo y puede ofrecer mayor flexibilidad que la implementación del protocolo de tuplas. Además, se puede acceder directamente a estos tipos desde QML. No obstante, el acceso a través del sistema de propiedades conlleva cierta sobrecarga en tiempo de ejecución. Para modelos en los que el rendimiento sea fundamental, se recomienda implementar el protocolo de tuplas para la generación del código de acceso en tiempo de compilación.
Elementos con múltiples roles
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 las funciones de « Qt::DisplayRole » y « Qt::EditRole ». La mayoría de las vistas esperan que el valor sea « convertible to and from a QString » (aunque un delegado personalizado podría ofrecer mayor flexibilidad).
Contenedores asociativos con múltiples roles
Si el elemento es un contenedor asociativo que utiliza int, Qt::ItemDataRole o QString como tipo de 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 asignado en el contenedor; 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. Al utilizar int, itemData() devuelve el contenedor tal cual, sin necesidad de crear una copia de los datos.
Gadgets y objetos como elementos con múltiples roles
Los gadgets y los tipos QObject también pueden representarse como elementos multifuncionales. Las propiedades de dichos elementos se utilizarán para la función con la que coincida el name of a role. Si todos los elementos son del 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 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;
};Cuando se utiliza en una tabla, esta 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, en las que cada propiedad se representa como una columna independiente. Para forzar que un gadget se represente como un elemento de varias funciones en una lista, declara el gadget como un tipo de varias funciones especializando QRoleModel::RowOptions, con una variable miembro static constexpr auto rowCategory establecida en 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;
};También puedes agrupar dichos tipos en una tupla de un solo elemento, convirtiendo la lista en una tabla de una sola columna:
const QStringList colorNames = QColor::colorNames();
QList<std::tuple<ColorEntry>> colors;
// ...
QRangeModel colorModel(colors);
QListView list;
list.setModel(&colorModel);En este caso, ten en cuenta que el acceso directo a los elementos de los datos de la lista debe realizarse mediante ` 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 contienen punteros, incluidos los punteros inteligentes. Esto permite que `QRangeModel` opere con rangos de tipos polimórficos, 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 determina si el rango se representa como una lista, una tabla o un árbol. Las filas que son QObjects presentarán cada propiedad como una columna, a menos que la plantilla QRangeModel::RowOptions se especialice para declarar el tipo como un elemento de roles múltiples.
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));Nota: Si el rango contiene punteros sin tipo, hay que construir un QRangeModel a partir de un puntero o de un envoltorio de referencia del rango. De lo contrario, la propiedad de los datos se vuelve ambigua, y una copia del rango seguiría operando sobre los mismos datos reales de la fila, lo que provocaría efectos secundarios inesperados.
Subclasificación de QRangeModel
La subclasificación de QRangeModel permite añadir interfaces de programación de aplicaciones (API) prácticas que tengan 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)
{
}Para ello, añade el rango como miembro privado y llama al constructor de QRangeModel con un envoltorio de referencia o un puntero a dicho miembro. De este modo, se encapsulan correctamente los datos y se 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ñade funciones de miembro para proporcionar un acceso seguro en cuanto al tipo a los datos, utilizando la API ` QAbstractItemModel ` para realizar cualquier operación que modifique el rango. El acceso de solo lectura puede operar directamente sobre la estructura de datos.
Árboles de datos
QRangeModel puede representar una estructura de datos como un modelo de árbol. Dicha estructura de datos en forma de árbol debe ser homomórfica: en todos los niveles del árbol, la lista de filas hijas debe utilizar exactamente la misma representación que el propio árbol. Además, el tipo de fila debe ser de tamaño estático: bien un tipo «gadget» o « QObject », bien un tipo que implemente ` the C++ tuple protocol`.
Para representar dichos datos como un árbol, QRangeModel debe poder recorrer la estructura de datos: para cualquier fila dada, el modelo debe poder recuperar la fila padre y el intervalo opcional de hijos. Estas funciones de recorrido pueden proporcionarse de forma implícita a través del tipo de fila, o mediante un tipo de protocolo explícito.
Protocolo implícito de recorrido del árbol
class TreeRow;
using Tree = std::vector<TreeRow>;El árbol en sí mismo es un vector de valores de tipo « TreeRow ». Consulte Tree Rows as pointers or values para conocer las consideraciones sobre si se deben utilizar valores o punteros a 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 defaultedLa clase de fila puede ser de cualquier tipo de tamaño fijo descrito anteriormente: un tipo que implemente el protocolo «tuple», un «gadget» o un « QObject ». En este ejemplo, utilizamos un «gadget».
Cada elemento de la fila debe mantener un puntero a la fila principal, así como un rango opcional de filas secundarias. Ese rango debe ser idéntico a la estructura de rango utilizada para el propio árbol.
Hacer que el tipo de fila sea construible por defecto es opcional y permite al modelo construir nuevos elementos de datos de fila, por ejemplo, en las implementaciones de ` 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 implementarse entonces como funciones miembro del tipo de datos de fila. Una función const parentRow() debe devolver un puntero a un elemento de fila; y la función childRows() debe devolver una referencia a un const std::optional que pueda contener el rango opcional de hijos.
Estas dos funciones son suficientes para que el modelo navegue por el árbol como una estructura de datos de solo lectura. Para permitir que el usuario edite datos en una vista y que el modelo implemente API de modelo mutables como insertRows(), removeRows() y moveRows(), debemos 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 de childRows() para mover o insertar filas en una rama existente del árbol, y para actualizar el puntero padre en caso de que el valor anterior haya dejado de ser válido. La sobrecarga no const de childRows() proporciona, además, acceso de escritura a los datos de la fila.
Nota: El modelo lleva a cabo, en pasos separados, la asignación del padre de una fila, la eliminación de dicha fila del padre anterior y su adición a la lista de hijos del nuevo padre. Esto permite que la interfaz del protocolo sea concisa.
...
// 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 una función auxiliar ` addChild() ` nos proporciona una forma cómoda 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 de árbol en una clase independiente
El protocolo de recorrido del árbol también se puede implementar en una clase separada.
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; }
};Pasa una instancia de esta implementación del protocolo al constructor de QRangeModel:
QRangeModel model(&tree, TreeTraversal{});Filas del á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, al ser un bloque contiguo de memoria, invalida todos los iteradores y referencias cuando tiene que reasignar el almacenamiento, o al insertar o eliminar elementos. Esto afecta al puntero al elemento padre, que es la ubicación de la fila padre dentro del vector. Asegurarse de que este padre (y l QPersistentModelIndex es instancias que hacen referencia a elementos dentro de él) siga siendo válido puede suponer una sobrecarga de rendimiento considerable. La implementación de QRangeModel tiene que asumir que todas las referencias al rango dejan de ser válidas al modificarlo.
Como alternativa, también podemos utilizar un rango de punteros a filas como tipo de árbol:
struct TreeRow;
using Tree = std::vector<TreeRow *>;En este caso, tenemos que asignar todas las instancias de `TreeRow` de forma explícita mediante el operador ` new`, e implementar el destructor para ` delete ` todos los elementos del vector de hijos.
struct TreeRow
{
Q_GADGET
public:
TreeRow(const QString&value = {})
: m_value(value)
{}
~TreeRow()
{
if (m_children)
qDeleteAll(*m_children);
}
// solo movimiento
TreeRow(TreeRow&&) = default;
TreeRow&operator=(TreeRow&&) = default;
// función auxiliar para rellenar
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 poder construir un modelo que represente estos datos como un árbol, también debemos implementar 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 debe 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 al crear nuevas filas en ` insertRows()` y al eliminar filas en ` removeRows()`. Además, si el modelo tiene la propiedad de los datos, también eliminará todas las filas de nivel superior al destruirse. Fíjate en cómo, en este ejemplo, trasladamos el árbol al modelo, por lo que ya no tenemos que realizar ninguna operación sobre él. QRangeModel, cuando se construye trasladando datos del árbol con punteros a las filas al modelo, asumirá la propiedad de los datos y eliminará los punteros a las filas en su destructor.
El uso de punteros como filas conlleva cierta sobrecarga en la asignación y gestión de la memoria. Sin embargo, las referencias a los elementos de las filas permanecen estables, incluso cuando se mueven dentro del rango o cuando este se reasigna. Esto puede reducir significativamente el coste de realizar modificaciones en la estructura del modelo al utilizar insertRows(), removeRows() o moveRows().
Cada opción presenta diferentes compensaciones entre rendimiento y consumo de memoria. La mejor opción depende del caso de uso concreto y de la estructura de datos empleada.
Personalización mediante la especialización de plantillas
QRangeModel declara dos tipos de plantillas anidadas que se pueden especializar para anular el comportamiento predeterminado.
La plantilla « RowOptions », que ya hemos presentado anteriormente, sirve para personalizar funcionalidades específicas del tipo de fila, como los datos de cabecera, o que deben aplicarse de manera uniforme a todos los elementos de una fila, como los indicadores por defecto. La plantilla « ItemAccess » permite personalizar el comportamiento específico de cada tipo de elemento, como la lectura o la escritura de datos de rol.
Estas dos plantillas siempre deben especializarse para el tipo subyacente, por lo que, aunque el rango contenga filas de tipo ` Row ` como ` std::unique_ptr<Row>`, o elementos de tipo ` Item ` como ` std::shared_ptr<Item>`, la especialización debe realizarse para ` Row ` y ` Item`.
template <>
struct QRangeModel::ItemAccess<ColorEntry>
{
...
};
std::vector<std::shared_ptr<ColorEntry>> colors;
// ...
QRangeModel model(colors);Nota: En C++ solo debes especializar plantillas para tipos de los que seas propietario, y no para tipos estándar o de Qt. Crea subclases o agregados para los tipos que no controles si necesitas personalizar el comportamiento de dichos tipos. Ten en cuenta que un alias de tipo no es un tipo distinto, y no debes especializar plantillas para tipos alias. Sin embargo, está permitido crear una especialización de un contenedor estándar o de Qt con un tipo del que seas propietario, como por ejemplo un ` std::vector<MyGadget>`.
Indicadores específicos de fila y elemento
La implementación por defecto de ` flags()` devuelve una combinación de ` Qt::ItemIsSelectable`, ` Qt::ItemIsEnabled` y —excepto para los elementos de la columna 0 de un modelo de árbol— ` Qt::ItemNeverHasChildren`. Los indicadores ` Qt::ItemIsEditable ` y ` Qt::ItemIsDropEnabled ` se establecen para todos los elementos de los modelos que no sean de solo lectura, y ` Qt::ItemIsDragEnabled ` se establece siempre que el modelo admita al menos un ` mime type`.
Para personalizar el comportamiento predeterminado de todos los elementos de una fila, especializa la plantilla RowOptions. Para acceder a los datos de los indicadores de cada elemento, especializa la plantilla ItemAccess. Puedes hacer ambas cosas: RowOptions permite establecer indicadores comunes para todos los elementos de una fila, y ItemAccess permite establecer indicadores para elementos basados en un tipo específico.
Gestión de «arrastrar y soltar»
Desde Qt 6.12, QRangeModel implementa la función virtual ` flags()` para establecer el indicador ` Qt::ItemIsDragEnabled ` para todos los elementos válidos de un modelo, siempre que el modelo admita al menos un ` mime type`. Este es el comportamiento por defecto, ya que ` QAbstractItemModel ` proporciona el tipo MIME interno de Qt «application/x-qabstractitemmodeldatalist». Además, se establece el indicador Qt::ItemIsDropEnabled para los elementos de dicho modelo, siempre que este no sea de solo lectura. Esto incluye el elemento inexistente en el índice no válido, de modo que los usuarios pueden soltar datos en áreas vacías de una vista para añadirlos.
La implementación de la compatibilidad con tipos MIME adicionales puede realizarse sin necesidad de crear subclases de `QRangeModel` ni de sobrescribir las funciones virtuales correspondientes. QRangeModel detectará y utilizará las funciones de las plantillas de personalización ItemAccess y RowOptions para codificar filas o elementos como mime data, y para decode mime data en secuencias de filas o elementos. Estas funciones de personalización pueden operar directamente sobre los tipos de fila y de elemento, sin necesidad de pasar por QModelIndex y QVariant.
De este modo, el código para serializar datos puede ser seguro en cuanto a tipos y puede permanecer junto a la implementación del tipo que se utiliza para almacenar los datos.
Además, supportedDragActions y supportedDropActions son propiedades que se pueden configurar para cada instancia de QRangeModel.
Temas avanzados de C++
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 sin calificaciones get. Hazlo para tu tipo de fila personalizado a fin de que los datos estructurados existentes estén disponibles para el marco de trabajo de modelo/vista 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>())); };
}En la implementación anterior, los valores de « title » y « author » del tipo « Book » se devuelven como « const », por lo que el modelo marca los elementos de esas dos columnas como de solo lectura. El usuario no podrá activar la edición, y « setData()» no realiza ninguna acción y devuelve «false». En el caso de 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 un Book, devolverá una referencia mutable de la variable correspondiente. El modelo hace que esas columnas sean editables, tanto para el usuario como para el acceso programático.
Nota: La implementación de get anterior requiere C++23.
Consideraciones sobre la compatibilidad binaria
QRangeModel no es una clase de plantilla. Es seguro pasar instancias de QRangeModel (por puntero o por referencia, al igual que con todas las clases de QObject ) a través de las API de las bibliotecas, o almacenar QRangeModel por valor en una clase pública de una biblioteca.
Sin embargo, el constructor de QRangeModel es una plantilla e inline, y la implementación interna —especializada en el tipo del rango sobre el que opera el modelo— se instancia en el constructor. No se debe llamar al constructor en una implementación en línea de una API de biblioteca. Esto da lugar a infracciones de ODR y podría romper la compatibilidad binaria de dicha biblioteca si la versión de Qt con la que se compila es diferente de la versión de Qt con la que se compila la aplicación que utiliza dicha biblioteca.
Es posible que tampoco se utilicen las implementaciones nuevas y optimizadas de las funciones virtuales introducidas en versiones posteriores de Qt si QRangeModel detecta que la implementación se compiló con una versión anterior de Qt. Por ejemplo, las implementaciones de sort() y match() son nuevas en Qt 6.12, pero no serán llamadas por una aplicación que se haya compilado con Qt 6.11, incluso si la biblioteca de Qt utilizada es Qt 6.12. Para beneficiarte de estas nuevas sobrescrituras, vuelve a compilar tu aplicación.
Véase también QRangeModelAdapter, QAbstractItemModel, QStandardItemModel y Programación Modelo/Vista.
Documentación sobre tipos de miembros
[since 6.11] enum class QRangeModel::AutoConnectPolicy
Esta enumeración define si, y en qué casos, QRangeModel conecta automáticamente las señales modificadas de las propiedades a la señal dataChanged() del modelo. Solo se conectan las propiedades que coincidan con uno de los valores de role names.
| Constante | Valor | Descripción |
|---|---|---|
QRangeModel::AutoConnectPolicy::None | 0 | No se realizan conexiones automáticamente. |
QRangeModel::AutoConnectPolicy::Full | 1 | Las señales de todas las propiedades relevantes se conectan automáticamente para todos los elementos de « QObject ». Esto incluye los elementos de « QObject » que se añaden a las filas y columnas recién insertadas. |
QRangeModel::AutoConnectPolicy::OnRead | 2 | Las señales de las propiedades relevantes se conectan la primera vez que el modelo lee la propiedad. |
La sobrecarga de memoria que supone establecer conexiones automáticas puede ser considerable. Una conexión automática completa no requiere ningún tipo de registro adicional a la propia conexión, pero cada conexión ocupa memoria, y conectar todas las propiedades de todos los objetos puede resultar muy costoso, especialmente si solo cambian unas pocas propiedades de un subconjunto de objetos.
La política de conexión «OnRead» no establecerá conexiones con objetos o propiedades que nunca se lean (por ejemplo, que nunca se muestren en una vista), pero recordar qué conexiones se han establecido requiere cierta sobrecarga administrativa y un aumento impredecible de la memoria con el tiempo. Por ejemplo, desplazarse hacia abajo por una lista larga de elementos puede dar lugar fácilmente a que se establezcan miles de nuevas conexiones.
Esta enumeración se introdujo en Qt 6.11.
Véase también autoConnectPolicy y roleNames().
[since 6.12] enum class QRangeModel::DropOperation
Esta enumeración define cómo se escriben en el modelo los datos descodificados en una personalización de ` dropMimeData()`.
| Constante | Valor | Descripción |
|---|---|---|
QRangeModel::DropOperation::DontDrop | 0 | Los datos no deben añadirse al modelo. |
QRangeModel::DropOperation::Automatic | 1 | Qt determina cómo se añaden los datos al modelo. |
QRangeModel::DropOperation::OverwriteAndIgnore | 2 | Sobrescribir el elemento sobre el que se ha soltado y los elementos siguientes, y descartar cualquier dato soltado que no quepa. |
QRangeModel::DropOperation::OverwriteAndExtend | 3 | Sobrescribir el elemento sobre el que se ha soltado y los elementos siguientes, y ampliar el modelo para que quepan todos los datos soltados. |
QRangeModel::DropOperation::InsertAsSiblings | 4 | Insertar todos los datos arrastrados como elementos hermanos del elemento sobre el que se han soltado. |
QRangeModel::DropOperation::InsertAsChildren | 5 | Insertar todos los datos soltados como hijos del elemento sobre el que se han soltado. |
Una personalización de ` dropMimeData()` puede devolver un valor booleano en su lugar; en ese caso, ` false ` se asigna al valor `DontDrop`, y ` true ` a `Automatic`.
Esta enumeración se introdujo en Qt 6.12.
Véase también canDropMimeData() y dropMimeData().
enum class QRangeModel::RowCategory
Esta enumeración describe cómo debe presentar « QRangeModel » los elementos del rango con el que se ha creado.
| Constante | Valor | Descripción |
|---|---|---|
QRangeModel::RowCategory::Default | 0 | QRangeModel determina cómo se presentan las filas. |
QRangeModel::RowCategory::MultiRoleItem | 1 | QRangeModel presentará los elementos con un metaobjeto como elementos de múltiples roles, incluso cuando se utilice en un rango unidimensional. |
Especializa la plantilla RowOptions para tu tipo y añade una variable miembro pública static constexpr auto rowCategory con uno de los valores de esta enumeración.
Véase también ` RowOptions`.
Documentación de la propiedad
[since 6.11] autoConnectPolicy : AutoConnectPolicy
si el modelo se conecta automáticamente a las notificaciones de cambio de propiedad.
Si QRangeModel opera sobre una estructura de datos que contiene el mismo tipo de subclase de QObject que su tipo de fila o elemento, entonces puede conectar automáticamente las propiedades de los QObjects a la señal dataChanged(). Para las filas de QObject, esto se realiza para cada columna, asignándolas a la propiedad Qt::DisplayRole. Para los elementos, esto se realiza para aquellas propiedades que coincidan con una de las role names.
Por defecto, el valor de esta propiedad es None, por lo que no se establece ninguna conexión de este tipo. Al cambiar el valor de esta propiedad, siempre se rompen todas las conexiones existentes.
Nota: Las conexiones no se rompen ni se crean si se sustituyen los QObjects de la estructura de datos sobre la que opera QRangeModel.
Esta enumeración se introdujo en Qt 6.11.
Funciones de acceso:
| QRangeModel::AutoConnectPolicy | autoConnectPolicy() const |
| void | setAutoConnectPolicy(QRangeModel::AutoConnectPolicy policy) |
Señal del notificador:
| void | autoConnectPolicyChanged(QRangeModel::AutoConnectPolicy policy) |
Véase también roleNames().
roleNames : QHash<int, QByteArray>
Esta propiedad contiene los nombres de los roles del modelo.
Si todas las columnas del rango son del mismo tipo, y si ese tipo proporciona un metaobjeto (es decir, si es un gadget o una subclase de QObject ), entonces esta propiedad contiene los nombres de las propiedades de ese tipo, asignadas a valores de Qt::ItemDataRole a partir de Qt::UserRole. Además, una propiedad de rol «modelData» proporciona acceso a la instancia del gadget o de QObject.
Se puede anular este comportamiento predeterminado estableciendo esta propiedad explícitamente en una asignación no vacía. Al establecer esta propiedad en una asignación vacía, o al utilizar resetRoleNames(), se restablece el comportamiento predeterminado.
Funciones de acceso:
| virtual QHash<int, QByteArray> | roleNames() const override |
| void | setRoleNames(const QHash<int, QByteArray> &names) |
| void | resetRoleNames() |
Señal del notificador:
| void | roleNamesChanged() |
Véase también QAbstractItemModel::roleNames().
[since 6.12] sortCollator : QCollator
Esta propiedad contiene el ordenador que se utilizará al ordenar el modelo
El valor por defecto de esta propiedad es un « QCollator » para la configuración regional C. La ordenación no tendrá en cuenta la configuración regional y distinguirá entre mayúsculas y minúsculas. Al establecer un ordenador, la ordenación tendrá en cuenta la configuración regional.
Esta enumeración se introdujo en Qt 6.12.
Funciones de acceso:
| QCollator | sortCollator() const |
| void | setSortCollator(const QCollator &collator) |
| void | resetSortCollator() |
Señal del notificador:
| void | sortCollatorChanged(const QCollator &collator) |
Véase también sort(), sortRole y QSortFilterProxyModel.
[since 6.12] sortRole : int
Esta propiedad contiene la función de datos que se utiliza al ordenar los elementos.
El valor por defecto es « Qt::DisplayRole ».
Esta enumeración se introdujo en Qt 6.12.
Funciones de acceso:
| int | sortRole() const |
| void | setSortRole(int role) |
| void | resetSortRole() |
Señal de notificador:
| void | sortRoleChanged(int role) |
Véase también ` sort()`, ` sortCollator` y ` QSortFilterProxyModel`.
[since 6.12] supportedDragActions : Qt::DropActions
Esta propiedad contiene las acciones de arrastre que admite este modelo.
Las acciones que el modelo no admite, como mover datos fuera de un modelo de solo lectura, se eliminarán al configurar las acciones.
Nota: Es posiblesobrescribir esta función en una subclase de ` QRangeModel `, pero podría alterar el comportamiento de la propiedad.
Esta enumeración se introdujo en Qt 6.12.
Funciones de acceso:
| virtual Qt::DropActions | supportedDragActions() const override |
| void | setSupportedDragActions(Qt::DropActions actions) |
| void | resetSupportedDragActions() |
Señal de notificador:
| void | supportedDragActionsChanged(Qt::DropActions actions) |
Véase también ` supportedDropActions`.
[since 6.12] supportedDropActions : Qt::DropActions
Esta propiedad contiene las acciones de arrastre y soltar compatibles con este modelo.
Los modelos de solo lectura no admiten ninguna acción al soltar.
Nota: Es posiblesobrescribir esta función en una subclase de ` QRangeModel `, pero podría alterar el comportamiento de la propiedad.
Esta enumeración se introdujo en Qt 6.12.
Funciones de acceso:
| virtual Qt::DropActions | supportedDropActions() const override |
| void | setSupportedDropActions(Qt::DropActions actions) |
| void | resetSupportedDropActions() |
Señal del notificador:
| void | supportedDropActionsChanged(Qt::DropActions actions) |
Véase también ` supportedDragActions`.
Documentación de las funciones miembro
[explicit] template <typename Range, int = true> QRangeModel::QRangeModel(Range &&range, QObject *parent = nullptr)
[explicit] template <typename Range, int = true> QRangeModel::QRangeModel(Range &&range, QObject *parent = nullptr)
[explicit] template <
typename Range,
typename Protocol,
int = true
>
QRangeModel::QRangeModel(Range &&range, Protocol &&protocol, QObject *parent = nullptr)
Crea una instancia de ` QRangeModel ` que opera sobre los datos de ` range`. El ` range ` debe ser un rango secuencial para el que el compilador encuentre sobrecargas de ` begin ` y ` end ` mediante la búsqueda dependiente de argumentos, o para el que se hayan implementado ` std::begin ` y ` std::end `. Si se proporciona ` protocol `, el modelo representará el rango como un árbol utilizando la implementación del protocolo. La instancia del modelo se convierte en un elemento secundario de ` parent`.
range puede ser un puntero o un envoltorio de referencia; en ese caso, las API del modelo que modifican el contenido (como setData() o insertRow()) modificarán los datos de la instancia de rango a la que se hace referencia. Si range es un valor (o se ha movido al modelo), entonces hay que conectarse a las señales emitidas por el modelo para responder a los cambios en los datos.
QRangeModel No se accederá a range durante su construcción. Esto permite pasar a este constructor un puntero o una referencia a un objeto de rango que aún no esté completamente construido, por ejemplo, cuando se utiliza subclassing QRangeModel.
Si el ` range ` se ha movido al modelo, entonces el rango y todos los datos que contiene se destruirán al destruirse el modelo.
Nota: Aunque el modelo no adquiere la propiedad del objeto de rango en ningún otro caso, no debes modificar el ` range ` directamente una vez que el modelo se haya construido y se haya pasado a una vista. Dichas modificaciones no emitirán las señales necesarias para mantener a los usuarios del modelo (otros modelos o vistas) sincronizados con el modelo, lo que dará lugar a resultados incoherentes, comportamiento indefinido y fallos del sistema. Utiliza ` QRangeModelAdapter ` para interactuar de forma segura con el rango subyacente y mantener el modelo actualizado.
Véase también QRangeModelAdapter.
[override virtual noexcept] QRangeModel::~QRangeModel()
Destruye el « QRangeModel ».
No se accede al rango a partir del cual se construyó el modelo, y este solo se destruye si el modelo se construyó a partir de un rango en el que se había realizado una entrada.
[override virtual] QModelIndex QRangeModel::buddy(const QModelIndex &index) const
Reimplementa: ` QAbstractItemModel::buddy(const QModelIndex &index) const`.
[override virtual] bool QRangeModel::canDropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent) const
Reimplementa: QAbstractItemModel::canDropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent) const.
Si existe una personalización de ` ItemAccess ` disponible para el tipo de elemento almacenado en el rango, y si dicha personalización implementa una función miembro de clase adecuada ` canDropMimeData()`, entonces esta implementación llama a dicha función y devuelve el resultado.
template <>
struct QRangeModel::ItemAccess<ColorEntry>
{
static bool canDropMimeData(const QMimeData *mimeData)
{
// ...
return true;
}
};De lo contrario, si hay disponible una personalización de ` RowOptions ` para el tipo de fila del rango con una función miembro de clase ` canDropMimeData()` adecuada, esta implementación devuelve el resultado de llamar a dicha función.
template <>
struct QRangeModel::RowOptions<ColorEntry>
{
static bool canDropMimeData(const QMimeData *mimeData)
{
// ...
return true;
}
};Si no hay ninguna personalización disponible, devuelve el resultado de la implementación predeterminada de ` QAbstractItemModel `.
Véase también Drag'n'drop handling, RowOptions::canDropMimeData(), ItemAccess::canDropMimeData(), dropMimeData(), mimeTypes() y mimeData().
[override virtual] bool QRangeModel::canFetchMore(const QModelIndex &parent) const
Reimplementa: QAbstractItemModel::canFetchMore(const QModelIndex &parent) const.
[override virtual] bool QRangeModel::clearItemData(const QModelIndex &index)
Reimplementa: QAbstractItemModel::clearItemData(const QModelIndex &index).
Sustituye el valor almacenado en el rango en index por un valor construido por defecto.
En el caso de modelos que operan sobre un rango de solo lectura, o sobre una columna de solo lectura en un tipo de fila que implemente ` the C++ tuple protocol`, esta implementación devuelve inmediatamente ` false `.
[override virtual] int QRangeModel::columnCount(const QModelIndex &parent = {}) const
Reimplementa: QAbstractItemModel::columnCount(const QModelIndex &parent) const.
Devuelve el número de columnas del modelo. Esta función devuelve el mismo valor para todos los índices de parent.
En el caso de los modelos que operan con un tipo de fila de tamaño estático, este valor devuelto es siempre el mismo a lo largo de toda la vida útil del modelo. En el caso de los modelos que operan con un tipo de fila de tamaño dinámico, el modelo devuelve el número de elementos de la primera fila, o 0 si el modelo no tiene filas.
Véase también ` rowCount ` y ` insertColumns()`.
[override virtual] QVariant QRangeModel::data(const QModelIndex &index, int role = Qt::DisplayRole) const
Reimplementa: ` QAbstractItemModel::data(const QModelIndex &index, int role) const`.
Devuelve los datos almacenados en el « role » dado para el valor del rango al que hace referencia « index ».
Si el tipo de elemento para ese índice es un contenedor asociativo que mapea desde int, Qt::ItemDataRole o QString a un QVariant, entonces se busca el dato de rol en ese contenedor y se devuelve.
Si el elemento es un gadget o un QObject, la implementación devuelve el valor de la propiedad del elemento que coincida con la entrada role en la asignación roleNames().
En caso contrario, la implementación devuelve un ` QVariant ` construido a partir del elemento mediante ` QVariant::fromValue() ` para ` Qt::DisplayRole ` o ` Qt::EditRole`. Para otros roles, la implementación devuelve un ` QVariant` no válido (construido por defecto).
Véase también Qt::ItemDataRole, setData() y headerData().
[override virtual] bool QRangeModel::dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent)
Reimplementa: QAbstractItemModel::dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent).
Si existe una personalización de ` ItemAccess ` disponible para el tipo de elemento almacenado en el rango, y si dicha personalización implementa una función miembro de clase adecuada ` dropMimeData()`, entonces esta implementación llama a dicha función y devuelve el resultado.
template <>
struct QRangeModel::ItemAccess<ColorEntry>
{
static bool dropMimeData(const QMimeData *mimeData, auto inserter)
{
QByteArray data = mimeData->data(mimeTypes().first());
if (data.isEmpty())
return false;
QTextStream stream(&data, QIODevice::ReadOnly);
while (!stream.atEnd()) {
QString colorName;
stream >> colorName;
inserter = ColorEntry(colorName);
}
return true;
}
};De lo contrario, si existe una personalización de ` RowOptions ` disponible para el tipo de fila del rango con una función miembro de clase adecuada ` dropMimeData()`, esta implementación devuelve el resultado de llamar a dicha función.
template <>
struct QRangeModel::RowOptions<ColorEntry>
{
static bool dropMimeData(const QMimeData *mimeData, auto inserter)
{
const QByteArray data = mimeData->data(mimeTypes().first());
if (data.isEmpty())
return false;
QXmlStreamReader stream(data);
while (!stream.atEnd()) {
stream.readNext();
if (stream.isStartElement() && stream.name() == u"li"_s)
inserter = ColorEntry(stream.readElementText());
}
return true;
}
};Si no hay ninguna personalización disponible, devuelve el resultado de la implementación predeterminada de ` QAbstractItemModel `.
Véase también Drag'n'drop handling, RowOptions::dropMimeData(), ItemAccess::dropMimeData(), canDropMimeData(), mimeTypes() y mimeData().
[override virtual protected] bool QRangeModel::event(QEvent *event)
Reimplementa: QObject::event(QEvent *e).
[override virtual protected] bool QRangeModel::eventFilter(QObject *object, QEvent *event)
Reimplementa: QObject::eventFilter(QObject *watched, QEvent *event).
[override virtual] void QRangeModel::fetchMore(const QModelIndex &parent)
Reimplementa: ` QAbstractItemModel::fetchMore(const QModelIndex &parent)`.
[override virtual] Qt::ItemFlags QRangeModel::flags(const QModelIndex &index) const
Reimplementa: ` QAbstractItemModel::flags(const QModelIndex &index) const`.
Devuelve los indicadores del elemento para el index dado.
La implementación devuelve una combinación de indicadores que habilita el elemento (ItemIsEnabled) y permite su selección (ItemIsSelectable). En el caso de modelos que operan sobre un rango con datos mutables, también establece el indicador que permite que el elemento sea editable (ItemIsEditable).
Los modelos que devuelven una lista no vacía de mimeTypes() también establecen el indicador Qt::ItemIsDragEnabled y, a menos que sean de solo lectura, el indicador Qt::ItemIsDropEnabled.
Los modelos planos establecen el indicador Qt::ItemNeverHasChildren para todos los elementos, mientras que los modelos jerárquicos establecen ese indicador para todos los elementos de las columnas situadas por encima de la 0.
Para personalizar los indicadores según tus propios tipos de datos, proporciona una especialización de RowOptions y/o ItemAccess para tus tipos de fila o de elemento e implementa una función miembro estática flags():
template <>
struct QRangeModel::ItemAccess<ColorEntry>
{
static Qt::ItemFlags flags(const ColorEntry &entry)
{
return entry.flags();
}
};Véase también Qt::ItemFlags, RowOptions y ItemAccess.
[override virtual] bool QRangeModel::hasChildren(const QModelIndex &parent = QModelIndex()) const
Reimplementa: QAbstractItemModel::hasChildren(const QModelIndex &parent) const.
[override virtual] QVariant QRangeModel::headerData(int section, Qt::Orientation orientation, int role = Qt::DisplayRole) const
Reimplementa: ` QAbstractItemModel::headerData(int section, Qt::Orientation orientation, int role) const`.
Devuelve los datos correspondientes a la ` role ` y ` section ` indicadas en el encabezado con el ` orientation` especificado.
En el caso de los encabezados horizontales, el número de sección se corresponde con el número de columna. Del mismo modo, en el caso de los encabezados verticales, el número de sección se corresponde con el número de fila.
Para el encabezado horizontal y los valores Qt::DisplayRole y role, los modelos que operan sobre un rango que utiliza una matriz como tipo de fila devuelven section. Si el tipo de fila es una tupla, la implementación devuelve el nombre del tipo en section. Para las filas que son de tipo «gadget» o « QObject », esta función devuelve el nombre de la propiedad en el índice de section.
Para personalizar los datos del encabezado horizontal de tu propio rango, proporciona una especialización de RowOptions para tus tipos de fila e implementa una función miembro de clase headerData():
template <>
struct QRangeModel::RowOptions<ColorEntry>
{
static QVariant headerData(int section, int role)
{
switch (section) {
// ...
}
return {};
}
};En el caso del encabezado vertical, esta función siempre devuelve el resultado de la implementación predeterminada de ` QAbstractItemModel`.
Véase también Qt::ItemDataRole, setHeaderData(), QHeaderView y RowOptions.
[override virtual] QModelIndex QRangeModel::index(int row, int column, const QModelIndex &parent = {}) const
Reimplementa: ` QAbstractItemModel::index` (int row, int column, const QModelIndex &parent) const.
Devuelve el índice del elemento del modelo en row y column en parent.
Si se pasa un padre válido, se obtiene un índice no válido para los modelos que operan con rangos de listas y tablas.
Véase también parent().
[override virtual] bool QRangeModel::insertColumns(int column, int count, const QModelIndex &parent = {})
Reimplementa: QAbstractItemModel::insertColumns(int column, int count, const QModelIndex &parent).
Inserta count columnas vacías antes del elemento situado en column en todas las filas del rango parent. Devuelve true si se realiza correctamente; en caso contrario, devuelve false.
Nota: Un tipo de fila de tamaño dinámico debe proporcionar una función miembro insert(const_iterator, size_t, value_type).
Para los modelos que operan sobre un rango de solo lectura, o sobre un rango con un tipo de fila de tamaño estático (como una tupla, una matriz o una estructura), esta implementación no realiza ninguna acción y devuelve false inmediatamente. Este es siempre el caso de los modelos de árbol.
[override virtual] bool QRangeModel::insertRows(int row, int count, const QModelIndex &parent = {})
Reimplementa: ` QAbstractItemModel::insertRows` (int row, int count, const QModelIndex &parent).
Inserta count filas vacías antes del row dado en el rango situado en parent. Devuelve true si se realiza correctamente; en caso contrario, devuelve false.
Nota: El rango debe tener un tamaño dinámico y proporcionar una función miembro insert(const_iterator, size_t, value_type).
En el caso de modelos que operan sobre un rango de solo lectura o de tamaño estático (como una matriz), esta implementación no realiza ninguna acción y devuelve inmediatamente ` false `.
Nota: Para rangos con un tipo de columna de tamaño dinámico, la columna debe proporcionar una función miembro ` resize(size_t) `.
[override virtual] QMap<int, QVariant> QRangeModel::itemData(const QModelIndex &index) const
Reimplementa: QAbstractItemModel::itemData(const QModelIndex &index) const.
Devuelve un mapa con los valores de todos los roles predefinidos en el modelo para el elemento situado en el index dado.
Si el tipo de elemento para ese index es un contenedor asociativo que asigna valores de int, Qt::ItemDataRole o QString a un QVariant, se devuelven los datos de dicho contenedor.
Si el tipo del elemento es un gadget o una subclase de ` QObject `, se devuelven los valores de aquellas propiedades que coincidan con un ` role name `.
Si el elemento no es un contenedor asociativo, un gadget o una subclase de QObject, entonces se invoca la implementación de la clase base.
Véase también ` setItemData()`, ` Qt::ItemDataRole` y ` data()`.
[override virtual] QModelIndexList QRangeModel::match(const QModelIndex &start, int role, const QVariant &value, int hits, Qt::MatchFlags flags) const
Reimplementa: ` QAbstractItemModel::match` (const QModelIndex &start, int role, const QVariant &value, int hits, Qt::MatchFlags flags) const.
Devuelve una lista de índices de los elementos de la columna de start en los que los datos almacenados en role coinciden con value, utilizando los criterios de coincidencia definidos en flags. Utiliza hits = -1 para encontrar todos los elementos que coincidan.
Nota: Esta implementación lee los datos directamente del rango C++ subyacente y no se ejecuta a través de las sobrescrituras de data().
[override virtual] QMimeData *QRangeModel::mimeData(const QModelIndexList &indexes) const
Reimplementa: ` QAbstractItemModel::mimeData(const QModelIndexList &indexes) const`.
Si existe una personalización de ` ItemAccess ` para el tipo de elemento almacenado en el rango, y si dicha personalización implementa una función miembro de clase adecuada ` mimeData()`, entonces esta implementación llama a dicha función y devuelve el resultado.
template <>
struct QRangeModel::ItemAccess<ColorEntry>
{
static QMimeData *mimeData(const auto &range)
{
QByteArray data;
QTextStream stream(&data, QIODevice::WriteOnly);
for (const auto &[item, index] : range)
stream << item.colorName() << Qt::endl;
QMimeData *result = new QMimeData;
result->setData(mimeTypes().first(), data);
// Qt handles encoding into the default mime type
return result;
}
};De lo contrario, si existe una personalización de ` RowOptions ` disponible para el tipo de fila del rango con una función miembro de clase ` mimeData()` adecuada, esta implementación devuelve el resultado de llamar a dicha función.
template <>
struct QRangeModel::RowOptions<ColorEntry>
{
template <typename Items>
static QMimeData *mimeData(const Items &items)
{
if (items.isEmpty())
return nullptr;
QByteArray data;
QXmlStreamWriter stream(&data);
stream.writeStartElement("ul");
for (const auto &[item, index] : items)
stream.writeTextElement("li", item.colorName());
stream.writeEndElement();
QMimeData *mimeData = new QMimeData;
mimeData->setData(mimeTypes().first(), data);
return mimeData;
}
};Si no hay ninguna personalización disponible, devuelve el resultado de la implementación predeterminada de ` QAbstractItemModel `.
Véase también Drag'n'drop handling, RowOptions::mimeData(), ItemAccess::mimeData(), canDropMimeData(), dropMimeData() y mimeTypes().
[override virtual] QStringList QRangeModel::mimeTypes() const
Reimplementa: QAbstractItemModel::mimeTypes() const.
Si existe una personalización de ` ItemAccess ` para el tipo de elemento almacenado en el rango, y si dicha personalización implementa una función miembro de clase adecuada ` mimeTypes()`, esta implementación llama a dicha función y devuelve el resultado.
template <>
struct QRangeModel::ItemAccess<ColorEntry>
{
static QStringList mimeTypes()
{
return {
u"text/plain"_s,
u"application/x-qabstractitemmodeldatalist"_s
};
}
};De lo contrario, si hay disponible una personalización de ` RowOptions ` para el tipo de fila del rango con una función miembro de clase ` mimeTypes()` adecuada, esta implementación devuelve el resultado de llamar a dicha función.
template <>
struct QRangeModel::RowOptions<ColorEntry>
{
static QStringList mimeTypes()
{
return {
u"text/html"_s
};
}
};Si no hay ninguna personalización disponible, devuelve el resultado de la implementación predeterminada de ` QAbstractItemModel `.
Véase también Drag'n'drop handling, RowOptions::mimeTypes(), ItemAccess::mimeTypes(), canDropMimeData(), dropMimeData() y mimeData().
[override virtual] bool QRangeModel::moveColumns(const QModelIndex &sourceParent, int sourceColumn, int count, const QModelIndex &destinationParent, int destinationColumn)
Reimplementa: QAbstractItemModel::moveColumns(const QModelIndex &sourceParent, int sourceColumn, int count, const QModelIndex &destinationParent, int destinationChild).
Mueve las columnas de count que comienzan por el sourceColumn dado, bajo el padre sourceParent, a la columna destinationColumn bajo el padre destinationParent.
Devuelve ` true ` si las columnas se han movido correctamente; en caso contrario, devuelve ` false`.
[override virtual] bool QRangeModel::moveRows(const QModelIndex &sourceParent, int sourceRow, int count, const QModelIndex &destinationParent, int destinationRow)
Reimplementa: QAbstractItemModel::moveRows(const QModelIndex &sourceParent, int sourceRow, int count, const QModelIndex &destinationParent, int destinationChild).
Mueve las filas de ` count ` que comienzan por el ` sourceRow ` dado, bajo el padre ` sourceParent `, a la fila ` destinationRow ` bajo el padre ` destinationParent`.
Devuelve ` true ` si las filas se han movido correctamente; en caso contrario, devuelve ` false`.
[override virtual] void QRangeModel::multiData(const QModelIndex &index, QModelRoleDataSpan roleDataSpan) const
Reimplementa: ` QAbstractItemModel::multiData` (const QModelIndex &index, QModelRoleDataSpan roleDataSpan) const.
[override virtual] QModelIndex QRangeModel::parent(const QModelIndex &child) const
Reimplementa: QAbstractItemModel::parent(const QModelIndex &index) const.
Devuelve el elemento padre del elemento situado en el índice child.
Esta función siempre produce un índice no válido para los modelos que operan con rangos de listas y tablas. Para los modelos que operan con un árbol, esta función devuelve el índice del elemento de fila devuelto por la implementación de parent() del protocolo de recorrido del árbol.
Véase también ` index()` y ` hasChildren()`.
[override virtual] bool QRangeModel::removeColumns(int column, int count, const QModelIndex &parent = {})
Reimplementa: QAbstractItemModel::removeColumns(int column, int count, const QModelIndex &parent).
Elimina las columnas de tipo « count » del elemento situado en column en todas las filas del rango situado en parent. Devuelve « true » si se realiza correctamente; en caso contrario, devuelve « false ».
Nota: Un tipo de fila de tamaño dinámico debe proporcionar una función miembro erase(const_iterator, size_t).
Para los modelos que operan sobre un rango de solo lectura, o sobre un rango con un tipo de fila de tamaño estático (como una tupla, una matriz o una estructura), esta implementación no realiza ninguna acción y devuelve inmediatamente false. Este es siempre el caso de los modelos de árbol.
[override virtual] bool QRangeModel::removeRows(int row, int count, const QModelIndex &parent = {})
Reimplementa: QAbstractItemModel::removeRows(int row, int count, const QModelIndex &parent).
Elimina las filas « count » del rango en parent, comenzando por el row dado. Devuelve « true » si se realiza correctamente; en caso contrario, devuelve « false ».
Nota: El rango debe tener un tamaño dinámico y proporcionar una función miembro erase(const_iterator, size_t).
Para los modelos que operan sobre un rango de solo lectura o de tamaño estático (como una matriz), esta implementación no realiza ninguna acción y devuelve inmediatamente false.
[override virtual protected slot] void QRangeModel::resetInternalData()
Reimplementa: QAbstractItemModel::resetInternalData().
[override virtual] QHash<int, QByteArray> QRangeModel::roleNames() const
Reimplementa: QAbstractItemModel::roleNames() const.
Nota: Es posiblesobrescribir esta función en una subclase de ` QRangeModel `, pero podría alterar el comportamiento de la propiedad.
Nota: Funcióngetter para la propiedad roleNames.
Véase también setRoleNames().
[override virtual] int QRangeModel::rowCount(const QModelIndex &parent = {}) const
Reimplementa: ` QAbstractItemModel::rowCount(const QModelIndex &parent) const`.
Devuelve el número de filas que se encuentran bajo el índice ` parent` dado. Se trata del número de elementos del rango raíz para un índice ` parent ` no válido.
Si el índice ` parent ` es válido, esta función siempre devuelve 0 para los modelos que operan con rangos de listas y tablas. En el caso de los árboles, devuelve el tamaño del rango devuelto por la implementación de `childRows()` del protocolo de recorrido de árboles.
Véanse también columnCount(), insertRows() y hasChildren().
[override virtual] bool QRangeModel::setData(const QModelIndex &index, const QVariant &data, int role = Qt::EditRole)
Reimplementa: QAbstractItemModel::setData(const QModelIndex &index, const QVariant &value, int role).
Establece los datos de « role » para el elemento de « index » en « data ».
Si el tipo de elemento de ese ` index ` es un contenedor asociativo que asocia valores de ` int`, ` Qt::ItemDataRole` o ` QString ` a un ` QVariant`, entonces se almacena ` data ` en ese contenedor para la clave especificada por ` role`.
Si el elemento es un gadget o QObject, entonces data se escribe en la propiedad del elemento que coincida con la entrada role en la asignación roleNames(). La función devuelve true si se ha encontrado una propiedad y si data almacenaba un valor que pudiera convertirse al tipo requerido; en caso contrario, devuelve false.
En caso contrario, esta implementación asigna el valor de data al elemento situado en index dentro del rango para Qt::DisplayRole y Qt::EditRole, y devuelve true. Para el resto de roles, la implementación devuelve false.
Para los modelos que operan sobre un rango de solo lectura, o sobre una columna de solo lectura en un tipo de fila que implemente the C++ tuple protocol, esta implementación devuelve false inmediatamente.
Véase también data().
[override virtual] bool QRangeModel::setHeaderData(int section, Qt::Orientation orientation, const QVariant &data, int role = Qt::EditRole)
Reimplementa: QAbstractItemModel::setHeaderData(int section, Qt::Orientation orientation, const QVariant &value, int role).
Véase también headerData().
[override virtual] bool QRangeModel::setItemData(const QModelIndex &index, const QMap<int, QVariant> &data)
Reimplementa: QAbstractItemModel::setItemData(const QModelIndex &index, const QMap<int, QVariant> &roles).
Si el tipo de elemento para ese ` index ` es un contenedor asociativo que establece una correspondencia entre ` int ` o ` Qt::ItemDataRole ` y ` QVariant`, entonces las entradas de ` data ` se almacenan en ese contenedor. Si el contenedor asociativo establece una correspondencia entre ` QString ` y ` QVariant`, entonces solo se almacenan aquellos valores de ` data ` para los que existe una correspondencia en la tabla ` role names `.
Si el tipo de elemento es un gadget o una subclase de QObject, las propiedades que coincidan con un role name se establecen en el valor correspondiente de data.
Los roles para los que no existe ninguna entrada en data no se modifican.
Para los tipos de elementos que se pueden copiar, esta implementación es transaccional y devuelve «true» si se han podido almacenar todas las entradas de data. Si no se ha podido actualizar alguna entrada, el contenedor original no se modifica en absoluto y la función devuelve «false».
Si el elemento no es un contenedor asociativo, un gadget o una subclase de ` QObject `, entonces se invoca la implementación de la clase base, que llama a ` setData()` para cada entrada de ` data`.
Véanse también ` itemData()`, ` setData()` y ` Qt::ItemDataRole`.
[override virtual] QModelIndex QRangeModel::sibling(int row, int column, const QModelIndex &index) const
Reimplementa: QAbstractItemModel::sibling(int row, int column, const QModelIndex &index) const.
Devuelve el elemento hermano situado en row y column correspondiente al elemento situado en index, o un QModelIndex inválido si no hay ningún elemento hermano en esa ubicación.
Esta implementación es considerablemente más rápida que recorrer el método ` parent()` del ` index`.
Véase también index(), QModelIndex::row() y QModelIndex::column().
[override virtual] void QRangeModel::sort(int column, Qt::SortOrder order = Qt::AscendingOrder)
Reimplementa: QAbstractItemModel::sort(int columna, Qt::SortOrder orden).
Ordena el rango subyacente según el orden especificado en ` order`, basándose en los datos de la ` sortRole ` (por defecto, `Qt::DisplayRole `) de los elementos de ` column`.
Nota: Esta implementación utiliza una función miembro ` sort(Compare comp) ` del rango de C++ si está disponible (como en ` std::list`), o, en su defecto, ` std::stable_sort() ` si el rango proporciona iteradores de acceso aleatorio. Si ninguna de las dos está disponible, la implementación no realiza ninguna acción y devuelve el resultado inmediatamente.
Nota: El acceso al elemento no desencadena la lectura de datos a través de sobrescrituras de data().
Véase también sortRole y QSortFilterProxyModel.
[override virtual] QSize QRangeModel::span(const QModelIndex &index) const
Reimplementa: ` QAbstractItemModel::span(const QModelIndex &index) const`.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.