En esta página

Programación de modelo/vista

Introducción a la programación de modelo/vista

Qt contiene un conjunto de clases de vista de elementos que utilizan una arquitectura de modelo/vista para gestionar la relación entre los datos y la forma en que se presentan al usuario. La separación de funcionalidades que introduce esta arquitectura ofrece a los desarrolladores una mayor flexibilidad para personalizar la presentación de los elementos y proporciona una interfaz de modelo estándar que permite utilizar una amplia gama de fuentes de datos con las vistas de elementos existentes. En este documento ofrecemos una breve introducción al paradigma Modelo/Vista, esbozamos los conceptos implicados y describimos la arquitectura del sistema de vistas de elementos. Se explica cada uno de los componentes de la arquitectura y se proporcionan ejemplos que muestran cómo utilizar las clases proporcionadas.

La arquitectura modelo/vista

Modelo-Vista-Controlador (MVC) es un patrón de diseño originario de Smalltalk que se utiliza a menudo en la creación de interfaces de usuario. En *Design Patterns*, Gamma et al. escriben:

El MVC consta de tres tipos de objetos. El Modelo es el objeto de la aplicación, la Vista es su presentación en pantalla y el Controlador define la forma en que la interfaz de usuario reacciona a las entradas del usuario. Antes del MVC, los diseños de interfaces de usuario tendían a agrupar estos objetos. El MVC los desacopla para aumentar la flexibilidad y la reutilización.

Si se combinan los objetos de vista y controlador, el resultado es la arquitectura Modelo/Vista. Esta sigue separando la forma en que se almacenan los datos de la forma en que se presentan al usuario, pero proporciona un marco más sencillo basado en los mismos principios. Esta separación permite mostrar los mismos datos en varias vistas diferentes e implementar nuevos tipos de vistas sin modificar las estructuras de datos subyacentes. Para permitir un manejo flexible de las entradas del usuario, introducimos el concepto de delegado. La ventaja de contar con un delegado en este marco es que permite personalizar la forma en que se representan y editan los elementos de datos.

Diagrama de interacción entre modelo, vista y delegadoLa arquitectura modelo/vista

El modelo se comunica con una fuente de datos, proporcionando una interfaz para los demás componentes de la arquitectura. La naturaleza de la comunicación depende del tipo de fuente de datos y de la forma en que se implemente el modelo.

La vista obtiene del modelo los índices del modelo; estos son referencias a elementos de datos. Al proporcionar los índices del modelo a la vista, esta puede recuperar elementos de datos de la fuente de datos.

En las vistas estándar, un delegado se encarga de representar los elementos de datos. Cuando se edita un elemento, el delegado se comunica directamente con el modelo utilizando los índices del modelo.

Por lo general, las clases de modelo y vista pueden dividirse en los tres grupos descritos anteriormente: modelos, vistas y delegados. Cada uno de estos componentes viene definido por clases abstractas que proporcionan interfaces comunes y, en algunos casos, implementaciones predeterminadas de las funcionalidades. Las clases abstractas están pensadas para ser subclasificadas con el fin de proporcionar el conjunto completo de funcionalidades que esperan otros componentes; esto también permite escribir componentes especializados.

Los modelos, las vistas y los delegados se comunican entre sí mediante señales y ranuras:

  • Las señales del modelo informan a la vista de los cambios en los datos que contiene la fuente de datos.
  • Las señales de la vista proporcionan información sobre la interacción del usuario con los elementos que se muestran.
  • Las señales del delegado se utilizan durante la edición para informar al modelo y a la vista sobre el estado del editor.

Modelos

Todos los modelos de elementos se basan en la clase ` QAbstractItemModel `. Esta clase define una interfaz que utilizan las vistas y los delegados para acceder a los datos. Los datos en sí no tienen por qué almacenarse en el modelo; pueden guardarse en una estructura de datos o en un repositorio proporcionado por una clase independiente, un archivo, una base de datos o algún otro componente de la aplicación.

Los conceptos básicos relacionados con los modelos se presentan en la sección sobre clases de modelo.

QAbstractItemModel QAbstractListModel proporciona una interfaz de datos lo suficientemente flexible como para gestionar vistas que representan datos en forma de tablas, listas y árboles. Sin embargo, a la hora de implementar nuevos modelos para estructuras de datos tipo lista y tabla, las clases y son mejores puntos de partida, ya que proporcionan implementaciones predeterminadas adecuadas de funciones comunes. Cada una de estas clases puede ser subclasificada para proporcionar modelos que admitan tipos especializados de listas y tablas. QAbstractTableModel

El proceso de creación de subclases de modelos se explica en la sección «Creación de nuevos modelos».

Qt proporciona algunos modelos ya preparados que pueden utilizarse para gestionar elementos de datos:

  • QRangeModel adapta un contenedor de C++ existente o cualquier rango iterable de C++ al marco de trabajo de modelo/vista sin necesidad de crear subclases.
  • QStringListModel se utiliza para almacenar una lista sencilla de elementos « QString ».
  • QStandardItemModel gestiona estructuras de árbol más complejas de elementos, cada uno de los cuales puede contener datos arbitrarios.
  • QFileSystemModel proporciona información sobre archivos y directorios del sistema de archivos local.
  • QSqlQueryModel, QSqlTableModel y QSqlRelationalTableModel se utilizan para acceder a bases de datos mediante las convenciones de modelo/vista.

Si estos modelos estándar no satisfacen tus necesidades, puedes crear subclases de QAbstractItemModel, QAbstractListModel o QAbstractTableModel para crear tus propios modelos personalizados. Alternativamente, si tus datos ya se encuentran en un contenedor o rango de C++, QRangeModel suele poder adaptarlos sin necesidad de crear subclases.

Vistas

Se proporcionan implementaciones completas para diferentes tipos de vistas: QListView muestra una lista de elementos, QTableView muestra los datos de un modelo en una tabla y QTreeView muestra los elementos del modelo en una lista jerárquica. Cada una de estas clases se basa en la clase base abstracta QAbstractItemView. Aunque estas clases son implementaciones listas para usar, también se pueden subclasificar para proporcionar vistas personalizadas.

Las vistas disponibles se analizan en la sección sobre clases de vista.

Delegados

QAbstractItemDelegate es la clase base abstracta para los delegados en el marco de trabajo de modelo/vista. La implementación predeterminada del delegado la proporciona QStyledItemDelegate, y es la que utilizan como delegado predeterminado las vistas estándar de Qt. Sin embargo, QStyledItemDelegate y QItemDelegate son alternativas independientes para dibujar y proporcionar editores para los elementos de las vistas. La diferencia entre ellas es que QStyledItemDelegate utiliza el estilo actual para dibujar sus elementos. Por lo tanto, recomendamos utilizar QStyledItemDelegate como clase base al implementar delegados personalizados o al trabajar con hojas de estilo de Qt.

Los delegados se describen en la sección sobre clases de delegado.

Ordenación

Hay dos formas de abordar la ordenación en la arquitectura modelo/vista; la elección de una u otra depende del modelo subyacente.

Si su modelo es ordenable, es decir, si reimplementa la función QAbstractItemModel::sort(), tanto QTableView como QTreeView proporcionan una API que le permite ordenar los datos de su modelo mediante programación. Además, puede habilitar la ordenación interactiva (es decir, permitir que los usuarios ordenen los datos haciendo clic en los encabezados de la vista), conectando la señal « QHeaderView::sortIndicatorChanged()» a la ranura « QTableView::sortByColumn()» o a la ranura « QTreeView::sortByColumn()», respectivamente.

El enfoque alternativo, si su modelo no dispone de la interfaz necesaria o si desea utilizar una vista de lista para presentar sus datos, consiste en utilizar un modelo proxy para transformar la estructura de su modelo antes de presentar los datos en la vista. Esto se trata en detalle en la sección sobre modelos proxy.

Clases de conveniencia

Existen varias clases de conveniencia derivadas de las clases de vista estándar, pensadas para facilitar el trabajo de las aplicaciones que se basan en las clases de vista de elementos y de tabla de Qt. No están pensadas para ser subclasificadas.

Entre los ejemplos de estas clases se incluyen QListWidget, QTreeWidget y QTableWidget.

Estas clases son menos flexibles que las clases de vista y no pueden utilizarse con modelos arbitrarios. Recomendamos utilizar un enfoque modelo/vista para gestionar los datos en las vistas de elementos, a menos que se necesite imperativamente un conjunto de clases basadas en elementos.

Si desea aprovechar las características que ofrece el enfoque «modelo/vista» sin dejar de utilizar una interfaz basada en elementos, considere la posibilidad de utilizar clases de vista, como QListView, QTableView y QTreeView junto con QStandardItemModel.

Uso de modelos y vistas

En las siguientes secciones se explica cómo utilizar el patrón modelo/vista en Qt. Cada sección incluye un ejemplo y va seguida de otra sección que muestra cómo crear nuevos componentes.

Dos modelos incluidos en Qt

Dos de los modelos estándar que ofrece Qt son QStandardItemModel y QFileSystemModel. QStandardItemModel es un modelo polivalente que puede utilizarse para representar diversas estructuras de datos necesarias para las vistas de lista, tabla y árbol. Este modelo también almacena los elementos de datos. QFileSystemModel es un modelo que gestiona la información sobre el contenido de un directorio. Por lo tanto, no almacena ningún elemento de datos por sí mismo, sino que simplemente representa archivos y directorios del sistema de archivos local.

QFileSystemModel ofrece un modelo listo para usar con el que experimentar y que se puede configurar fácilmente para utilizar datos existentes. Con este modelo, podemos mostrar cómo configurar un modelo para utilizarlo con vistas predeterminadas y explorar cómo manipular datos mediante índices de modelo.

Uso de vistas con un modelo existente

Las clases ` QListView ` y ` QTreeView ` son las vistas más adecuadas para utilizar con ` QFileSystemModel`. El ejemplo que se presenta a continuación muestra el contenido de un directorio en una vista de árbol junto a la misma información en una vista de lista. Las vistas comparten la selección del usuario, de modo que los elementos seleccionados aparecen resaltados en ambas vistas.

Vista en árbol y vista en lista para mostrar el mismo modelo de sistema de archivos

Configuramos un ` QFileSystemModel ` para que esté listo para su uso y creamos algunas vistas para mostrar el contenido de un directorio. Esto muestra la forma más sencilla de utilizar un modelo. La creación y el uso del modelo se realizan desde una única función ` main() `:

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    QSplitter *splitter = new QSplitter;

    QFileSystemModel *model = new QFileSystemModel;
    model->setRootPath(QDir::currentPath());

El modelo está configurado para utilizar datos de un sistema de archivos concreto. La llamada a setRootPath() indica al modelo qué unidad del sistema de archivos debe mostrar a las vistas.

Creamos dos vistas para poder examinar los elementos contenidos en el modelo de dos formas diferentes:

QTreeView *tree = new QTreeView(splitter);
tree->setModel(model);
tree->setRootIndex(model->index(QDir::currentPath()));

QListView *list = new QListView(splitter);
list->setModel(model);
list->setRootIndex(model->index(QDir::currentPath()));

Las vistas se construyen del mismo modo que otros widgets. Configurar una vista para mostrar los elementos del modelo es tan sencillo como llamar a su función ` setModel()` con el modelo de directorios como argumento. Filtramos los datos proporcionados por el modelo llamando a la función ` setRootIndex()` en cada vista, pasando un índice de modelo adecuado del modelo del sistema de archivos para el directorio actual.

La función index() utilizada en este caso es exclusiva de QFileSystemModel; le proporcionamos un directorio y devuelve un índice de modelo. Los índices de modelo se tratan en «Clases de modelo».

El resto de la función se limita a mostrar las vistas dentro de un widget «splitter» y a ejecutar el bucle de eventos de la aplicación:

    splitter->setWindowTitle("Two views onto the same file system model");
    splitter->show();
    return app.exec();
}

En el ejemplo anterior, no hemos mencionado cómo gestionar la selección de elementos. Este tema se trata con más detalle en la sección sobre la gestión de selecciones en las vistas de elementos.

Clases de modelo

Antes de examinar cómo se gestionan las selecciones, puede resultarte útil repasar los conceptos utilizados en el marco de trabajo modelo/vista.

Conceptos básicos

En la arquitectura modelo/vista, el modelo proporciona una interfaz estándar que las vistas y los delegados utilizan para acceder a los datos. En Qt, la interfaz estándar viene definida por la clase ` QAbstractItemModel `. Independientemente de cómo se almacenen los elementos de datos en cualquier estructura de datos subyacente, todas las subclases de ` QAbstractItemModel ` representan los datos como una estructura jerárquica que contiene tablas de elementos. Las vistas utilizan esta convención para acceder a los elementos de datos del modelo, pero no están limitadas en cuanto a la forma de presentar esta información al usuario.

Modelo de lista, modelo de tabla y modelo de árbol

Los modelos también notifican a las vistas asociadas cualquier cambio en los datos a través del mecanismo de señales y ranuras.

En esta sección se describen algunos conceptos básicos fundamentales para el modo en que otros componentes acceden a los elementos de datos a través de una clase de modelo. Los conceptos más avanzados se tratan en secciones posteriores.

Índices de modelo

Para garantizar que la representación de los datos se mantenga separada de la forma en que se accede a ellos, se introduce el concepto de índice de modelo. Cada dato que se puede obtener a través de un modelo está representado por un índice de modelo. Las vistas y los delegados utilizan estos índices para solicitar los elementos de datos que se van a mostrar.

Como resultado, solo el modelo necesita saber cómo obtener los datos, y el tipo de datos gestionados por el modelo puede definirse de forma bastante general. Los índices de modelo contienen un puntero al modelo que los creó, lo que evita confusiones al trabajar con más de un modelo.

const QAbstractItemModel *model = index.model();

Los índices de modelo proporcionan referencias temporales a datos concretos y pueden utilizarse para recuperar o modificar datos a través del modelo. Dado que los modelos pueden reorganizar sus estructuras internas de vez en cuando, los índices de modelo pueden dejar de ser válidos, por lo que no deben almacenarse. Si se requiere una referencia a largo plazo a un dato, debe crearse un índice de modelo persistente. Esto proporciona una referencia a la información que el modelo mantiene actualizada. Los índices de modelo temporales los proporciona la clase ` QModelIndex `, y los índices de modelo persistentes, la clase ` QPersistentModelIndex `.

Para obtener un índice de modelo que se corresponda con un elemento de datos, deben especificarse tres propiedades en el modelo: un número de fila, un número de columna y el índice de modelo de un elemento padre. En las secciones siguientes se describen y explican estas propiedades con detalle.

Filas y columnas

En su forma más básica, se puede acceder a un modelo como una tabla sencilla en la que los elementos se localizan mediante sus números de fila y columna. Esto no significa que los datos subyacentes se almacenen en una estructura de matriz; el uso de números de fila y columna es solo una convención que permite a los componentes comunicarse entre sí. Podemos recuperar información sobre cualquier elemento dado especificando sus números de fila y columna al modelo, y recibimos un índice que representa dicho elemento:

QModelIndex index = model->index(row, column /*...*/);

Los modelos que proporcionan interfaces para estructuras de datos sencillas de un solo nivel, como listas y tablas, no necesitan que se les facilite ninguna otra información; sin embargo, tal y como indica el código anterior, debemos proporcionar más información a la hora de obtener un índice del modelo.

Estructura del modelo de tabla mediante filas y columnasFilas y columnas

El diagrama muestra una representación de un modelo de tabla básico en el que cada elemento se localiza mediante un par de números de fila y columna. Obtenemos un índice del modelo que hace referencia a un elemento de datos pasando al modelo los números de fila y columna correspondientes.

QModelIndex indexA = model->index(0, 0, QModelIndex());
QModelIndex indexB = model->index(1, 1, QModelIndex());
QModelIndex indexC = model->index(2, 1, QModelIndex());

Los elementos de nivel superior de un modelo siempre se referencian especificando QModelIndex() como su elemento padre. Esto se trata en la siguiente sección.

Elementos padres

La interfaz tipo tabla que proporcionan los modelos para los datos de los elementos resulta ideal cuando se utilizan los datos en una vista de tabla o de lista; el sistema de números de filas y columnas se corresponde exactamente con la forma en que las vistas muestran los elementos. Sin embargo, estructuras como las vistas en árbol requieren que el modelo ofrezca una interfaz más flexible para los elementos que contiene. Como resultado, cada elemento también puede ser el padre de otra tabla de elementos, de forma muy similar a como un elemento de nivel superior en una vista de árbol puede contener otra lista de elementos.

Al solicitar un índice para un elemento del modelo, debemos proporcionar cierta información sobre el elemento padre de dicho elemento. Fuera del modelo, la única forma de hacer referencia a un elemento es a través de un índice del modelo, por lo que también debe indicarse el índice del modelo padre:

QModelIndex index = model->index(row, column, parent);
Estructura del modelo de árbol con elementos de nivel superior, de fila y de columnaPadres, filas y columnas

El diagrama muestra una representación de un modelo de árbol en el que cada elemento se identifica mediante un padre, un número de fila y un número de columna.

Los elementos «A» y «C» se representan como elementos hermanos de nivel superior en el modelo:

QModelIndex indexA = model->index(0, 0, QModelIndex());
QModelIndex indexC = model->index(2, 1, QModelIndex());

El elemento «A» tiene varios hijos. Se obtiene un índice del modelo para el elemento «B» con el siguiente código:

QModelIndex indexB = model->index(1, 0, indexA);

Funciones de los elementos

Los elementos de un modelo pueden desempeñar diversas funciones para otros componentes, lo que permite proporcionar diferentes tipos de datos según las distintas situaciones. Por ejemplo, Qt::DisplayRole se utiliza para acceder a una cadena que puede mostrarse como texto en una vista. Normalmente, los elementos contienen datos para varias funciones diferentes, y las funciones estándar se definen en Qt::ItemDataRole.

Podemos solicitar al modelo los datos del elemento pasándole el índice del modelo correspondiente al elemento y especificando una función para obtener el tipo de datos que deseamos:

QVariant value = model->data(index, role);
Diferentes funciones en un modeloRoles de los elementos

El rol indica al modelo a qué tipo de datos se hace referencia. Las vistas pueden mostrar los roles de diferentes maneras, por lo que es importante proporcionar la información adecuada para cada rol.

La sección «Creación de nuevos modelos » aborda con más detalle algunos usos específicos de los roles.

Los usos más comunes de los datos de los elementos quedan cubiertos por los roles estándar definidos en Qt::ItemDataRole. Al proporcionar los datos de los elementos adecuados para cada rol, los modelos pueden ofrecer indicaciones a las vistas y a los delegados sobre cómo deben presentarse los elementos al usuario. Los diferentes tipos de vistas tienen libertad para interpretar o ignorar esta información según sea necesario. También es posible definir roles adicionales para fines específicos de la aplicación.

Resumen

  • Los índices de modelo proporcionan a las vistas y a los delegados información sobre la ubicación de los elementos proporcionados por los modelos, de forma independiente de cualquier estructura de datos subyacente.
  • Se hace referencia a los elementos mediante sus números de fila y columna, y mediante el índice del modelo de sus elementos padres.
  • Los índices de modelo son creados por los modelos a petición de otros componentes, como las vistas y los delegados.
  • Si se especifica un índice de modelo válido para el elemento padre al solicitar un índice mediante ` index()``, el índice devuelto hace referencia a un elemento situado debajo de ese elemento padre en el modelo. El índice obtenido hace referencia a un elemento hijo de ese elemento.
  • Si se especifica un índice de modelo no válido para el elemento padre al solicitar un índice mediante ` index()`, el índice devuelto hace referencia a un elemento de nivel superior en el modelo.
  • La función ` role ` distingue entre los diferentes tipos de datos asociados a un elemento.

Uso de índices de modelo

Para mostrar cómo se pueden recuperar datos de un modelo utilizando índices de modelo, creamos un ` QFileSystemModel ` sin vista y mostramos los nombres de los archivos y directorios en un widget. Aunque esto no muestra una forma habitual de utilizar un modelo, ilustra las convenciones que siguen los modelos al manejar índices de modelo.

QFileSystemModel La carga es asíncrona para minimizar el uso de recursos del sistema. Debemos tenerlo en cuenta al trabajar con este modelo.

Construimos un modelo de sistema de archivos de la siguiente manera:

auto *model = new QFileSystemModel;

auto onDirectoryLoaded = [model, layout, &window](const QString &directory) {
    QModelIndex parentIndex = model->index(directory);
    const int numRows = model->rowCount(parentIndex);
    for (int row = 0; row < numRows; ++row) {
        QModelIndex index = model->index(row, 0, parentIndex);

        QString text = model->data(index, Qt::DisplayRole).toString();

        // Display the text in a widget.
        auto *label = new QLabel(text, &window);
        layout->addWidget(label);
    }
};

QObject::connect(model, &QFileSystemModel::directoryLoaded, onDirectoryLoaded);
model->setRootPath(QDir::currentPath());

En este caso, empezamos por configurar un ` QFileSystemModel` por defecto. Conectamos su señal ` directoryLoaded(QString) ` a una función lambda, en la que obtendremos un índice padre para el directorio utilizando una implementación específica de ` index()` proporcionada por ese modelo.

En la función lambda, determinamos el número de filas del modelo utilizando la función ` rowCount()`.

Para simplificar, solo nos interesan los elementos de la primera columna del modelo. Examinamos cada fila por turnos, obteniendo un índice de modelo para el primer elemento de cada fila, y leemos los datos almacenados para ese elemento en el modelo.

for (int row = 0; row < numRows; ++row) {
    QModelIndex index = model->index(row, 0, parentIndex);

Para obtener un índice del modelo, especificamos el número de fila, el número de columna (cero para la primera columna) y el índice del modelo correspondiente al elemento padre de todos los elementos que queremos. El texto almacenado en cada elemento se recupera utilizando la función ` data()` del modelo. Especificamos el índice del modelo y el ` DisplayRole ` para obtener los datos del elemento en forma de cadena.

    QString text = model->data(index, Qt::DisplayRole).toString();

}

Por último, establecemos la ruta raíz de ` QFileSystemModel ` para que comience a cargar datos y active la función Lambda.

El ejemplo anterior ilustra los principios básicos que se utilizan para recuperar datos de un modelo:

  • Las dimensiones de un modelo se pueden obtener mediante rowCount() y columnCount(). Estas funciones suelen requerir que se especifique un índice de modelo padre.
  • Los índices de modelo se utilizan para acceder a los elementos del modelo. Para especificar un elemento se necesitan el índice de fila, el de columna y el índice del modelo padre.
  • Para acceder a los elementos de nivel superior de un modelo, especifique un índice de modelo nulo como índice principal con QModelIndex().
  • Los elementos contienen datos para diferentes roles. Para obtener los datos de un rol concreto, se deben proporcionar al modelo tanto el índice del modelo como el rol.

Más información

Se pueden crear nuevos modelos implementando la interfaz estándar proporcionada por QAbstractItemModel. En la sección «Creación de nuevos modelos», lo demostramos creando un modelo práctico y listo para usar destinado a almacenar listas de cadenas.

Ver clases

Conceptos

En la arquitectura modelo/vista, la vista obtiene elementos de datos del modelo y los presenta al usuario. La forma en que se presentan los datos no tiene por qué parecerse a la representación de los datos proporcionada por el modelo, y puede ser completamente diferente de la estructura de datos subyacente utilizada para almacenar los elementos de datos.

La separación entre contenido y presentación se consigue mediante el uso de una interfaz de modelo estándar proporcionada por QAbstractItemModel, una interfaz de vista estándar proporcionada por QAbstractItemView y el uso de índices de modelo que representan los elementos de datos de forma general. Las vistas suelen gestionar el diseño general de los datos obtenidos de los modelos. Pueden mostrar elementos de datos individuales por sí mismas o utilizar delegados para gestionar tanto las funciones de visualización como las de edición.

Además de presentar datos, las vistas gestionan la navegación entre elementos y algunos aspectos de la selección de elementos. Las vistas también implementan funciones básicas de la interfaz de usuario, como los menús contextuales y la función de arrastrar y soltar. Una vista puede proporcionar funciones de edición predeterminadas para los elementos, o bien puede trabajar con un delegado para proporcionar un editor personalizado.

Una vista puede crearse sin un modelo, pero es necesario proporcionar un modelo antes de que pueda mostrar información útil. Las vistas realizan un seguimiento de los elementos que el usuario ha seleccionado mediante el uso de selecciones que pueden mantenerse por separado para cada vista o compartirse entre varias vistas.

Algunas vistas, como QTableView y QTreeView, muestran encabezados además de elementos. Estos también se implementan mediante una clase de vista, QHeaderView. Los encabezados suelen acceder al mismo modelo que la vista que los contiene. Recuperan datos del modelo mediante la función QAbstractItemModel::headerData(), y suelen mostrar la información del encabezado en forma de etiqueta. Se pueden crear subclases de la clase QHeaderView para proporcionar etiquetas más especializadas a las vistas.

Uso de una vista existente

Qt proporciona tres clases de vista listas para usar que presentan los datos de los modelos de formas que resultan familiares para la mayoría de los usuarios. QListView puede mostrar elementos de un modelo como una lista sencilla o en forma de vista de iconos clásica. QTreeView muestra los elementos de un modelo como una jerarquía de listas, lo que permite representar estructuras profundamente anidadas de forma compacta. QTableView presenta los elementos de un modelo en forma de tabla, muy similar al diseño de una aplicación de hoja de cálculo.

Vista de lista, vista de árbol y vista de tabla

El comportamiento predeterminado de las vistas estándar mostradas anteriormente debería ser suficiente para la mayoría de las aplicaciones. Proporcionan funciones básicas de edición y pueden personalizarse para adaptarse a las necesidades de interfaces de usuario más especializadas.

Uso de un modelo

Tomamos el modelo de lista de cadenas que hemos creado como modelo de ejemplo, lo configuramos con algunos datos y creamos una vista para mostrar el contenido del modelo. Todo esto se puede realizar dentro de una única función:

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

// Unindented for quoting purposes:
QStringList numbers;
numbers << "One" << "Two" << "Three" << "Four" << "Five";

QAbstractItemModel *model = new StringListModel(numbers);

Obsérvese que el modelo « StringListModel » se declara como un « QAbstractItemModel ». Esto nos permite utilizar la interfaz abstracta del modelo y garantiza que el código siga funcionando, incluso si sustituimos el modelo de lista de cadenas por otro modelo diferente.

La vista de lista que proporciona QListView es suficiente para presentar los elementos del modelo de lista de cadenas. Creamos la vista y configuramos el modelo mediante las siguientes líneas de código:

QListView *view = new QListView;
view->setModel(model);

La vista se muestra de la forma habitual:

    view->show();
    return app.exec();
}

La vista representa el contenido de un modelo, accediendo a los datos a través de la interfaz del modelo. Cuando el usuario intenta editar un elemento, la vista utiliza un delegado predeterminado para proporcionar un control de edición.

Lista de textos que utilizan un modelo de lista de cadenas

La imagen anterior muestra cómo un QListView representa los datos del modelo de lista de cadenas. Dado que el modelo es editable, la vista permite automáticamente editar cada elemento de la lista mediante el delegado predeterminado.

Uso de varias vistas de un modelo

Para proporcionar varias vistas de un mismo modelo, basta con establecer el mismo modelo para cada vista. En el siguiente código creamos dos vistas de tabla, cada una de las cuales utiliza el mismo modelo de tabla sencillo que hemos creado para este ejemplo:

QTableView *firstTableView = new QTableView;
QTableView *secondTableView = new QTableView;

firstTableView->setModel(model);
secondTableView->setModel(model);

El uso de señales y ranuras en la arquitectura modelo/vista implica que los cambios en el modelo pueden propagarse a todas las vistas asociadas, lo que garantiza que siempre podamos acceder a los mismos datos independientemente de la vista que se utilice.

Dos vistas de tabla comparten un modelo, pero no comparten el modelo de selección.

La imagen anterior muestra dos vistas diferentes del mismo modelo, cada una de las cuales contiene varios elementos seleccionados. Aunque los datos del modelo se muestran de forma coherente en todas las vistas, cada una de ellas mantiene su propio modelo de selección interno. Esto puede resultar útil en determinadas situaciones, pero, para muchas aplicaciones, es preferible disponer de un modelo de selección compartido.

Gestión de selecciones de elementos

El mecanismo para gestionar las selecciones de elementos dentro de las vistas lo proporciona la clase ` QItemSelectionModel `. Todas las vistas estándar crean sus propios modelos de selección de forma predeterminada e interactúan con ellos de la forma habitual. El modelo de selección que utiliza una vista se puede obtener mediante la función ` selectionModel()`, y se puede especificar un modelo de selección alternativo con ` setSelectionModel()`. La capacidad de controlar el modelo de selección utilizado por una vista resulta útil cuando queremos ofrecer varias vistas coherentes sobre los mismos datos del modelo.

Por lo general, a menos que se esté creando una subclase de un modelo o una vista, no es necesario manipular directamente el contenido de las selecciones. No obstante, se puede acceder a la interfaz del modelo de selección, si es necesario, y esto se explica en «Manejo de selecciones en vistas de elementos».

Compartir selecciones entre vistas

Aunque resulta práctico que las clases de vista proporcionen sus propios modelos de selección por defecto, cuando utilizamos más de una vista sobre el mismo modelo, a menudo es deseable que tanto los datos del modelo como la selección del usuario se muestren de forma coherente en todas las vistas. Dado que las clases de vista permiten sustituir sus modelos de selección internos, podemos lograr una selección unificada entre vistas con la siguiente línea:

secondTableView->setSelectionModel(firstTableView->selectionModel());

A la segunda vista se le asigna el modelo de selección de la primera vista. Ambas vistas operan ahora con el mismo modelo de selección, lo que mantiene sincronizados tanto los datos como los elementos seleccionados.

Dos vistas de tabla con el mismo modelo de selección

En el ejemplo anterior, se utilizaron dos vistas del mismo tipo para mostrar los datos del mismo modelo. Sin embargo, si se utilizaran dos tipos diferentes de vista, los elementos seleccionados podrían representarse de forma muy diferente en cada vista; por ejemplo, una selección contigua en una vista de tabla puede representarse como un conjunto fragmentado de elementos resaltados en una vista de árbol.

Clases delegadas

Conceptos

A diferencia del patrón Modelo-Vista-Controlador, el diseño modelo/vista no incluye un componente completamente independiente para gestionar la interacción con el usuario. Por lo general, la vista se encarga de presentar los datos del modelo al usuario y de procesar las entradas de este. Para permitir cierta flexibilidad en la forma de obtener estas entradas, la interacción la llevan a cabo los delegados. Estos componentes proporcionan capacidades de entrada y también se encargan de representar elementos individuales en algunas vistas. La interfaz estándar para controlar a los delegados se define en la clase ` QAbstractItemDelegate `.

Se espera que los delegados sean capaces de representar su contenido por sí mismos mediante la implementación de las funciones ` paint()` y ` sizeHint()`. Sin embargo, los delegados sencillos basados en widgets pueden heredar de ` QStyledItemDelegate ` en lugar de ` QAbstractItemDelegate` y aprovechar las implementaciones predeterminadas de estas funciones.

Los editores para delegados pueden implementarse utilizando widgets para gestionar el proceso de edición o gestionando los eventos directamente. El primer enfoque se trata más adelante en esta sección.

Uso de un delegado existente

Las vistas estándar que se incluyen con Qt utilizan instancias de ` QStyledItemDelegate ` para proporcionar funciones de edición. Esta implementación predeterminada de la interfaz de delegado representa los elementos con el estilo habitual de cada una de las vistas estándar: ` QListView`, ` QTableView` y ` QTreeView`.

Todas las funciones estándar son gestionadas por el delegado predeterminado utilizado por las vistas estándar. La forma en que se interpretan se describe en la documentación de QStyledItemDelegate.

El delegado utilizado por una vista es devuelto por la función itemDelegate(). La función setItemDelegate() permite instalar un delegado personalizado para una vista estándar, y es necesario utilizar esta función al configurar el delegado para una vista personalizada.

Un delegado sencillo

El delegado que se implementa aquí utiliza un ` QSpinBox ` para proporcionar funciones de edición, y está pensado principalmente para su uso con modelos que muestran números enteros. Aunque hemos configurado un modelo de tabla personalizado basado en números enteros para este fin, podríamos haber utilizado fácilmente ` QStandardItemModel ` en su lugar, ya que el delegado personalizado controla la introducción de datos. Creamos una vista de tabla para mostrar el contenido del modelo, y esta utilizará el delegado personalizado para la edición.

Delegado de cuadro de selección personalizado para la edición

Creamos una subclase del delegado a partir de ` QStyledItemDelegate `, ya que no queremos escribir funciones de visualización personalizadas. Sin embargo, aún debemos proporcionar funciones para gestionar el control de edición:

class SpinBoxDelegate : public QStyledItemDelegate
{
    Q_OBJECT

public:
    SpinBoxDelegate(QObject *parent = nullptr);

    QWidget *createEditor(QWidget *parent, const QStyleOptionViewItem &option,
                          const QModelIndex &index) const override;

    void setEditorData(QWidget *editor, const QModelIndex &index) const override;
    void setModelData(QWidget *editor, QAbstractItemModel *model,
                      const QModelIndex &index) const override;

    void updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem &option,
                              const QModelIndex &index) const override;
};

SpinBoxDelegate::SpinBoxDelegate(QObject *parent)
    : QStyledItemDelegate(parent)
{
}

Ten en cuenta que no se configura ningún control de edición cuando se crea el delegado. Solo creamos un control de edición cuando es necesario.

Proporcionar un editor

En este ejemplo, cuando la vista de tabla necesita proporcionar un editor, solicita al delegado que proporcione un widget de editor adecuado para el elemento que se está modificando. A la función createEditor() se le proporciona todo lo que el delegado necesita para poder configurar un widget adecuado:

QWidget *SpinBoxDelegate::createEditor(QWidget *parent,
                                       const QStyleOptionViewItem &/* option */,
                                       const QModelIndex &/* index */) const
{
    QSpinBox *editor = new QSpinBox(parent);
    editor->setFrame(false);
    editor->setMinimum(0);
    editor->setMaximum(100);

    return editor;
}

Ten en cuenta que no es necesario mantener un puntero al widget de editor, ya que la vista se encarga de destruirlo cuando ya no sea necesario.

Instalamos el filtro de eventos predeterminado del delegado en el editor para garantizar que ofrezca los atajos de edición estándar que esperan los usuarios. Se pueden añadir atajos adicionales al editor para permitir un comportamiento más sofisticado; estos se tratan en la sección sobre «Sugerencias de edición».

La vista garantiza que los datos y la geometría del editor se configuren correctamente llamando a funciones que definiremos más adelante para estos fines. Podemos crear diferentes editores en función del índice del modelo proporcionado por la vista. Por ejemplo, si tenemos una columna de números enteros y una columna de cadenas, podríamos devolver un ` QSpinBox ` o un ` QLineEdit`, dependiendo de qué columna se esté editando.

El delegado debe proporcionar una función para copiar los datos del modelo en el editor. En este ejemplo, leemos los datos almacenados en el ` display role` y establecemos el valor en el cuadro de selección en consecuencia.

void SpinBoxDelegate::setEditorData(QWidget *editor,
                                    const QModelIndex &index) const
{
    int value = index.data(Qt::EditRole).toInt();

    QSpinBox *spinBox = static_cast<QSpinBox*>(editor);
    spinBox->setValue(value);
}

En este ejemplo, sabemos que el control del editor es un cuadro de selección, pero podríamos haber proporcionado diferentes controles de edición para distintos tipos de datos del modelo; en ese caso, tendríamos que convertir el control al tipo adecuado antes de acceder a sus funciones miembro.

Envío de datos al modelo

Cuando el usuario ha terminado de editar el valor en el cuadro de selección, la vista solicita al delegado que almacene el valor editado en el modelo llamando a la función setModelData().

void SpinBoxDelegate::setModelData(QWidget *editor, QAbstractItemModel *model,
                                   const QModelIndex &index) const
{
    QSpinBox *spinBox = static_cast<QSpinBox*>(editor);
    spinBox->interpretText();
    int value = spinBox->value();

    model->setData(index, value, Qt::EditRole);
}

Dado que la vista gestiona los controles del editor para el delegado, solo tenemos que actualizar el modelo con el contenido proporcionado por el editor. En este caso, nos aseguramos de que el cuadro de selección esté actualizado y actualizamos el modelo con el valor que contiene utilizando el índice especificado.

La clase estándar ` QStyledItemDelegate ` informa a la vista de que ha finalizado la edición emitiendo la señal ` closeEditor()`. La vista se asegura de que el widget del editor se cierre y se elimine. En este ejemplo, solo proporcionamos funciones de edición sencillas, por lo que nunca necesitamos emitir esta señal.

Todas las operaciones sobre los datos se realizan a través de la interfaz proporcionada por ` QAbstractItemModel`. Esto hace que el delegado sea prácticamente independiente del tipo de datos que manipula, pero es necesario hacer algunas suposiciones para poder utilizar determinados tipos de widgets de edición. En este ejemplo, hemos supuesto que el modelo siempre contiene valores enteros, pero aún así podemos utilizar este delegado con diferentes tipos de modelos, ya que QVariant proporciona valores por defecto adecuados para los datos inesperados.

Actualización de la geometría del editor

Es responsabilidad del delegado gestionar la geometría del editor. La geometría debe configurarse al crear el editor y cuando se modifica el tamaño o la posición del elemento en la vista. Afortunadamente, la vista proporciona toda la información geométrica necesaria dentro de un objeto ` view option `.

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

En este caso, simplemente utilizamos la información geométrica proporcionada por la opción de vista en el rectángulo del elemento. Un delegado que represente elementos con varios componentes no utilizaría directamente el rectángulo del elemento, sino que situaría el editor en relación con los demás componentes del elemento.

Consejos de edición

Tras la edición, los delegados deben proporcionar indicaciones a los demás componentes sobre el resultado del proceso de edición, así como indicaciones que faciliten cualquier operación de edición posterior. Esto se consigue emitiendo la señal closeEditor() con una indicación adecuada. De ello se encarga el filtro de eventos predeterminado QStyledItemDelegate, que instalamos en el cuadro de selección al crearlo.

El comportamiento del cuadro giratorio podría ajustarse para que resulte más intuitivo para el usuario. En el filtro de eventos predeterminado proporcionado por QStyledItemDelegate, si el usuario pulsa Return para confirmar su elección en el cuadro giratorio, el delegado aplica el valor al modelo y cierra el cuadro giratorio. Podemos modificar este comportamiento instalando nuestro propio filtro de eventos en el cuadro giratorio y proporcionar sugerencias de edición que se adapten a nuestras necesidades; por ejemplo, podríamos emitir closeEditor() con la sugerencia « EditNextItem » para comenzar automáticamente a editar el siguiente elemento de la vista.

Otro enfoque que no requiere el uso de un filtro de eventos consiste en proporcionar nuestro propio widget de editor, tal vez creando una subclase de ` QSpinBox ` para mayor comodidad. Este enfoque alternativo nos daría más control sobre el comportamiento del widget de edición, a costa de tener que escribir código adicional. Por lo general, resulta más sencillo instalar un filtro de eventos en el delegado si necesitas personalizar el comportamiento de un widget de edición estándar de Qt.

Los delegados no tienen por qué emitir estas sugerencias, pero aquellos que no lo hagan estarán menos integrados en las aplicaciones y serán menos útiles que los que emiten sugerencias para dar soporte a acciones de edición comunes.

Gestión de selecciones en vistas de elementos

Conceptos

El modelo de selección utilizado en las clases de vista de elementos ofrece una descripción general de las selecciones basada en las prestaciones de la arquitectura modelo/vista. Aunque las clases estándar para manipular selecciones son suficientes para las vistas de elementos proporcionadas, el modelo de selección permite crear modelos de selección especializados que se adapten a los requisitos de sus propios modelos y vistas de elementos.

La información sobre los elementos seleccionados en una vista se almacena en una instancia de la clase « QItemSelectionModel ». Esta clase mantiene los índices del modelo para los elementos de un único modelo y es independiente de cualquier vista. Dado que puede haber muchas vistas de un mismo modelo, es posible compartir selecciones entre vistas, lo que permite a las aplicaciones mostrar múltiples vistas de forma coherente.

Las selecciones se componen de rangos de selección. Estos mantienen de forma eficiente la información sobre grandes selecciones de elementos, ya que registran únicamente los índices de modelo iniciales y finales para cada rango de elementos seleccionados. Las selecciones de elementos no contiguos se construyen utilizando más de un rango de selección para describir la selección.

Las selecciones se aplican a una colección de índices de modelo que contiene un modelo de selección. La selección de elementos aplicada más recientemente se conoce como la selección actual. Los efectos de esta selección pueden modificarse incluso después de su aplicación mediante el uso de determinados tipos de comandos de selección. Estos se tratan más adelante en esta sección.

Elemento actual y elementos seleccionados

En una vista, siempre hay un elemento actual y un elemento seleccionado: dos estados independientes. Un elemento puede ser el elemento actual y estar seleccionado al mismo tiempo. La vista se encarga de garantizar que siempre haya un elemento actual, ya que, por ejemplo, la navegación mediante el teclado requiere un elemento actual.

La tabla siguiente destaca las diferencias entre el elemento actual y los elementos seleccionados.

Elemento actualElementos seleccionados
Solo puede haber un elemento actual.Puede haber varios elementos seleccionados.
El elemento actual se modificará mediante la navegación con las teclas o al hacer clic con el ratón.El estado de selección de los elementos se activa o desactiva, dependiendo de varios modos predefinidos —por ejemplo, selección única, selección múltiple, etc.— cuando el usuario interactúa con los elementos.
El elemento actual se editará si se pulsa la tecla de edición ( F2) o si se hace doble clic sobre el elemento (siempre que la edición esté habilitada).El elemento actual se puede utilizar junto con un punto de anclaje para especificar un rango que se debe seleccionar o deseleccionar (o una combinación de ambos).
El elemento actual se indica mediante el rectángulo de foco.Los elementos seleccionados se indican mediante el rectángulo de selección.

A la hora de manipular selecciones, suele resultar útil considerar ` QItemSelectionModel ` como un registro del estado de selección de todos los elementos de un modelo de elementos. Una vez configurado un modelo de selección, se pueden seleccionar o deseleccionar conjuntos de elementos, o alternar su estado de selección, sin necesidad de saber qué elementos están ya seleccionados. Los índices de todos los elementos seleccionados pueden recuperarse en cualquier momento, y se puede informar a otros componentes de los cambios en el modelo de selección a través del mecanismo de señales y ranuras.

Uso de un modelo de selección

Las clases de vista estándar proporcionan modelos de selección predeterminados que pueden utilizarse en la mayoría de las aplicaciones. Se puede obtener un modelo de selección perteneciente a una vista mediante la función ` selectionModel()` de dicha vista, y compartirlo entre varias vistas con ` setSelectionModel()`, por lo que, por lo general, no es necesario crear nuevos modelos de selección.

Una selección se crea especificando un modelo y un par de índices del modelo en ` QItemSelection`. Esto utiliza los índices para hacer referencia a los elementos del modelo dado y los interpreta como los elementos de la esquina superior izquierda y de la esquina inferior derecha de un bloque de elementos seleccionados. Para aplicar la selección a los elementos de un modelo, es necesario enviar la selección a un modelo de selección; esto puede lograrse de varias maneras, cada una de las cuales tiene un efecto diferente sobre las selecciones ya presentes en el modelo de selección.

Selección de elementos

Para mostrar algunas de las características principales de las selecciones, creamos una instancia de un modelo de tabla personalizado con un total de 32 elementos y abrimos una vista de tabla con sus datos:

TableModel *model = new TableModel(8, 4, &app);

QTableView *table = new QTableView(0);
table->setModel(model);

QItemSelectionModel *selectionModel = table->selectionModel();

Se recupera el modelo de selección predeterminado de la vista de tabla para su uso posterior. No modificamos ningún elemento del modelo, sino que seleccionamos algunos elementos que la vista mostrará en la esquina superior izquierda de la tabla. Para ello, necesitamos recuperar los índices del modelo correspondientes a los elementos de la esquina superior izquierda y de la esquina inferior derecha de la región que se va a seleccionar:

QModelIndex topLeft;
QModelIndex bottomRight;

topLeft = model->index(0, 0, QModelIndex());
bottomRight = model->index(5, 2, QModelIndex());

Para seleccionar estos elementos en el modelo y ver el cambio correspondiente en la vista de tabla, debemos crear un objeto de selección y, a continuación, aplicarlo al modelo de selección:

QItemSelection selection(topLeft, bottomRight);
selectionModel->select(selection, QItemSelectionModel::Select);

La selección se aplica al modelo de selección mediante un comando definido por una combinación de selection flags. En este caso, los indicadores utilizados hacen que los elementos registrados en el objeto de selección se incluyan en el modelo de selección, independientemente de su estado anterior. La selección resultante se muestra en la vista.

El modelo de selección de un modelo de tabla aparece resaltado en azul

La selección de elementos puede modificarse mediante diversas operaciones definidas por los indicadores de selección. La selección resultante de estas operaciones puede tener una estructura compleja, pero el modelo de selección la representa de forma eficiente. El uso de diferentes indicadores de selección para manipular los elementos seleccionados se describe al examinar cómo actualizar una selección.

Lectura del estado de la selección

Los índices de modelo almacenados en el modelo de selección se pueden leer mediante la función selectedIndexes(). Esta función devuelve una lista sin ordenar de índices de modelo sobre la que podemos iterar siempre que sepamos a qué modelo corresponden:

const QModelIndexList indexes = selectionModel->selectedIndexes();

for (const QModelIndex &index : indexes) {
    QString text = QString("(%1,%2)").arg(index.row()).arg(index.column());
    model->setData(index, text);
}

El código anterior utiliza un bucle «for» basado en rangos para recorrer y modificar los elementos correspondientes a los índices devueltos por el modelo de selección.

El modelo de selección emite señales para indicar cambios en la selección. Estas notifican a otros componentes los cambios tanto en la selección en su conjunto como en el elemento actualmente seleccionado en el modelo de elementos. Podemos conectar la señal « selectionChanged()» a una ranura y examinar los elementos del modelo que se seleccionan o deseleccionan cuando cambia la selección. La ranura se invoca con dos objetos « QItemSelection »: uno contiene una lista de índices que corresponden a los elementos recién seleccionados; el otro contiene índices que corresponden a los elementos recién deseleccionados.

En el código siguiente, definimos un slot que recibe la señal selectionChanged(), rellena los elementos seleccionados con una cadena y borra el contenido de los elementos deseleccionados.

void MainWindow::updateSelection(const QItemSelection &selected,
    const QItemSelection &deselected)
{
    QModelIndexList items = selected.indexes();

    for (const QModelIndex &index : std::as_const(items)) {
        QString text = QString("(%1,%2)").arg(index.row()).arg(index.column());
        model->setData(index, text);
    }

    items = deselected.indexes();

    for (const QModelIndex &index : std::as_const(items)) {
        model->setData(index, QString());
    }
}

Podemos realizar un seguimiento del elemento en el que se encuentra el foco actualmente conectando la señal currentChanged() a una ranura que se invoca con dos índices del modelo. Estos corresponden al elemento en el que se encontraba el foco anteriormente y al elemento en el que se encuentra el foco actualmente.

En el siguiente código, definimos un slot que recibe la señal currentChanged() y utiliza la información proporcionada para actualizar la barra de estado de un QMainWindow:

void MainWindow::changeCurrent(const QModelIndex &current,
    const QModelIndex &previous)
{
    statusBar()->showMessage(
        tr("Moved from (%1,%2) to (%3,%4)")
            .arg(previous.row()).arg(previous.column())
            .arg(current.row()).arg(current.column()));
}

Con estas señales, resulta muy sencillo realizar un seguimiento de las selecciones realizadas por el usuario, pero también podemos actualizar directamente el modelo de selección.

Actualización de una selección

Los comandos de selección se proporcionan mediante una combinación de indicadores de selección, definidos en QItemSelectionModel::SelectionFlag. Cada indicador de selección indica al modelo de selección cómo actualizar su registro interno de elementos seleccionados cuando se llama a cualquiera de las funciones select(). El indicador más utilizado es el de « Select », que indica al modelo de selección que registre los elementos especificados como seleccionados. El indicador « Toggle » hace que el modelo de selección invierta el estado de los elementos especificados, seleccionando los elementos deseleccionados y deseleccionando los que estén seleccionados en ese momento. El indicador « Deselect » deselecciona todos los elementos especificados.

Los elementos individuales del modelo de selección se actualizan creando una selección de elementos y aplicándola al modelo de selección. En el código siguiente, aplicamos una segunda selección de elementos al modelo de tabla mostrado anteriormente, utilizando el comando « Toggle » para invertir el estado de selección de los elementos indicados.

QItemSelection toggleSelection;

topLeft = model->index(2, 1, QModelIndex());
bottomRight = model->index(7, 3, QModelIndex());
toggleSelection.select(topLeft, bottomRight);

selectionModel->select(toggleSelection, QItemSelectionModel::Toggle);

Los resultados de esta operación se muestran en la vista de tabla, lo que ofrece una forma práctica de visualizar lo que hemos conseguido:

El modelo de selección actualizado tiene los colores invertidos

Por defecto, los comandos de selección solo actúan sobre los elementos individuales especificados por los índices del modelo. Sin embargo, el indicador utilizado para describir el comando de selección se puede combinar con indicadores adicionales para modificar filas y columnas completas. Por ejemplo, si se llama a ` select()` con un solo índice, pero con un comando que sea una combinación de ` Select ` y ` Rows`, se seleccionará toda la fila que contenga el elemento al que se hace referencia. El siguiente código muestra el uso de los indicadores ` Rows ` y ` Columns `:

QItemSelection columnSelection;

topLeft = model->index(0, 1, QModelIndex());
bottomRight = model->index(0, 2, QModelIndex());

columnSelection.select(topLeft, bottomRight);

selectionModel->select(columnSelection,
    QItemSelectionModel::Select | QItemSelectionModel::Columns);

QItemSelection rowSelection;

topLeft = model->index(0, 0, QModelIndex());
bottomRight = model->index(1, 0, QModelIndex());

rowSelection.select(topLeft, bottomRight);

selectionModel->select(rowSelection,
    QItemSelectionModel::Select | QItemSelectionModel::Rows);

Aunque solo se proporcionan cuatro índices al modelo de selección, el uso de los indicadores de selección « Columns » y « Rows » hace que se seleccionen dos columnas y dos filas. La siguiente imagen muestra el resultado de estas dos selecciones:

Actualización de columnas o filas completas en el modelo de selección

Todos los comandos ejecutados en el modelo de ejemplo han consistido en acumular una selección de elementos en el modelo. También es posible borrar la selección o sustituir la selección actual por una nueva.

Para sustituir la selección actual por una nueva, combina los demás indicadores de selección con el indicador Current. Un comando que utilice este indicador ordena al modelo de selección que sustituya su conjunto actual de índices del modelo por los especificados en una llamada a ` select()`. Para borrar todas las selecciones antes de empezar a añadir otras nuevas, combina los demás indicadores de selección con el indicador ` Clear `. Esto tiene como efecto restablecer el conjunto de índices del modelo del modelo de selección.

Seleccionar todos los elementos de un modelo

Para seleccionar todos los elementos de un modelo, es necesario crear una selección para cada nivel del modelo que abarque todos los elementos de ese nivel. Para ello, recuperamos los índices correspondientes a los elementos de la esquina superior izquierda y de la esquina inferior derecha con un índice padre determinado:

QModelIndex topLeft = model->index(0, 0, parent);
QModelIndex bottomRight = model->index(model->rowCount(parent)-1,
    model->columnCount(parent)-1, parent);

Se construye una selección con estos índices y el modelo. A continuación, se seleccionan los elementos correspondientes en el modelo de selección:

QItemSelection selection(topLeft, bottomRight);
selectionModel->select(selection, QItemSelectionModel::Select);

Esto debe realizarse para todos los niveles del modelo. En el caso de los elementos de nivel superior, definiríamos el índice padre de la forma habitual:

En los modelos jerárquicos, se utiliza la función hasChildren() para determinar si un elemento dado es el padre de otro nivel de elementos.

Creación de nuevos modelos

La separación de funcionalidades entre los componentes de modelo y vista permite crear modelos que puedan aprovechar las vistas existentes. Este enfoque nos permite presentar datos procedentes de diversas fuentes utilizando componentes estándar de la interfaz gráfica de usuario, como QListView, QTableView y QTreeView.

La clase QAbstractItemModel proporciona una interfaz lo suficientemente flexible como para admitir fuentes de datos que organizan la información en estructuras jerárquicas, lo que permite insertar, eliminar, modificar u ordenar los datos de alguna forma. También admite operaciones de arrastrar y soltar.

Las clases ` QAbstractListModel ` y ` QAbstractTableModel ` ofrecen compatibilidad con interfaces para estructuras de datos no jerárquicas más sencillas, y resultan más fáciles de utilizar como punto de partida para modelos sencillos de listas y tablas.

En esta sección, crearemos un modelo sencillo de solo lectura para explorar los principios básicos de la arquitectura modelo/vista. Más adelante en esta sección, adaptaremos este modelo sencillo para que el usuario pueda modificar los elementos.

Para ver un ejemplo de un modelo más complejo, consulta el ejemplo «Modelo de árbol sencillo ».

Los requisitos para subclasific QAbstractItemModel s se describen con más detalle en el documento «Referencia sobre subclasificación de modelos ».

Diseño de un modelo

Al crear un nuevo modelo para una estructura de datos existente, es importante tener en cuenta qué tipo de modelo se debe utilizar para proporcionar una interfaz sobre los datos. Si los datos ya se encuentran en un contenedor de C++ o en cualquier tipo que modele un rango iterable de C++, ` QRangeModel ` puede proporcionar un modelo adecuado sin necesidad de crear subclases, siempre que se admitan el rango de entrada y el tipo de sus elementos.

Si no se puede aplicar un modelo ya creado y la estructura de datos se puede representar como una lista o una tabla de elementos, se puede crear una subclase de ` QAbstractListModel ` o ` QAbstractTableModel `, ya que estas clases proporcionan implementaciones por defecto adecuadas para muchas funciones.

Sin embargo, si la estructura de datos subyacente solo puede representarse mediante una estructura jerárquica en forma de árbol, es necesario crear una subclase de ` QAbstractItemModel`. Este enfoque se adopta en el ejemplo «Modelo de árbol simple ».

En esta sección, implementamos un modelo sencillo basado en una lista de cadenas, por lo que ` QAbstractListModel ` proporciona una clase base ideal sobre la que construir.

Sea cual sea la forma que adopte la estructura de datos subyacente, suele ser una buena idea complementar la API estándar de ` QAbstractItemModel ` en modelos especializados con otra que permita un acceso más natural a dicha estructura. Esto facilita el rellenado del modelo con datos, al tiempo que permite que otros componentes generales de modelo/vista interactúen con él utilizando la API estándar. El modelo que se describe a continuación proporciona un constructor personalizado precisamente con este fin.

Un modelo de ejemplo de solo lectura

El modelo que se implementa aquí es un modelo de datos sencillo, no jerárquico y de solo lectura basado en la clase estándar ` QStringListModel `. Cuenta con un ` QStringList ` como fuente de datos interna e implementa únicamente lo necesario para que el modelo funcione. Para facilitar la implementación, creamos una subclase de ` QAbstractListModel `, ya que define un comportamiento predeterminado adecuado para los modelos de lista y expone una interfaz más sencilla que la clase ` QAbstractItemModel `.

A la hora de implementar un modelo, es importante recordar que QAbstractItemModel no almacena ningún dato por sí misma, sino que simplemente presenta una interfaz que las vistas utilizan para acceder a los datos. Para un modelo mínimo de solo lectura, solo es necesario implementar unas pocas funciones, ya que existen implementaciones por defecto para la mayor parte de la interfaz. La declaración de la clase es la siguiente:

class StringListModel : public QAbstractListModel
{
    Q_OBJECT

public:
    StringListModel(const QStringList &strings, QObject *parent = nullptr)
        : QAbstractListModel(parent), stringList(strings) {}

    int rowCount(const QModelIndex &parent = QModelIndex()) const override;
    QVariant data(const QModelIndex &index, int role) const override;
    QVariant headerData(int section, Qt::Orientation orientation,
                        int role = Qt::DisplayRole) const override;

private:
    QStringList stringList;
};

Aparte del constructor del modelo, solo necesitamos implementar dos funciones: ` rowCount()` devuelve el número de filas del modelo y ` data()` devuelve un elemento de datos correspondiente a un índice especificado del modelo.

Los modelos bien diseñados también implementan headerData() para proporcionar a las vistas de árbol y tabla información que mostrar en sus encabezados.

Ten en cuenta que se trata de un modelo no jerárquico, por lo que no tenemos que preocuparnos por las relaciones padre-hijo. Si nuestro modelo fuera jerárquico, también tendríamos que implementar las funciones ` index()` y ` parent()`.

La lista de cadenas se almacena internamente en la variable miembro privada ` stringList `.

Dimensiones del modelo

Queremos que el número de filas del modelo sea igual al número de cadenas de la lista de cadenas. Implementamos la función ` rowCount()` teniendo esto en cuenta:

int StringListModel::rowCount(const QModelIndex &parent) const
{
    return stringList.count();
}

Dado que el modelo no es jerárquico, podemos ignorar sin problema el índice del modelo correspondiente al elemento padre. Por defecto, los modelos derivados de ` QAbstractListModel ` solo contienen una columna, por lo que no es necesario reimplementar la función ` columnCount()`.

Encabezados y datos del modelo

Para los elementos de la vista, queremos devolver las cadenas de la lista de cadenas. La función data() se encarga de devolver el elemento de datos que corresponde al argumento índice:

QVariant StringListModel::data(const QModelIndex &index, int role) const
{
    if (!index.isValid())
        return QVariant();

    if (index.row() >= stringList.size())
        return QVariant();

    if (role == Qt::DisplayRole)
        return stringList.at(index.row());
    else
        return QVariant();
}

Solo devolvemos un objeto ` QVariant ` válido si el índice del modelo proporcionado es válido, el número de fila está dentro del rango de elementos de la lista de cadenas y el rol solicitado es uno de los que admitimos.

Algunas vistas, como QTreeView y QTableView, pueden mostrar encabezados junto con los datos de los elementos. Si nuestro modelo se muestra en una vista con encabezados, queremos que estos muestren los números de fila y columna. Podemos proporcionar información sobre los encabezados creando una subclase de la función headerData():

QVariant StringListModel::headerData(int section, Qt::Orientation orientation,
                                     int role) const
{
    if (role != Qt::DisplayRole)
        return QVariant();

    if (orientation == Qt::Horizontal)
        return QStringLiteral("Column %1").arg(section);
    else
        return QStringLiteral("Row %1").arg(section);
}

Una vez más, solo devolvemos un ` QVariant ` válido si el rol es uno de los que admitimos. La orientación del encabezado también se tiene en cuenta a la hora de decidir los datos exactos que se van a devolver.

No todas las vistas muestran encabezados con los datos de los elementos, y aquellas que sí lo hacen pueden estar configuradas para ocultarlos. No obstante, se recomienda implementar la función headerData() para proporcionar información relevante sobre los datos proporcionados por el modelo.

Un elemento puede tener varias funciones, lo que permite ofrecer datos diferentes en función de la función especificada. Los elementos de nuestro modelo solo tienen una función, DisplayRole, por lo que devolvemos los datos de los elementos independientemente de la función especificada. Sin embargo, podríamos reutilizar los datos que proporcionamos para DisplayRole en otras funciones, como ToolTipRole, que las vistas pueden utilizar para mostrar información sobre los elementos en una información sobre herramientas.

Un modelo editable

El modelo de solo lectura muestra cómo se podrían presentar opciones sencillas al usuario, pero, para muchas aplicaciones, un modelo de lista editable resulta mucho más útil. Podemos modificar el modelo de solo lectura para que los elementos sean editables cambiando la función data() que implementamos para el modo de solo lectura e implementando dos funciones adicionales: flags() y setData(). Se añaden las siguientes declaraciones de función a la definición de la clase:

    Qt::ItemFlags flags(const QModelIndex &index) const override;
    bool setData(const QModelIndex &index, const QVariant &value,
                 int role = Qt::EditRole) override;

Hacer que el modelo sea editable

Un delegado comprueba si un elemento es editable antes de crear un editor. El modelo debe indicar al delegado que sus elementos son editables. Para ello, devolvemos los indicadores correctos para cada elemento del modelo; en este caso, habilitamos todos los elementos y los hacemos tanto seleccionables como editables:

Qt::ItemFlags StringListModel::flags(const QModelIndex &index) const
{
    if (!index.isValid())
        return Qt::ItemIsEnabled;

    return QAbstractItemModel::flags(index) | Qt::ItemIsEditable;
}

Tenga en cuenta que no es necesario que sepamos cómo lleva a cabo el delegado el proceso de edición propiamente dicho. Solo tenemos que proporcionar al delegado una forma de establecer los datos en el modelo. Esto se consigue mediante la función ` setData()`:

bool StringListModel::setData(const QModelIndex &index,
                              const QVariant &value, int role)
{
    if (index.isValid() && role == Qt::EditRole) {

        stringList.replace(index.row(), value.toString());
        emit dataChanged(index, index, {role});
        return true;
    }
    return false;
}

En este modelo, el elemento de la lista de cadenas que se corresponde con el índice del modelo se sustituye por el valor proporcionado. Sin embargo, antes de poder modificar la lista de cadenas, debemos asegurarnos de que el índice sea válido, de que el elemento sea del tipo correcto y de que el rol sea compatible. Por convención, insistimos en que el rol sea « EditRole », ya que es el que utiliza el delegado de elemento estándar. Sin embargo, para los valores booleanos, se puede utilizar « Qt::CheckStateRole » y establecer el indicador « Qt::ItemIsUserCheckable »; en ese caso, se utiliza una casilla de selección para editar el valor. Los datos subyacentes en este modelo son los mismos para todas las funciones, por lo que este detalle simplemente facilita la integración del modelo con los componentes estándar.

Una vez establecidos los datos, el modelo debe notificar a las vistas que algunos datos han cambiado. Esto se hace emitiendo la señal dataChanged(). Dado que solo ha cambiado un dato, el rango de elementos especificado en la señal se limita a un único índice del modelo.

Además, es necesario modificar la función data() para añadir la comprobación de « Qt::EditRole »:

QVariant StringListModel::data(const QModelIndex &index, int role) const
{
    if (!index.isValid())
        return QVariant();

    if (index.row() >= stringList.size())
        return QVariant();

    if (role == Qt::DisplayRole || role == Qt::EditRole)
        return stringList.at(index.row());
    else
        return QVariant();
}

Insertar y eliminar filas

Es posible modificar el número de filas y columnas de un modelo. En el modelo de lista de cadenas solo tiene sentido cambiar el número de filas, por lo que solo reimplementamos las funciones para insertar y eliminar filas. Estas se declaran en la definición de la clase:

    bool insertRows(int position, int rows, const QModelIndex &index = QModelIndex()) override;
    bool removeRows(int position, int rows, const QModelIndex &index = QModelIndex()) override;

Dado que las filas de este modelo corresponden a cadenas de una lista, la función ` insertRows() ` inserta un número de cadenas vacías en la lista de cadenas antes de la posición especificada. El número de cadenas insertadas es equivalente al número de filas especificado.

El índice padre se utiliza normalmente para determinar en qué parte del modelo deben añadirse las filas. En este caso, solo tenemos una única lista de cadenas de nivel superior, por lo que simplemente insertamos cadenas vacías en esa lista.

bool StringListModel::insertRows(int position, int rows, const QModelIndex &parent)
{
    beginInsertRows(QModelIndex(), position, position+rows-1);

    for (int row = 0; row < rows; ++row) {
        stringList.insert(position, "");
    }

    endInsertRows();
    return true;
}

El modelo llama primero a la función beginInsertRows() para informar a otros componentes de que el número de filas está a punto de cambiar. La función especifica los números de fila de la primera y la última de las nuevas filas que se van a insertar, así como el índice del modelo correspondiente a su elemento padre. Tras modificar la lista de cadenas, llama a endInsertRows() para completar la operación e informar a otros componentes de que las dimensiones del modelo han cambiado, devolviendo «true» para indicar que la operación se ha realizado con éxito.

La función para eliminar filas del modelo también es sencilla de escribir. Las filas que se van a eliminar del modelo se especifican mediante la posición y el número de filas indicados. Ignoramos el índice del elemento padre para simplificar nuestra implementación y simplemente eliminamos los elementos correspondientes de la lista de cadenas.

bool StringListModel::removeRows(int position, int rows, const QModelIndex &parent)
{
    beginRemoveRows(QModelIndex(), position, position+rows-1);

    for (int row = 0; row < rows; ++row) {
        stringList.removeAt(position);
    }

    endRemoveRows();
    return true;
}

La función ` beginRemoveRows()` siempre se llama antes de que se eliminen los datos subyacentes y especifica la primera y la última fila que se van a eliminar. Esto permite que otros componentes accedan a los datos antes de que dejen de estar disponibles. Una vez eliminadas las filas, el modelo emite ` endRemoveRows()` para finalizar la operación y notificar a otros componentes que las dimensiones del modelo han cambiado.

Próximos pasos

Podemos mostrar los datos proporcionados por este modelo, o por cualquier otro, utilizando la clase ` QListView ` para presentar los elementos del modelo en forma de lista vertical. En el caso del modelo de lista de cadenas, esta vista también proporciona un editor predeterminado que permite manipular los elementos. En «Clases de vista» examinamos las posibilidades que ofrecen las clases de vista estándar.

El documento «Referencia sobre la subclasificación de modelos» analiza con más detalle los requisitos de las subclases de ` QAbstractItemModel ` y ofrece una guía sobre las funciones virtuales que deben implementarse para habilitar diversas características en diferentes tipos de modelos.

Clases de conveniencia de la vista de elementos

Los widgets basados en elementos tienen nombres que reflejan sus usos: ` QListWidget ` proporciona una lista de elementos, ` QTreeWidget ` muestra una estructura de árbol de varios niveles y ` QTableWidget ` proporciona una tabla de elementos de celda. Cada clase hereda el comportamiento de la clase ` QAbstractItemView `, que implementa el comportamiento común para la selección de elementos y la gestión de encabezados.

Widgets de lista

Las listas de elementos de un solo nivel suelen mostrarse utilizando un QListWidget y varios QListWidgetItem. Un widget de lista se construye de la misma forma que cualquier otro widget:

QListWidget *listWidget = new QListWidget(this);

Los elementos de la lista se pueden añadir directamente al widget de lista al crearlo:

new QListWidgetItem(tr("Sycamore"), listWidget);
new QListWidgetItem(tr("Chestnut"), listWidget);
new QListWidgetItem(tr("Mahogany"), listWidget);

También se pueden crear sin un widget de lista padre y añadirse a una lista más adelante:

QListWidgetItem *newItem = new QListWidgetItem;
newItem->setText(itemText);
listWidget->insertItem(row, newItem);

Cada elemento de una lista puede mostrar una etiqueta de texto y un icono. Los colores y la fuente utilizados para representar el texto pueden modificarse para personalizar el aspecto de los elementos. Las descripciones emergentes, las indicaciones de estado y la ayuda «¿Qué es esto?» se configuran fácilmente para garantizar que la lista se integre correctamente en la aplicación.

newItem->setToolTip(toolTipText);
newItem->setStatusTip(toolTipText);
newItem->setWhatsThis(whatsThisText);

Por defecto, los elementos de una lista se muestran en el orden en que se crearon. Las listas de elementos se pueden ordenar según los criterios indicados en Qt::SortOrder para generar una lista de elementos ordenada en orden alfabético ascendente o descendente:

listWidget->sortItems(Qt::AscendingOrder);
listWidget->sortItems(Qt::DescendingOrder);

Widgets de árbol

Las clases ` QTreeWidget ` y ` QTreeWidgetItem ` permiten crear árboles o listas jerárquicas de elementos. Cada elemento del widget de árbol puede tener a su vez elementos secundarios y mostrar varias columnas de información. Los widgets de árbol se crean igual que cualquier otro widget:

QTreeWidget *treeWidget = new QTreeWidget(this);

Antes de poder añadir elementos al widget de árbol, hay que establecer el número de columnas. Por ejemplo, podríamos definir dos columnas y crear un encabezado para incluir etiquetas en la parte superior de cada columna:

treeWidget->setColumnCount(2);
QStringList headers;
headers << tr("Subject") << tr("Default");
treeWidget->setHeaderLabels(headers);

La forma más sencilla de configurar las etiquetas de cada sección es proporcionar una lista de cadenas. Para encabezados más sofisticados, puedes crear un elemento de árbol, decorarlo como desees y utilizarlo como encabezado del widget de árbol.

Los elementos de nivel superior del widget de árbol se construyen teniendo al propio widget de árbol como widget padre. Se pueden insertar en un orden arbitrario, o bien puedes asegurarte de que aparezcan en un orden concreto especificando el elemento anterior al construir cada elemento:

QTreeWidgetItem *cities = new QTreeWidgetItem(treeWidget);
cities->setText(0, tr("Cities"));
QTreeWidgetItem *osloItem = new QTreeWidgetItem(cities);
osloItem->setText(0, tr("Oslo"));
osloItem->setText(1, tr("Yes"));

QTreeWidgetItem *planets = new QTreeWidgetItem(treeWidget, cities);

Los widgets de árbol tratan los elementos de nivel superior de forma ligeramente diferente a los demás elementos situados en niveles más profundos del árbol. Los elementos se pueden eliminar del nivel superior del árbol llamando a la función ` takeTopLevelItem()` del widget de árbol, pero los elementos de los niveles inferiores se eliminan llamando a la función ` takeChild()` de su elemento padre. Los elementos se insertan en el nivel superior del árbol mediante la función insertTopLevelItem(). En los niveles inferiores del árbol, se utiliza la función insertChild() del elemento padre.

Es fácil mover elementos entre el nivel superior y los niveles inferiores del árbol. Solo tenemos que comprobar si los elementos son de nivel superior o no, y esta información la proporciona la función parent() de cada elemento. Por ejemplo, podemos eliminar el elemento actual del widget de árbol independientemente de su ubicación:

QTreeWidgetItem *parent = currentItem->parent();
int index;

if (parent) {
    index = parent->indexOfChild(treeWidget->currentItem());
    delete parent->takeChild(index);
} else {
    index = treeWidget->indexOfTopLevelItem(treeWidget->currentItem());
    delete treeWidget->takeTopLevelItem(index);
}

Insertar el elemento en cualquier otro lugar del widget de árbol sigue el mismo patrón:

QTreeWidgetItem *parent = currentItem->parent();
QTreeWidgetItem *newItem;
if (parent)
    newItem = new QTreeWidgetItem(parent, treeWidget->currentItem());
else
    newItem = new QTreeWidgetItem(treeWidget, treeWidget->currentItem());

Widgets de tabla

Las tablas de elementos, similares a las que se encuentran en las aplicaciones de hojas de cálculo, se construyen con las funciones ` QTableWidget ` y ` QTableWidgetItem`. Estas proporcionan un widget de tabla con desplazamiento, encabezados y elementos para utilizar en su interior.

Las tablas pueden crearse con un número fijo de filas y columnas, o bien estas pueden añadirse a una tabla sin tamaño fijo según sea necesario.

QTableWidget *tableWidget;
tableWidget = new QTableWidget(12, 3, this);

Los elementos se crean fuera de la tabla antes de añadirlos a la tabla en la ubicación deseada:

QTableWidgetItem *newItem = new QTableWidgetItem(tr("%1").arg(
    pow(row, column+1)));
tableWidget->setItem(row, column, newItem);

Se pueden añadir encabezados horizontales y verticales a la tabla creando elementos fuera de ella y utilizándolos como encabezados:

QTableWidgetItem *valuesHeaderItem = new QTableWidgetItem(tr("Values"));
tableWidget->setHorizontalHeaderItem(0, valuesHeaderItem);

Ten en cuenta que las filas y columnas de la tabla comienzan en cero.

Características comunes

Existen varias características basadas en elementos que son comunes a todas las clases de utilidades y que están disponibles a través de las mismas interfaces en cada clase. Las presentamos en las siguientes secciones con algunos ejemplos para diferentes widgets. Consulta la lista de clases de modelo/vista de cada uno de los widgets para obtener más detalles sobre el uso de cada función.

Elementos ocultos

A veces resulta útil poder ocultar elementos en un widget de vista de elementos en lugar de eliminarlos. Los elementos de todos los widgets mencionados anteriormente se pueden ocultar y volver a mostrar más adelante. Se puede determinar si un elemento está oculto llamando a la función `isItemHidden()`, y los elementos se pueden ocultar con ` setItemHidden()`.

Dado que esta operación se realiza elemento por elemento, la misma función está disponible para las tres clases de conveniencia.

Selecciones

La forma en que se seleccionan los elementos viene determinada por el modo de selección del widget (QAbstractItemView::SelectionMode). Esta propiedad controla si el usuario puede seleccionar uno o varios elementos y, en el caso de selecciones de varios elementos, si la selección debe ser un rango continuo de elementos. El modo de selección funciona de la misma manera para todos los widgets mencionados anteriormente.

Seleccionar un único elemento

Selecciones de un solo elemento: cuando el usuario necesita elegir un único elemento de un widget, el modo predeterminado de « SingleSelection » es el más adecuado. En este modo, el elemento actual y el elemento seleccionado son el mismo.

Seleccionar varios elementos

Selecciones de varios elementos: en este modo, el usuario puede alternar el estado de selección de cualquier elemento del widget sin modificar la selección existente, de forma muy similar a como se pueden activar o desactivar de forma independiente las casillas de selección no exclusivas.

Selección de elementos contiguos y adyacentes

Selecciones extendidas: Los widgets que a menudo requieren la selección de muchos elementos adyacentes, como los que se encuentran en las hojas de cálculo, necesitan el modo « ExtendedSelection ». En este modo, se pueden seleccionar rangos continuos de elementos del widget tanto con el ratón como con el teclado. También se pueden crear selecciones complejas, que incluyan muchos elementos que no sean adyacentes a otros elementos seleccionados en el widget, si se utilizan teclas modificadoras.

Si el usuario selecciona un elemento sin utilizar una tecla modificadora, se borra la selección existente.

Los elementos seleccionados en un widget se leen mediante la función ` selectedItems() `, que proporciona una lista de elementos relevantes sobre los que se puede iterar. Por ejemplo, podemos calcular la suma de todos los valores numéricos de una lista de elementos seleccionados con el siguiente código:

const QList<QTableWidgetItem *> selected = tableWidget->selectedItems();
int number = 0;
double total = 0;

for (QTableWidgetItem *item : selected) {
    bool ok;
    double value = item->text().toDouble(&ok);

    if (ok && !item->text().isEmpty()) {
        total += value;
        number++;
    }
}

Ten en cuenta que, en el modo de selección única, el elemento actual formará parte de la selección. En los modos de selección múltiple y de selección ampliada, es posible que el elemento actual no se encuentre dentro de la selección, dependiendo de cómo haya realizado el usuario la selección.

Búsqueda

A menudo resulta útil poder buscar elementos dentro de un widget de vista de elementos, ya sea como desarrollador o como servicio que se ofrece a los usuarios. Las tres clases de conveniencia de vista de elementos proporcionan una función común ` findItems() ` para que esto resulte lo más coherente y sencillo posible.

Los elementos se buscan por el texto que contienen, según los criterios especificados mediante una selección de valores de ` Qt::MatchFlags`. Podemos obtener una lista de elementos coincidentes con la función ` findItems() `:

const QList<QTreeWidgetItem *> found = treeWidget->findItems(
    itemText, Qt::MatchWildcard);

for (QTreeWidgetItem *item : found) {
    item->setSelected(true);
    // Show the item->text(0) for each item.
}

El código anterior hace que se seleccionen los elementos de un widget de árbol si contienen el texto indicado en la cadena de búsqueda. Este patrón también se puede utilizar en los widgets de lista y tabla.

Uso de la función de arrastrar y soltar con vistas de elementos

La infraestructura de arrastrar y soltar de Qt es totalmente compatible con el marco de trabajo modelo/vista. Los elementos de las listas, tablas y árboles se pueden arrastrar dentro de las vistas, y los datos se pueden importar y exportar como datos codificados en MIME.

Las vistas estándar admiten automáticamente la función de arrastrar y soltar interna, mediante la cual se mueven los elementos para cambiar el orden en que se muestran. Por defecto, la función de arrastrar y soltar no está habilitada para estas vistas, ya que están configuradas para los usos más sencillos y habituales. Para permitir que los elementos se arrastren, es necesario habilitar determinadas propiedades de la vista, y los propios elementos también deben permitir que se produzca el arrastre.

Los requisitos para un modelo que solo permite exportar elementos desde una vista, y que no permite soltar datos en ella, son menores que los de un modelo con la función de arrastrar y soltar totalmente habilitada.

Consulte también la Referencia sobre subclasificación de modelos para obtener más información sobre cómo habilitar la compatibilidad con la función de arrastrar y soltar en nuevos modelos.

Uso de vistas de conveniencia

Cada uno de los tipos de elementos utilizados con QListWidget, QTableWidget y QTreeWidget está configurado para utilizar un conjunto diferente de indicadores por defecto. Por ejemplo, cada QListWidgetItem o QTreeWidgetItem está inicialmente habilitado, se puede marcar, se puede seleccionar y puede utilizarse como origen de una operación de arrastrar y soltar; cada QTableWidgetItem también se puede editar y utilizarse como destino de una operación de arrastrar y soltar.

Aunque todos los elementos estándar tienen uno o ambos indicadores activados para la función de arrastrar y soltar, por lo general es necesario configurar varias propiedades en la propia vista para aprovechar la compatibilidad integrada con esta función:

  • Para habilitar el arrastre de elementos, establece la propiedad « dragEnabled » de la vista en « true ».
  • Para permitir que el usuario suelte elementos internos o externos dentro de la vista, establezca la propiedad ` viewport()` de la vista en ` acceptDrops ` y en ` true`.
  • Para mostrar al usuario dónde se colocará el elemento que se está arrastrando en ese momento si se suelta, configura la propiedad showDropIndicator de la vista. Esto proporciona al usuario información que se actualiza continuamente sobre la ubicación del elemento dentro de la vista.

Por ejemplo, podemos habilitar la función de arrastrar y soltar en un widget de lista con las siguientes líneas de código:

QListWidget *listWidget = new QListWidget(this);
listWidget->setSelectionMode(QAbstractItemView::SingleSelection);
listWidget->setDragEnabled(true);
listWidget->viewport()->setAcceptDrops(true);
listWidget->setDropIndicatorShown(true);

El resultado es un widget de lista que permite copiar los elementos dentro de la vista e incluso permite al usuario arrastrar elementos entre vistas que contengan el mismo tipo de datos. En ambos casos, los elementos se copian en lugar de moverse.

Para que el usuario pueda mover los elementos dentro de la vista, debemos configurar la propiedad ` dragDropMode` del widget de lista:

listWidget->setDragDropMode(QAbstractItemView::InternalMove);

Uso de clases de modelo y vista

La configuración de una vista para arrastrar y soltar sigue el mismo patrón que se utiliza con las vistas de conveniencia. Por ejemplo, se puede configurar un ` QListView ` de la misma manera que un ` QListWidget`:

QListView *listView = new QListView(this);
listView->setSelectionMode(QAbstractItemView::ExtendedSelection);
listView->setDragEnabled(true);
listView->setAcceptDrops(true);
listView->setDropIndicatorShown(true);

Dado que el acceso a los datos mostrados por la vista está controlado por un modelo, el modelo utilizado también debe proporcionar soporte para las operaciones de arrastrar y soltar. Las acciones admitidas por un modelo se pueden especificar reimplementando la función ` QAbstractItemModel::supportedDropActions()`. Por ejemplo, las operaciones de copiar y mover se habilitan con el siguiente código:

Qt::DropActions DragDropListModel::supportedDropActions() const
{
    return Qt::CopyAction | Qt::MoveAction;
}

Aunque se puede especificar cualquier combinación de valores de ` Qt::DropActions `, el modelo debe estar escrito de forma que las admita. Por ejemplo, para permitir que ` Qt::MoveAction ` se utilice correctamente con un modelo de lista, el modelo debe proporcionar una implementación de ` QAbstractItemModel::removeRows()`, ya sea directamente o heredando la implementación de su clase base.

Habilitar la función de arrastrar y soltar para los elementos

Los modelos indican a las vistas qué elementos se pueden arrastrar y cuáles admiten su colocación, reimplementando la función QAbstractItemModel::flags() para proporcionar los indicadores adecuados.

Por ejemplo, un modelo que proporcione una lista sencilla basada en ` QAbstractListModel ` puede habilitar la función de arrastrar y soltar para cada uno de los elementos asegurándose de que los indicadores devueltos contengan los valores ` Qt::ItemIsDragEnabled ` y ` Qt::ItemIsDropEnabled `:

Qt::ItemFlags DragDropListModel::flags(const QModelIndex &index) const
{
    Qt::ItemFlags defaultFlags = QStringListModel::flags(index);

    if (index.isValid())
        return Qt::ItemIsDragEnabled | Qt::ItemIsDropEnabled | defaultFlags;
    else
        return Qt::ItemIsDropEnabled | defaultFlags;
}

Tenga en cuenta que los elementos se pueden soltar en el nivel superior del modelo, pero la función de arrastrar y soltar solo está habilitada para los elementos válidos.

En el código anterior, dado que el modelo deriva de QStringListModel, obtenemos un conjunto predeterminado de indicadores llamando a su implementación de la función flags().

Codificación de los datos exportados

Cuando se exportan elementos de datos desde un modelo mediante una operación de arrastrar y soltar, estos se codifican en un formato adecuado correspondiente a uno o varios tipos MIME. Los modelos declaran los tipos MIME que pueden utilizar para proporcionar elementos reimplementando la función ` QAbstractItemModel::mimeTypes()`, que devuelve una lista de tipos MIME estándar.

Por ejemplo, un modelo que solo proporcione texto sin formato ofrecería la siguiente implementación:

QStringList DragDropListModel::mimeTypes() const
{
    QStringList types;
    types << "application/vnd.text.list";
    return types;
}

El modelo también debe proporcionar código para codificar los datos en el formato anunciado. Esto se consigue reimplementando la función QAbstractItemModel::mimeData() para proporcionar un objeto QMimeData, al igual que en cualquier otra operación de arrastrar y soltar.

El siguiente código muestra cómo cada elemento de datos, correspondiente a una lista dada de índices, se codifica como texto sin formato y se almacena en un objeto ` QMimeData `.

QMimeData *DragDropListModel::mimeData(const QModelIndexList &indexes) const
{
    QMimeData *mimeData = new QMimeData;
    QByteArray encodedData;

    QDataStream stream(&encodedData, QIODevice::WriteOnly);

    for (const QModelIndex &index : indexes) {
        if (index.isValid()) {
            QString text = data(index, Qt::DisplayRole).toString();
            stream << text;
        }
    }

    mimeData->setData("application/vnd.text.list", encodedData);
    return mimeData;
}

Dado que se proporciona a la función una lista de índices del modelo, este enfoque es lo suficientemente general como para utilizarse tanto en modelos jerárquicos como no jerárquicos.

Ten en cuenta que los tipos de datos personalizados deben declararse como meta objects y que deben implementarse operadores de flujo para ellos. Consulta la descripción de la clase QMetaObject para obtener más detalles.

Inserción de datos descartados en un modelo

La forma en que un modelo concreto gestiona los datos eliminados depende tanto de su tipo (lista, tabla o árbol) como de la forma en que es probable que se presente su contenido al usuario. En general, el enfoque adoptado para dar cabida a los datos eliminados debe ser el que mejor se adapte al almacén de datos subyacente del modelo.

Los distintos tipos de modelos suelen gestionar los datos arrastrados de formas diferentes. Los modelos de lista y tabla solo proporcionan una estructura plana en la que se almacenan los elementos de datos. Como resultado, pueden insertar nuevas filas (y columnas) cuando se sueltan datos sobre un elemento existente en una vista, o pueden sobrescribir el contenido del elemento en el modelo utilizando parte de los datos proporcionados. Los modelos de árbol suelen ser capaces de añadir elementos secundarios que contienen nuevos datos a sus almacenes de datos subyacentes y, por lo tanto, se comportarán de forma más predecible desde el punto de vista del usuario.

Los datos arrastrados se gestionan mediante la reimplementación que hace un modelo de la función ` QAbstractItemModel::dropMimeData()`. Por ejemplo, un modelo que gestiona una lista simple de cadenas puede proporcionar una implementación que trate los datos arrastrados sobre elementos existentes de forma independiente de los datos arrastrados al nivel superior del modelo (es decir, sobre un elemento no válido).

Los modelos pueden prohibir el arrastre sobre determinados elementos, o en función de los datos arrastrados, mediante la reimplementación de ` QAbstractItemModel::canDropMimeData()`.

El modelo debe asegurarse primero de que la operación debe llevarse a cabo, de que los datos proporcionados están en un formato que se puede utilizar y de que su destino dentro del modelo es válido:

bool DragDropListModel::canDropMimeData(const QMimeData *data,
    Qt::DropAction action, int row, int column, const QModelIndex &parent) const
{
    Q_UNUSED(action);
    Q_UNUSED(row);
    Q_UNUSED(parent);

    if (!data->hasFormat("application/vnd.text.list"))
        return false;

    if (column > 0)
        return false;

    return true;
}
bool DragDropListModel::dropMimeData(const QMimeData *data,
    Qt::DropAction action, int row, int column, const QModelIndex &parent)
{
    if (!canDropMimeData(data, action, row, column, parent))
        return false;

    if (action == Qt::IgnoreAction)
        return true;

Un modelo sencillo de lista de cadenas de una sola columna puede indicar un error si los datos facilitados no son texto sin formato o si el número de columna indicado para la inserción no es válido.

Los datos que se van a insertar en el modelo se tratan de forma diferente según se suelten sobre un elemento existente o no. En este sencillo ejemplo, queremos permitir que se suelten elementos entre elementos existentes, antes del primer elemento de la lista y después del último.

Cuando se produce una inserción, el índice del modelo correspondiente al elemento padre será válido —lo que indica que la inserción se ha producido en un elemento— o inválido —lo que indica que la inserción se ha producido en algún lugar de la vista que corresponde al nivel superior del modelo—.

int beginRow;

if (row != -1)
    beginRow = row;

En primer lugar, examinamos el número de fila proporcionado para ver si podemos utilizarlo para insertar elementos en el modelo, independientemente de si el índice del elemento padre es válido o no.

else if (parent.isValid())
    beginRow = parent.row();

Si el índice del modelo padre es válido, la eliminación se ha producido en un elemento. En este sencillo modelo de lista, averiguamos el número de fila del elemento y utilizamos ese valor para insertar los elementos eliminados en el nivel superior del modelo.

else
    beginRow = rowCount(QModelIndex());

Cuando se produce una eliminación en cualquier otro punto de la vista y el número de fila no se puede utilizar, añadimos los elementos al nivel superior del modelo.

En los modelos jerárquicos, cuando se produce una eliminación de un elemento, sería mejor insertar los nuevos elementos en el modelo como hijos de ese elemento. En el sencillo ejemplo que se muestra aquí, el modelo solo tiene un nivel, por lo que este enfoque no es adecuado.

Decodificación de datos importados

Cada implementación de ` dropMimeData()` también debe decodificar los datos e insertarlos en la estructura de datos subyacente del modelo.

En el caso de un modelo sencillo de lista de cadenas, los elementos codificados pueden decodificarse e introducirse en un ` QStringList`:

QByteArray encodedData = data->data("application/vnd.text.list");
QDataStream stream(&encodedData, QIODevice::ReadOnly);
QStringList newItems;
int rows = 0;

while (!stream.atEnd()) {
    QString text;
    stream >> text;
    newItems << text;
    ++rows;
}

A continuación, las cadenas se pueden insertar en el almacén de datos subyacente. Para mantener la coherencia, esto se puede hacer a través de la propia interfaz del modelo:

    insertRows(beginRow, rows, QModelIndex());
    for (const QString &text : std::as_const(newItems)) {
        QModelIndex idx = index(beginRow, 0, QModelIndex());
        setData(idx, text);
        beginRow++;
    }

    return true;
}

Ten en cuenta que, por lo general, el modelo deberá proporcionar implementaciones de las funciones ` QAbstractItemModel::insertRows()` y ` QAbstractItemModel::setData()`.

Modelos proxy

En el marco de trabajo «modelo/vista», los elementos de datos proporcionados por un único modelo pueden ser compartidos por cualquier número de vistas, y cada una de ellas puede representar la misma información de formas completamente diferentes. Las vistas personalizadas y los delegados son formas eficaces de proporcionar representaciones radicalmente diferentes de los mismos datos. Sin embargo, las aplicaciones a menudo necesitan ofrecer vistas convencionales de versiones procesadas de los mismos datos, como vistas ordenadas de forma diferente de una lista de elementos.

Aunque parece adecuado realizar operaciones de ordenación y filtrado como funciones internas de las vistas, este enfoque no permite que varias vistas compartan los resultados de operaciones que pueden resultar costosas. El enfoque alternativo, que implica ordenar dentro del propio modelo, conduce a un problema similar, en el que cada vista tiene que mostrar elementos de datos organizados según la operación de procesamiento más reciente.

Para resolver este problema, el marco modelo/vista utiliza modelos proxy para gestionar la información que se intercambia entre los modelos individuales y las vistas. Los modelos proxy son componentes que, desde la perspectiva de una vista, se comportan como modelos normales y acceden a los datos de los modelos de origen en nombre de dicha vista. Las señales y ranuras que utiliza el marco de trabajo «modelo/vista» garantizan que cada vista se actualice adecuadamente, independientemente del número de modelos proxy que se interpongan entre ella y el modelo de origen.

Uso de modelos proxy

Los modelos proxy pueden insertarse entre un modelo existente y cualquier número de vistas. Qt incluye un modelo proxy estándar, ` QSortFilterProxyModel`, que normalmente se instancia y se utiliza directamente, pero del que también se pueden crear subclases para proporcionar un comportamiento personalizado de filtrado y ordenación. La clase ` QSortFilterProxyModel ` puede utilizarse de la siguiente manera:

QSortFilterProxyModel *filterModel = new QSortFilterProxyModel(parent);
filterModel->setSourceModel(stringListModel);

QListView *filteredView = new QListView;
filteredView->setModel(filterModel);

Dado que los modelos proxy heredan de ` QAbstractItemModel`, pueden conectarse a cualquier tipo de vista y compartirse entre vistas. También pueden utilizarse para procesar la información obtenida de otros modelos proxy en una configuración en cadena.

La clase ` QSortFilterProxyModel ` está diseñada para ser instanciada y utilizada directamente en aplicaciones. Se pueden crear modelos proxy más especializados creando subclases de esta clase e implementando las operaciones de comparación necesarias.

Personalización de modelos proxy

Por lo general, el tipo de procesamiento utilizado en un modelo proxy consiste en asignar cada elemento de datos desde su ubicación original en el modelo de origen a una ubicación diferente en el modelo proxy. En algunos modelos, es posible que ciertos elementos no tengan una ubicación correspondiente en el modelo proxy; estos modelos se denominan modelos proxy de filtrado. Las vistas acceden a los elementos mediante índices de modelo proporcionados por el modelo proxy, y estos no contienen información sobre el modelo de origen ni sobre las ubicaciones de los elementos originales en dicho modelo.

QSortFilterProxyModel permite filtrar los datos de un modelo de origen antes de suministrarlos a las vistas, y también permite que el contenido de un modelo de origen se suministre a las vistas como datos preclasificados.

Modelos de filtrado personalizados

La clase ` QSortFilterProxyModel ` proporciona un modelo de filtrado bastante versátil, que puede utilizarse en diversas situaciones habituales. Para usuarios avanzados, es posible crear subclases de ` QSortFilterProxyModel `, lo que proporciona un mecanismo que permite implementar filtros personalizados.

Las subclases de ` QSortFilterProxyModel ` pueden reimplementar dos funciones virtuales que se invocan cada vez que se solicita o se utiliza un índice de modelo del modelo proxy:

  • filterAcceptsColumn() se utiliza para filtrar columnas específicas de una parte del modelo de origen.
  • filterAcceptsRow() se utiliza para filtrar filas específicas de una parte del modelo de origen.

Las implementaciones predeterminadas de las funciones anteriores en ` QSortFilterProxyModel ` devuelven `true` para garantizar que todos los elementos se transfieran a las vistas; las reimplementaciones de estas funciones deben devolver `false` para filtrar filas y columnas concretas.

Modelos de ordenación personalizados

QSortFilterProxyModel utilizan la función std::stable_sort() para establecer correspondencias entre los elementos del modelo de origen y los del modelo proxy, lo que permite exponer a las vistas una jerarquía ordenada de elementos sin modificar la estructura del modelo de origen. Para proporcionar un comportamiento de ordenación personalizado, reimplementa la función lessThan() para realizar comparaciones personalizadas.

Referencia sobre la subclasificación de modelos

Las subclases de modelo deben proporcionar implementaciones de muchas de las funciones virtuales definidas en la clase base ` QAbstractItemModel `. El número de estas funciones que deben implementarse depende del tipo de modelo: si proporciona a las vistas una lista simple, una tabla o una jerarquía compleja de elementos. Los modelos que heredan de QAbstractListModel y QAbstractTableModel pueden aprovechar las implementaciones predeterminadas de las funciones proporcionadas por dichas clases. Los modelos que exponen elementos de datos en estructuras de tipo árbol deben proporcionar implementaciones para muchas de las funciones virtuales de QAbstractItemModel.

Las funciones que deben implementarse en una subclase de modelo pueden dividirse en tres grupos:

  • Manejo de datos de elementos: Todos los modelos deben implementar funciones que permitan a las vistas y a los delegados consultar las dimensiones del modelo, examinar elementos y recuperar datos.
  • Navegación y creación de índices: los modelos jerárquicos deben proporcionar funciones que las vistas puedan invocar para navegar por las estructuras en forma de árbol que exponen y obtener índices del modelo para los elementos.
  • Compatibilidad con arrastrar y soltar y gestión de tipos MIME: los modelos heredan funciones que controlan la forma en que se realizan las operaciones internas y externas de arrastrar y soltar. Estas funciones permiten describir los elementos de datos en términos de tipos MIME que otros componentes y aplicaciones pueden entender.

Gestión de los datos de los elementos

Los modelos pueden ofrecer distintos niveles de acceso a los datos que proporcionan: pueden ser simples componentes de solo lectura; algunos modelos pueden admitir operaciones de cambio de tamaño; y otros pueden permitir la edición de elementos.

Acceso de solo lectura

Para proporcionar acceso de solo lectura a los datos proporcionados por un modelo, deben implementarse las siguientes funciones en la subclase del modelo:

flags()Utilizada por otros componentes para obtener información sobre cada elemento proporcionado por el modelo. En muchos modelos, la combinación de indicadores debe incluir Qt::ItemIsEnabled y Qt::ItemIsSelectable.
data()Se utiliza para proporcionar datos de elementos a vistas y delegados. Por lo general, los modelos solo necesitan proporcionar datos para Qt::DisplayRole y cualquier rol de usuario específico de la aplicación, pero también es una buena práctica proporcionar datos para Qt::ToolTipRole, Qt::AccessibleTextRole y Qt::AccessibleDescriptionRole. Consulte la documentación de la enumeración Qt::ItemDataRole para obtener información sobre los tipos asociados a cada rol.
headerData()Proporciona a las vistas la información que deben mostrar en sus encabezados. La información solo la recuperan las vistas que pueden mostrar información en el encabezado.
rowCount()Proporciona el número de filas de datos expuestas por el modelo.

Estas cuatro funciones deben implementarse en todos los tipos de modelo, incluidos los modelos de lista (subclases de `QAbstractListModel `) y los modelos de tabla (subclases de `QAbstractTableModel `).

Además, las siguientes funciones deben implementarse en las subclases directas de QAbstractTableModel y QAbstractItemModel:

columnCount()Proporciona el número de columnas de datos que expone el modelo. Los modelos de lista no proporcionan esta función, ya que está implementada en QAbstractListModel.

Elementos editables

Los modelos editables permiten modificar elementos de datos y también pueden proporcionar funciones que permitan insertar y eliminar filas y columnas. Para habilitar la edición, deben implementarse correctamente las siguientes funciones:

flags()Debe devolver una combinación adecuada de indicadores para cada elemento. En concreto, el valor devuelto por esta función debe incluir Qt::ItemIsEditable, además de los valores aplicados a los elementos en un modelo de solo lectura.
setData()Se utiliza para modificar el elemento de datos asociado a un índice de modelo especificado. Para poder aceptar la entrada del usuario, proporcionada por elementos de la interfaz de usuario, esta función debe gestionar los datos asociados a Qt::EditRole. La implementación también puede aceptar datos asociados a muchos tipos diferentes de roles especificados por Qt::ItemDataRole. Tras modificar el elemento de datos, los modelos deben emitir la señal dataChanged() para informar a otros componentes del cambio.
setHeaderData()Se utiliza para modificar la información de los encabezados horizontales y verticales. Tras modificar el dato, los modelos deben emitir la señal headerDataChanged() para informar a los demás componentes del cambio.

Modelos redimensionables

Todos los tipos de modelos admiten la inserción y eliminación de filas. Los modelos de tabla y los modelos jerárquicos también admiten la inserción y eliminación de columnas. Es importante notificar a los demás componentes los cambios en las dimensiones del modelo, tanto antes como después de que se produzcan. Por ello, se pueden implementar las siguientes funciones para permitir el redimensionamiento del modelo, pero las implementaciones deben garantizar que se llamen las funciones adecuadas para notificar a las vistas y delegados asociados:

insertRows()Se utiliza para añadir nuevas filas y elementos de datos a todo tipo de modelos. Las implementaciones deben llamar a beginInsertRows() antes de insertar nuevas filas en cualquier estructura de datos subyacente, y llamar a endInsertRows() inmediatamente después.
removeRows()Se utiliza para eliminar filas y los elementos de datos que contienen de cualquier tipo de modelo. Las implementaciones deben llamar a beginRemoveRows() antes de eliminar filas de cualquier estructura de datos subyacente, y llamar a endRemoveRows() inmediatamente después.
insertColumns()Se utiliza para añadir nuevas columnas y elementos de datos a modelos de tabla y modelos jerárquicos. Las implementaciones deben llamar a ` beginInsertColumns()` antes de insertar nuevas columnas en cualquier estructura de datos subyacente, y llamar a ` endInsertColumns()` inmediatamente después.
removeColumns()Se utiliza para eliminar columnas y los datos que contienen de los modelos de tabla y los modelos jerárquicos. Las implementaciones deben llamar a ` beginRemoveColumns()` antes de eliminar columnas de cualquier estructura de datos subyacente, y llamar a ` endRemoveColumns()` inmediatamente después.

Por lo general, estas funciones deben devolver «true» si la operación se ha realizado correctamente. Sin embargo, puede haber casos en los que la operación solo haya tenido éxito parcialmente; por ejemplo, si no se ha podido insertar el número de filas especificado. En tales casos, el modelo debe devolver «false» para indicar el fallo y permitir que cualquier componente asociado gestione la situación.

Las señales emitidas por las funciones llamadas en las implementaciones de la API de redimensionamiento permiten a los componentes asociados actuar antes de que los datos dejen de estar disponibles. La encapsulación de las operaciones de inserción y eliminación mediante las funciones `begin` y `end` también permite al modelo gestionar correctamente el ` persistent model indexes `.

Normalmente, las funciones «begin» y «end» son capaces de informar a otros componentes sobre los cambios en la estructura subyacente del modelo. Para cambios más complejos en la estructura del modelo, que quizá impliquen una reorganización interna, la clasificación de datos o cualquier otro cambio estructural, es necesario llevar a cabo la siguiente secuencia:

Esta secuencia puede utilizarse para cualquier actualización estructural en lugar de los métodos protegidos, que son más generales y cómodos. Por ejemplo, si en un modelo de dos millones de filas es necesario eliminar todas las filas impares, esto supone un millón de rangos no contiguos de un elemento cada uno. Sería posible utilizar `beginRemoveRows` y `endRemoveRows` un millón de veces, pero eso resultaría obviamente ineficiente. En su lugar, esto puede señalarse como un único cambio de estructura que actualiza todos los índices persistentes necesarios de una sola vez.

Población diferida de los datos del modelo

El rellenado diferido de los datos del modelo permite, en la práctica, aplazar las solicitudes de información sobre el modelo hasta que las vistas realmente la necesiten.

Algunos modelos necesitan obtener datos de fuentes remotas o deben realizar operaciones que consumen mucho tiempo para obtener información sobre la forma en que están organizados los datos. Dado que las vistas suelen solicitar toda la información posible para mostrar con precisión los datos del modelo, puede resultar útil restringir la cantidad de información que se les devuelve para reducir las solicitudes de datos de seguimiento innecesarias.

En modelos jerárquicos en los que averiguar el número de elementos secundarios de un elemento dado supone una operación costosa, resulta útil garantizar que la implementación de la función ` rowCount()` del modelo solo se llame cuando sea necesario. En tales casos, la función hasChildren() puede reimplementarse para proporcionar a las vistas una forma económica de comprobar la presencia de elementos secundarios y, en el caso de QTreeView, dibujar la decoración adecuada para su elemento principal.

Tanto si la reimplementación de ` hasChildren()` devuelve ` true ` como si devuelve ` false`, puede que no sea necesario que la vista llame a ` rowCount()` para averiguar cuántos elementos secundarios hay. Por ejemplo, ` QTreeView ` no necesita saber cuántos elementos secundarios hay si el elemento padre no se ha expandido para mostrarlos.

Si se sabe que muchos elementos tendrán elementos secundarios, a veces resulta útil reimplementar ` hasChildren()` para que devuelva incondicionalmente ` true `. Esto garantiza que posteriormente se pueda comprobar si cada elemento tiene elementos secundarios, al tiempo que agiliza al máximo el llenado inicial de los datos del modelo. La única desventaja es que los elementos sin hijos pueden mostrarse incorrectamente en algunas vistas hasta que el usuario intente ver los elementos hijos inexistentes.

Los modelos jerárquicos deben proporcionar funciones que las vistas puedan invocar para navegar por las estructuras en forma de árbol que exponen y obtener índices del modelo para los elementos.

Elementos padres e hijos

Dado que la estructura expuesta a las vistas viene determinada por la estructura de datos subyacente, corresponde a cada subclase del modelo crear sus propios índices de modelo proporcionando implementaciones de las siguientes funciones:

index()Dado un índice de modelo para un elemento padre, esta función permite a las vistas y a los delegados acceder a los elementos hijos de dicho elemento. Si no se encuentra ningún elemento hijo válido —que se corresponda con la fila, la columna y el índice de modelo padre especificados—, la función debe devolver QModelIndex(), que es un índice de modelo no válido.
parent()Proporciona un índice de modelo correspondiente al elemento padre de cualquier elemento hijo dado. Si el índice de modelo especificado corresponde a un elemento de nivel superior en el modelo, o si no existe ningún elemento padre válido en el modelo, la función debe devolver un índice de modelo no válido, creado con el constructor vacío de QModelIndex().

Ambas funciones anteriores utilizan la función de fábrica createIndex() para generar índices que puedan utilizar otros componentes. Es habitual que los modelos proporcionen algún identificador único a esta función para garantizar que el índice del modelo pueda volver a asociarse con su elemento correspondiente más adelante.

Compatibilidad con arrastrar y soltar y gestión de tipos MIME

Las clases de modelo/vista admiten operaciones de arrastrar y soltar, proporcionando un comportamiento predeterminado que resulta suficiente para muchas aplicaciones. Sin embargo, también es posible personalizar la forma en que se codifican los elementos durante las operaciones de arrastrar y soltar, si se copian o se mueven de forma predeterminada, y cómo se insertan en los modelos existentes.

Además, las clases de vistas de conveniencia implementan un comportamiento especializado que debería ajustarse fielmente a lo que esperan los desarrolladores actuales. La sección «Vistas de conveniencia» ofrece una visión general de este comportamiento.

Datos MIME

Por defecto, los modelos y vistas integrados utilizan un tipo MIME interno (application/x-qabstractitemmodeldatalist) para transmitir información sobre los índices de los modelos. Este tipo especifica los datos de una lista de elementos, que contiene los números de fila y columna de cada elemento, así como información sobre las funciones que admite cada elemento.

Los datos codificados con este tipo MIME se pueden obtener llamando a la función ` QAbstractItemModel::mimeData()` con un objeto ` QModelIndexList ` que contenga los elementos que se van a serializar.

Al implementar la compatibilidad con la función de arrastrar y soltar en un modelo personalizado, es posible exportar elementos de datos en formatos especializados reimplementando la siguiente función:

mimeData()Esta función se puede reimplementar para devolver datos en formatos distintos del tipo MIME interno predeterminado de ` application/x-qabstractitemmodeldatalist `.

Las subclases pueden obtener el objeto QMimeData predeterminado de la clase base y añadirle datos en formatos adicionales.

Para muchos modelos, resulta útil proporcionar el contenido de los elementos en formatos comunes representados por tipos MIME como text/plain y image/png. Ten en cuenta que las imágenes, los colores y los documentos HTML se pueden añadir fácilmente a un objeto QMimeData mediante las funciones QMimeData::setImageData(), QMimeData::setColorData() y QMimeData::setHtml().

Aceptación de datos arrastrados

Cuando se realiza una operación de arrastrar y soltar sobre una vista, se consulta el modelo subyacente para determinar qué tipos de operaciones admite y los tipos MIME que puede aceptar. Esta información la proporcionan las funciones QAbstractItemModel::supportedDropActions() y QAbstractItemModel::mimeTypes(). Los modelos que no sobrescriben las implementaciones proporcionadas por QAbstractItemModel admiten operaciones de copia y el tipo MIME interno predeterminado para los elementos.

Cuando se suelta un elemento de datos serializado en una vista, los datos se insertan en el modelo actual utilizando su implementación de QAbstractItemModel::dropMimeData(). La implementación predeterminada de esta función nunca sobrescribirá ningún dato del modelo; en su lugar, intenta insertar los elementos de datos como elementos hermanos de un elemento o como elementos hijos de dicho elemento.

Para aprovechar la implementación predeterminada de ` QAbstractItemModel` para el tipo MIME integrado, los nuevos modelos deben proporcionar reimplementaciones de las siguientes funciones:

insertRows()Estas funciones permiten al modelo insertar automáticamente nuevos datos utilizando la implementación existente proporcionada por QAbstractItemModel::dropMimeData().
insertColumns()
setData()Permite rellenar las nuevas filas y columnas con elementos.
setItemData()Esta función ofrece un soporte más eficiente para rellenar nuevos elementos.

Para aceptar otros tipos de datos, es necesario reimplementar estas funciones:

supportedDropActions()Se utiliza para devolver una combinación de ` drop actions`, que indica los tipos de operaciones de arrastrar y soltar que admite el modelo.
mimeTypes()Se utiliza para devolver una lista de tipos MIME que el modelo puede decodificar y gestionar. Por lo general, los tipos MIME admitidos como entrada en el modelo son los mismos que los que este puede utilizar al codificar datos para su uso por parte de componentes externos.
dropMimeData()Realiza la decodificación efectiva de los datos transferidos mediante operaciones de arrastrar y soltar, determina en qué parte del modelo se establecerán e inserta nuevas filas y columnas cuando sea necesario. La forma en que se implementa esta función en las subclases depende de los requisitos de los datos expuestos por cada modelo.

Si la implementación de la función ` dropMimeData()` modifica las dimensiones de un modelo al insertar o eliminar filas o columnas, o si se modifican elementos de datos, hay que asegurarse de que se emitan todas las señales pertinentes. Puede resultar útil limitarse a llamar a reimplementaciones de otras funciones en la subclase, como setData(), insertRows() y insertColumns(), para garantizar que el modelo se comporte de forma coherente.

Para garantizar que las operaciones de arrastre funcionen correctamente, es importante reimplementar las siguientes funciones que eliminan datos del modelo:

Para obtener más información sobre la función de arrastrar y soltar en las vistas de elementos, consulta «Uso de la función de arrastrar y soltar en las vistas de elementos».

Vistas de acceso rápido

Las vistas de conveniencia (QListWidget, QTableWidget y QTreeWidget) sustituyen la funcionalidad predeterminada de arrastrar y soltar para ofrecer un comportamiento menos flexible, pero más natural, adecuado para muchas aplicaciones. Por ejemplo, dado que es más habitual soltar datos en celdas de una tabla de datos ( QTableWidget), sustituyendo el contenido existente por los datos que se transfieren, el modelo subyacente establecerá los datos de los elementos de destino en lugar de insertar nuevas filas y columnas en el modelo. Para obtener más información sobre la función de arrastrar y soltar en las vistas de conveniencia, consulta «Uso de la función de arrastrar y soltar con vistas de elementos».

Optimización del rendimiento para grandes cantidades de datos

La función « canFetchMore()» comprueba si el elemento padre tiene más datos disponibles y devuelve « true » o «false» según corresponda. La función « fetchMore » () recupera datos en función del elemento principal especificado. Ambas funciones se pueden combinar, por ejemplo, en una consulta de base de datos que implique datos incrementales para rellenar un « QAbstractItemModel ». Reimplementamos « canFetchMore » () para indicar si hay más datos que recuperar y « fetchMore » () para rellenar el modelo según sea necesario.

Otro ejemplo serían los modelos de árbol rellenados dinámicamente, en los que reimplementamos fetchMore() cuando se expande una rama del modelo de árbol.

Si tu reimplementación de fetchMore() añade filas al modelo, debes llamar a beginInsertRows() y a endInsertRows(). Además, tanto canFetchMore() como fetchMore() deben reimplementarse, ya que su implementación por defecto devuelve «false» y no realiza ninguna acción.

Las clases de modelo y vista

Estas clases utilizan el patrón de diseño «modelo-vista», en el que los datos subyacentes (en el modelo) se mantienen separados de la forma en que el usuario presenta y manipula dichos datos (en la vista).

QAbstractItemDelegate

Se utilizan para mostrar y editar elementos de datos de un modelo

QAbstractItemModel

La interfaz abstracta para las clases de modelo de elementos

QAbstractItemView

La funcionalidad básica para las clases de vista de elementos

QAbstractListModel

Modelo abstracto del que se pueden crear subclases para generar modelos de listas unidimensionales

QAbstractProxyModel

Clase base para modelos de elementos proxy que pueden realizar tareas de ordenación, filtrado u otras tareas de procesamiento de datos

QAbstractTableModel

Modelo abstracto del que se pueden crear subclases para crear modelos de tabla

QColumnView

Implementación de modelo/vista de una vista de columna

QConcatenateTablesProxyModel

Actúa como proxy de varios modelos fuente, concatenando sus filas

QDataWidgetMapper

Asignación entre una sección de un modelo de datos y los widgets

QFileSystemModel

Modelo de datos para el sistema de archivos local

QHeaderView

Fila o columna de encabezado para vistas de elementos

QIdentityProxyModel

Actúa como proxy de su modelo de origen sin modificaciones

QItemDelegate

Funciones de visualización y edición para elementos de datos de un modelo

QItemEditorCreator

Permite crear bases para creadores de editores de elementos sin necesidad de subclasificar QItemEditorCreatorBase

QItemEditorCreatorBase

Clase base abstracta que debe subclasificarse al implementar nuevos creadores de editores de elementos

QItemEditorFactory

Widgets para editar datos de elementos en vistas y delegados

QItemSelection

Gestiona la información sobre los elementos seleccionados en un modelo

QItemSelectionModel

Realiza un seguimiento de los elementos seleccionados de una vista

QItemSelectionRange

Gestiona la información sobre un rango de elementos seleccionados en un modelo

QListView

Vista de lista o de iconos de un modelo

QListWidget

Widget de lista basado en elementos

QListWidgetItem

Elemento para utilizar con la clase de vista de elementos QListWidget

QModelIndex

Se utiliza para localizar datos en un modelo de datos

QModelRoleData

Alberga un rol y los datos asociados a dicho rol

QModelRoleDataSpan

Abarca objetos QModelRoleData

QPersistentModelIndex

Se utiliza para localizar datos en un modelo de datos

QRangeModel

Implementa QAbstractItemModel para cualquier rango de C++

QRangeModel::ItemAccess

La plantilla proporciona un punto de personalización para controlar cómo QRangeModel accede a los datos de rol de los elementos individuales

QRangeModel::RowOptions

La plantilla proporciona un punto de personalización para controlar cómo QRangeModel representa los tipos utilizados como filas

QRangeModelAdapter

Acceso compatible con QAbstractItemModel a cualquier rango de C++

QRangeModelAdapter::ColumnIterator

Proporciona un iterador no constante, al estilo de la STL, sobre las columnas de una fila del modelo

QRangeModelAdapter::ConstColumnIterator

Proporciona un iterador no constante, al estilo STL, sobre las columnas de una fila del modelo

QRangeModelAdapter::ConstRowIterator

Proporciona un iterador const al estilo STL sobre las filas de un modelo

QRangeModelAdapter::ConstRowReference

Envoltura de referencia en torno a una fila const de un QRangeModel

QRangeModelAdapter::DataReference

Envoltura de referencia en torno a un elemento de un QRangeModel

QRangeModelAdapter::RowIterator

Proporciona un iterador no constante, al estilo STL, sobre las filas de un modelo

QRangeModelAdapter::RowReference

Envoltura de referencia alrededor de una fila de un QRangeModel

QRangeModelAdapter::RowReferenceBase

API común para RowReference y ConstRowReference

QSortFilterProxyModel

Compatibilidad con la ordenación y el filtrado de datos que se pasan entre otro modelo y una vista

QStandardItem

Elemento para su uso con la clase QStandardItemModel

QStandardItemEditorCreator

Posibilidad de registrar widgets sin necesidad de crear una subclase de QItemEditorCreatorBase

QStandardItemModel

Modelo genérico para almacenar datos personalizados

QStringListModel

Modelo que proporciona cadenas de texto a las vistas

QStyledItemDelegate

Funciones de visualización y edición de elementos de datos de un modelo

QTableView

Implementación predeterminada de modelo/vista para una vista de tabla

QTableWidget

Vista de tabla basada en elementos con un modelo predeterminado

QTableWidgetItem

Elemento para su uso con la clase QTableWidget

QTableWidgetSelectionRange

Forma de interactuar con la selección en un modelo sin utilizar índices de modelo ni un modelo de selección

QTreeView

Implementación predeterminada de modelo/vista de una vista de árbol

QTreeWidget

Vista de árbol que utiliza un modelo de árbol predefinido

QTreeWidgetItem

Elemento para utilizar con la clase de conveniencia QTreeWidget

QTreeWidgetItemIterator

Forma de recorrer los elementos de una instancia de QTreeWidget

© 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.