QListView Class
La clase QListView ofrece una vista en forma de lista o de iconos de un modelo. Más información...
| Encabezado: | #include <QListView> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| Heredado de: | QAbstractItemView |
| Heredado por: |
Tipos públicos
| enum | Flow { LeftToRight, TopToBottom } |
| enum | LayoutMode { SinglePass, Batched } |
| enum | Movement { Static, Free, Snap } |
| enum | ResizeMode { Fixed, Adjust } |
| enum | ViewMode { ListMode, IconMode } |
Propiedades
|
|
Funciones públicas
| QListView(QWidget *parent = nullptr) | |
| virtual | ~QListView() |
| int | batchSize() const |
| void | clearPropertyFlags() |
| QListView::Flow | flow() const |
| QSize | gridSize() const |
| bool | isRowHidden(int row) const |
| bool | isSelectionRectVisible() const |
| bool | isWrapping() const |
| Qt::Alignment | itemAlignment() const |
| QListView::LayoutMode | layoutMode() const |
| int | modelColumn() const |
| QListView::Movement | movement() const |
| QListView::ResizeMode | resizeMode() const |
| void | setBatchSize(int batchSize) |
| void | setFlow(QListView::Flow flow) |
| void | setGridSize(const QSize &size) |
| void | setItemAlignment(Qt::Alignment alignment) |
| void | setLayoutMode(QListView::LayoutMode mode) |
| void | setModelColumn(int column) |
| void | setMovement(QListView::Movement movement) |
| void | setResizeMode(QListView::ResizeMode mode) |
| void | setRowHidden(int row, bool hide) |
| void | setSelectionRectVisible(bool show) |
| void | setSpacing(int space) |
| void | setUniformItemSizes(bool enable) |
| void | setViewMode(QListView::ViewMode mode) |
| void | setWordWrap(bool on) |
| void | setWrapping(bool enable) |
| int | spacing() const |
| bool | uniformItemSizes() const |
| QListView::ViewMode | viewMode() const |
| bool | wordWrap() const |
Funciones públicas reimplementadas
| virtual QModelIndex | indexAt(const QPoint &p) const override |
| virtual void | scrollTo(const QModelIndex &index, QAbstractItemView::ScrollHint hint = EnsureVisible) override |
| virtual void | setRootIndex(const QModelIndex &index) override |
| virtual QRect | visualRect(const QModelIndex &index) const override |
Señales
| void | indexesMoved(const QModelIndexList &indexes) |
Funciones protegidas
| QRect | rectForIndex(const QModelIndex &index) const |
| void | setPositionForIndex(const QPoint &position, const QModelIndex &index) |
Funciones protegidas reimplementadas
| virtual void | currentChanged(const QModelIndex ¤t, const QModelIndex &previous) override |
| virtual void | dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight, const QList<int> &roles = QList<int>()) override |
| virtual void | dragLeaveEvent(QDragLeaveEvent *e) override |
| virtual void | dragMoveEvent(QDragMoveEvent *e) override |
| virtual void | dropEvent(QDropEvent *event) override |
| virtual bool | event(QEvent *e) override |
| virtual int | horizontalOffset() const override |
| virtual void | initViewItemOption(QStyleOptionViewItem *option) const override |
| virtual bool | isIndexHidden(const QModelIndex &index) const override |
| virtual void | mouseMoveEvent(QMouseEvent *e) override |
| virtual void | mouseReleaseEvent(QMouseEvent *e) override |
| virtual QModelIndex | moveCursor(QAbstractItemView::CursorAction cursorAction, Qt::KeyboardModifiers modifiers) override |
| virtual void | paintEvent(QPaintEvent *e) override |
| virtual void | resizeEvent(QResizeEvent *e) override |
| virtual void | rowsAboutToBeRemoved(const QModelIndex &parent, int start, int end) override |
| virtual void | rowsInserted(const QModelIndex &parent, int start, int end) override |
| virtual void | scrollContentsBy(int dx, int dy) override |
| virtual QModelIndexList | selectedIndexes() const override |
| virtual void | selectionChanged(const QItemSelection &selected, const QItemSelection &deselected) override |
| virtual void | setSelection(const QRect &rect, QItemSelectionModel::SelectionFlags command) override |
| virtual void | startDrag(Qt::DropActions supportedActions) override |
| virtual void | timerEvent(QTimerEvent *e) override |
| virtual void | updateGeometries() override |
| virtual int | verticalOffset() const override |
| virtual QSize | viewportSizeHint() const override |
| virtual QRegion | visualRegionForSelection(const QItemSelection &selection) const override |
| virtual void | wheelEvent(QWheelEvent *e) override |
Descripción detallada

Una QListView presenta los elementos almacenados en un modelo, ya sea como una simple lista no jerárquica o como una colección de iconos. Esta clase se utiliza para proporcionar listas y vistas de iconos que antes ofrecían las clases QListBox y QIconView, pero utilizando el enfoque más flexible que ofrece la arquitectura modelo/vista de Qt.
La clase QListView es una de las clases de modelo/vista y forma parte del marco de trabajo de modelo/vista de Qt.
Esta vista no muestra encabezados horizontales ni verticales; para mostrar una lista de elementos con un encabezado horizontal, utilice en su lugar QTreeView.
QListView implementa las interfaces definidas por la clase QAbstractItemView para permitirle mostrar datos proporcionados por modelos derivados de la clase QAbstractItemModel.
Los elementos de una vista de lista se pueden mostrar utilizando uno de los dos modos de visualización: en ListMode, los elementos se muestran en forma de lista simple; en IconMode, la vista de lista adopta la forma de una vista de iconos en la que los elementos se muestran con iconos, como los archivos en un gestor de archivos. Por defecto, la vista de lista se encuentra en ListMode. Para cambiar el modo de vista, utilice la función setViewMode(), y para determinar el modo de vista actual, utilice viewMode().
Los elementos de estas vistas se distribuyen en la dirección especificada por flow() de la vista de lista. Los elementos pueden estar fijos en su posición o permitirse que se muevan, dependiendo del estado de movement() de la vista.
Si los elementos del modelo no pueden distribuirse completamente en la dirección del flujo, pueden ajustarse al límite del widget de vista; esto depende de ` isWrapping()`. Esta propiedad resulta útil cuando los elementos se representan mediante una vista de iconos.
Las propiedades « resizeMode()» y « layoutMode()» determinan cómo y cuándo se distribuyen los elementos. Los elementos se espacian según su « spacing()» y pueden situarse dentro de una cuadrícula teórica cuyo tamaño viene especificado por « gridSize()». Los elementos pueden representarse como iconos grandes o pequeños en función de su « iconSize()».
Mejora del rendimiento
Es posible proporcionar a la vista indicaciones sobre los datos que maneja con el fin de mejorar su rendimiento al mostrar un gran número de elementos. Un enfoque que se puede adoptar para las vistas destinadas a mostrar elementos de igual tamaño es establecer la propiedad uniformItemSizes en «true».
Véase también Clases de vista, QTreeView, QTableView y QListWidget.
Documentación sobre tipos de miembros
enum QListView::Flow
| Constante | Valor | Descripción |
|---|---|---|
QListView::LeftToRight | 0 | Los elementos se disponen en la vista de izquierda a derecha. |
QListView::TopToBottom | 1 | Los elementos se disponen en la vista de arriba abajo. |
enum QListView::LayoutMode
| Constante | Valor | Descripción |
|---|---|---|
QListView::SinglePass | 0 | Los elementos se disponen todos a la vez. |
QListView::Batched | 1 | Los artículos se distribuyen en lotes de batchSize artículos. |
Véase también « batchSize ».
enum QListView::Movement
| Constante | Valor | Descripción |
|---|---|---|
QListView::Static | 0 | El usuario no puede mover los elementos. |
QListView::Free | 1 | El usuario puede mover los elementos libremente. |
QListView::Snap | 2 | Los elementos se ajustan a la cuadrícula especificada al moverlos; véase setGridSize(). |
enum QListView::ResizeMode
| Constante | Valor | Descripción |
|---|---|---|
QListView::Fixed | 0 | Los elementos solo se distribuirán la primera vez que se muestre la vista. |
QListView::Adjust | 1 | Los elementos se distribuirán cada vez que se cambie el tamaño de la vista. |
enum QListView::ViewMode
| Constante | Valor | Descripción |
|---|---|---|
QListView::ListMode | 0 | Los artículos se disponen siguiendo un flujo « TopToBottom », con tamaño «Pequeño» y movimiento «Estático». |
QListView::IconMode | 1 | Los artículos se distribuyen mediante un flujo « LeftToRight », con tamaño «Grande» y movimiento «Libre» |
Documentación de la propiedad
batchSize : int
Esta propiedad contiene el número de elementos distribuidos en cada lote si la opción « layoutMode » está configurada en « Batched ».
El valor por defecto es 100.
Funciones de acceso:
| int | batchSize() const |
| void | setBatchSize(int batchSize) |
flow : Flow
Esta propiedad determina en qué dirección debe fluir la disposición de los elementos.
Si esta propiedad es LeftToRight, los elementos se distribuirán de izquierda a derecha. Si la propiedad isWrapping tiene el valor true, la distribución se ajustará al llegar al lado derecho del área visible. Si esta propiedad es TopToBottom, los elementos se distribuirán desde la parte superior del área visible, ajustándose al llegar a la parte inferior.
Al establecer esta propiedad cuando la vista está visible, los elementos se volverán a distribuir.
Por defecto, esta propiedad está establecida en « TopToBottom ».
Funciones de acceso:
| QListView::Flow | flow() const |
| void | setFlow(QListView::Flow flow) |
Véase también viewMode.
gridSize : QSize
Esta propiedad almacena el tamaño de la cuadrícula de diseño
Esta propiedad indica el tamaño de la cuadrícula en la que se distribuyen los elementos. El valor por defecto es un tamaño vacío, lo que significa que no hay cuadrícula y que la distribución no se realiza en una cuadrícula. Al establecer esta propiedad en un tamaño no vacío, se activa la distribución en cuadrícula. (Cuando está activa la distribución en cuadrícula, se ignora la propiedad « spacing »).
Si se establece esta propiedad cuando la vista está visible, los elementos se volverán a distribuir.
Funciones de acceso:
| QSize | gridSize() const |
| void | setGridSize(const QSize &size) |
Véase también viewMode.
isWrapping : bool
Esta propiedad determina si el diseño de los elementos debe ajustar el ancho.
Esta propiedad determina si la disposición debe ajustarse cuando no queda más espacio en el área visible. El punto en el que se ajusta la disposición depende de la propiedad « flow ».
Si se configura esta propiedad cuando la vista está visible, los elementos se volverán a distribuir.
Por defecto, esta propiedad tiene el valor « false ».
Funciones de acceso:
| bool | isWrapping() const |
| void | setWrapping(bool enable) |
Véase también « viewMode ».
itemAlignment : Qt::Alignment
Esta propiedad determina la alineación de cada elemento dentro de su celda
Esto solo es compatible con ListMode con un flujo de texto de tipo « TopToBottom » (denso) y con el ajuste de texto activado. La alineación por defecto es 0, lo que significa que un elemento ocupa toda la celda.
Funciones de acceso:
| Qt::Alignment | itemAlignment() const |
| void | setItemAlignment(Qt::Alignment alignment) |
layoutMode : LayoutMode
Determina si la disposición de los elementos debe realizarse de forma inmediata o posponerse.
Esta propiedad establece el modo de disposición de los elementos. Cuando el modo es « SinglePass » (por defecto), los elementos se disponen todos de una sola vez. Cuando el modo es « Batched », los elementos se disponen en lotes de batchSize elementos, mientras se procesan los eventos. Esto permite ver e interactuar al instante con los elementos visibles mientras se dispone el resto.
Funciones de Access:
| QListView::LayoutMode | layoutMode() const |
| void | setLayoutMode(QListView::LayoutMode mode) |
Véase también viewMode.
modelColumn : int
Esta propiedad indica la columna del modelo que está visible
Por defecto, esta propiedad contiene el valor 0, lo que indica que se mostrará la primera columna del modelo.
Funciones de acceso:
| int | modelColumn() const |
| void | setModelColumn(int column) |
movement : Movement
Esta propiedad determina si los elementos se pueden mover libremente, si se ajustan a una cuadrícula o si no se pueden mover en absoluto.
Esta propiedad determina cómo puede el usuario mover los elementos en la vista. « Static » significa que el usuario no puede mover los elementos. « Free » significa que el usuario puede arrastrar y soltar los elementos en cualquier posición de la vista. « Snap » significa que el usuario puede arrastrar y soltar los elementos, pero solo en las posiciones de una cuadrícula teórica indicadas por la propiedad « gridSize ».
Al establecer esta propiedad cuando la vista está visible, los elementos se volverán a distribuir.
Por defecto, esta propiedad está establecida en « Static ».
Funciones de acceso:
| QListView::Movement | movement() const |
| void | setMovement(QListView::Movement movement) |
Véase también gridSize, resizeMode y viewMode.
resizeMode : ResizeMode
Esta propiedad determina si los elementos se vuelven a distribuir cuando se cambia el tamaño de la vista.
Si esta propiedad tiene el valor « Adjust », los elementos se volverán a distribuir cuando se cambie el tamaño de la vista. Si el valor es « Fixed », los elementos no se volverán a distribuir cuando se cambie el tamaño de la vista.
De forma predeterminada, esta propiedad está establecida en « Fixed ».
Funciones de acceso:
| QListView::ResizeMode | resizeMode() const |
| void | setResizeMode(QListView::ResizeMode mode) |
Véase también « movement », « gridSize » y « viewMode ».
selectionRectVisible : bool
si el rectángulo de selección debe estar visible
Si esta propiedad es « true », el rectángulo de selección estará visible; en caso contrario, permanecerá oculto.
Nota: El rectángulo de selección solo será visible si el modo de selección permite seleccionar más de un elemento; es decir, no se dibujará ningún rectángulo de selección si el modo de selección es « QAbstractItemView::SingleSelection ».
Por defecto, esta propiedad está en « false ».
Funciones de acceso:
| bool | isSelectionRectVisible() const |
| void | setSelectionRectVisible(bool show) |
spacing : int
Esta propiedad define el espacio que rodea a los elementos del diseño
Esta propiedad corresponde al tamaño del espacio vacío que se deja alrededor de un elemento en la disposición.
Si se configura esta propiedad cuando la vista está visible, los elementos se volverán a distribuir.
Por defecto, esta propiedad tiene un valor de 0.
Funciones de Access:
| int | spacing() const |
| void | setSpacing(int space) |
Véase también viewMode.
uniformItemSizes : bool
Esta propiedad indica si todos los elementos de la vista de lista tienen el mismo tamaño
Esta propiedad solo debe establecerse en «true» si se garantiza que todos los elementos de la vista tienen el mismo tamaño. Esto permite a la vista realizar algunas optimizaciones para mejorar el rendimiento.
Por defecto, esta propiedad está establecida en « false ».
Funciones de acceso:
| bool | uniformItemSizes() const |
| void | setUniformItemSizes(bool enable) |
viewMode : ViewMode
Esta propiedad contiene el modo de visualización de QListView.
Esta propiedad modificará las demás propiedades no definidas para que se ajusten al modo de visualización establecido. Las propiedades específicas de « QListView » que ya se hayan definido no se modificarán, a menos que se haya llamado a « clearPropertyFlags()».
Al establecer el modo de visualización, se habilitará o deshabilitará la función de arrastrar y soltar en función del movimiento seleccionado. Para ListMode, el movimiento predeterminado es Static (arrastrar y soltar deshabilitado); para IconMode, el movimiento predeterminado es Free (arrastrar y soltar habilitado).
Funciones de acceso:
| QListView::ViewMode | viewMode() const |
| void | setViewMode(QListView::ViewMode mode) |
Véase también isWrapping, spacing, gridSize, flow, movement y resizeMode.
wordWrap : bool
Esta propiedad define la política de ajuste de texto del elemento
Si esta propiedad tiene el valor « true », el texto del elemento se ajustará en los saltos de palabra cuando sea necesario; en caso contrario, no se ajustará en absoluto. Esta propiedad tiene el valor « false » de forma predeterminada.
Ten en cuenta que, aunque el ajuste de línea esté habilitado, la celda no se ampliará para dar cabida al texto. Se imprimirán puntos suspensivos para el texto que no pueda mostrarse, según la configuración de « textElideMode » de la vista.
Funciones de Access:
| bool | wordWrap() const |
| void | setWordWrap(bool on) |
Documentación de funciones de miembro
[explicit] QListView::QListView(QWidget *parent = nullptr)
Crea un nuevo QListView con el ` parent ` especificado para visualizar un modelo. Utiliza ` setModel()` para establecer el modelo.
[virtual noexcept] QListView::~QListView()
Echa a perder la vista.
void QListView::clearPropertyFlags()
Borra los indicadores de propiedad específicos de « QListView ». Véase viewMode.
Las propiedades heredadas de QAbstractItemView no se ven afectadas por los indicadores de propiedad. En concreto, dragEnabled y acceptsDrops se calculan mediante QListView al llamar a setMovement() o setViewMode().
[override virtual protected] void QListView::currentChanged(const QModelIndex ¤t, const QModelIndex &previous)
Reimplementa: QAbstractItemView::currentChanged(const QModelIndex ¤t, const QModelIndex &previous).
[override virtual protected] void QListView::dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight, const QList<int> &roles = QList<int>())
Reimplementa: QAbstractItemView::dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight, const QList<int> &roles).
[override virtual protected] void QListView::dragLeaveEvent(QDragLeaveEvent *e)
Reimplementa: QAbstractItemView::dragLeaveEvent(QDragLeaveEvent *event).
[override virtual protected] void QListView::dragMoveEvent(QDragMoveEvent *e)
Reimplementa: QAbstractItemView::dragMoveEvent(QDragMoveEvent *event).
[override virtual protected] void QListView::dropEvent(QDropEvent *event)
Reimplementa: QAbstractItemView::dropEvent(QDropEvent *event).
[override virtual protected] bool QListView::event(QEvent *e)
Reimplementa: ` QAbstractItemView::event(QEvent *event)`.
[override virtual protected] int QListView::horizontalOffset() const
Reimplementa: QAbstractItemView::horizontalOffset() const.
[override virtual] QModelIndex QListView::indexAt(const QPoint &p) const
Reimplementa: ` QAbstractItemView::indexAt(const QPoint &point) const`.
[signal] void QListView::indexesMoved(const QModelIndexList &indexes)
Esta señal se emite cuando se desplazan en la vista los « indexes » especificados.
[override virtual protected] void QListView::initViewItemOption(QStyleOptionViewItem *option) const
Reimplementa: ` QAbstractItemView::initViewItemOption(QStyleOptionViewItem *option) const`.
[override virtual protected] bool QListView::isIndexHidden(const QModelIndex &index) const
Reimplementa: ` QAbstractItemView::isIndexHidden(const QModelIndex &index) const`.
bool QListView::isRowHidden(int row) const
Devuelve « true » si el « row » está oculto; en caso contrario, devuelve « false ».
[override virtual protected] void QListView::mouseMoveEvent(QMouseEvent *e)
Reimplementa: QAbstractItemView::mouseMoveEvent(QMouseEvent *event).
[override virtual protected] void QListView::mouseReleaseEvent(QMouseEvent *e)
Reimplementa: QAbstractItemView::mouseReleaseEvent(QMouseEvent *event).
[override virtual protected] QModelIndex QListView::moveCursor(QAbstractItemView::CursorAction cursorAction, Qt::KeyboardModifiers modifiers)
Reimplementa: ` QAbstractItemView::moveCursor` (`QAbstractItemView::CursorAction cursorAction, Qt::KeyboardModifiers modifiers`).
[override virtual protected] void QListView::paintEvent(QPaintEvent *e)
Reimplementa: QAbstractScrollArea::paintEvent(QPaintEvent *event).
[protected] QRect QListView::rectForIndex(const QModelIndex &index) const
Devuelve el rectángulo del elemento situado en la posición index en el modelo. El rectángulo se expresa en coordenadas de contenido.
Véase también visualRect().
[override virtual protected] void QListView::resizeEvent(QResizeEvent *e)
Reimplementa: ` QAbstractItemView::resizeEvent(QResizeEvent *event)`.
[override virtual protected] void QListView::rowsAboutToBeRemoved(const QModelIndex &parent, int start, int end)
Reimplementa: ` QAbstractItemView::rowsAboutToBeRemoved` (const QModelIndex &parent, int start, int end).
[override virtual protected] void QListView::rowsInserted(const QModelIndex &parent, int start, int end)
Reimplementa: ` QAbstractItemView::rowsInserted` (const QModelIndex &parent, int start, int end).
[override virtual protected] void QListView::scrollContentsBy(int dx, int dy)
Reimplementa: QAbstractScrollArea::scrollContentsBy(int dx, int dy).
Desplaza el contenido de la vista mediante dx y dy.
[override virtual] void QListView::scrollTo(const QModelIndex &index, QAbstractItemView::ScrollHint hint = EnsureVisible)
Reimplementa: QAbstractItemView::scrollTo(const QModelIndex &index, QAbstractItemView::ScrollHint hint).
[override virtual protected] QModelIndexList QListView::selectedIndexes() const
Reimplementa: QAbstractItemView::selectedIndexes() const.
[override virtual protected] void QListView::selectionChanged(const QItemSelection &selected, const QItemSelection &deselected)
Reimplementa: QAbstractItemView::selectionChanged(const QItemSelection &selected, const QItemSelection &deselected).
[protected] void QListView::setPositionForIndex(const QPoint &position, const QModelIndex &index)
Establece la posición del contenido del elemento situado en index en el modelo en la posición indicada position. Si el modo de desplazamiento de la vista de lista es «Estático» o su modo de visualización es « ListView », esta función no tendrá ningún efecto.
[override virtual] void QListView::setRootIndex(const QModelIndex &index)
Reimplementa: QAbstractItemView::setRootIndex(const QModelIndex &index).
void QListView::setRowHidden(int row, bool hide)
Si hide es verdadero, se ocultará el row indicado; en caso contrario, se mostrará el row.
Véase también isRowHidden().
[override virtual protected] void QListView::setSelection(const QRect &rect, QItemSelectionModel::SelectionFlags command)
Reimplementa: QAbstractItemView::setSelection(const QRect &rect, QItemSelectionModel::SelectionFlags flags).
[override virtual protected] void QListView::startDrag(Qt::DropActions supportedActions)
Reimplementa: QAbstractItemView::startDrag(Qt::DropActions supportedActions).
[override virtual protected] void QListView::timerEvent(QTimerEvent *e)
Reimplementa: ` QAbstractItemView::timerEvent(QTimerEvent *event)`.
[override virtual protected] void QListView::updateGeometries()
Reimplementa: QAbstractItemView::updateGeometries().
[override virtual protected] int QListView::verticalOffset() const
Reimplementa: QAbstractItemView::verticalOffset() const.
[override virtual protected] QSize QListView::viewportSizeHint() const
Reimplementa: ` QAbstractItemView::viewportSizeHint()` const.
[override virtual] QRect QListView::visualRect(const QModelIndex &index) const
Reimplementa: ` QAbstractItemView::visualRect(const QModelIndex &index) const`.
[override virtual protected] QRegion QListView::visualRegionForSelection(const QItemSelection &selection) const
Reimplementa: ` QAbstractItemView::visualRegionForSelection(const QItemSelection &selection) const`.
Desde la versión 4.7, la región devuelta solo contiene rectángulos que se cruzan con la ventana gráfica (o que están incluidos en ella).
[override virtual protected] void QListView::wheelEvent(QWheelEvent *e)
Reimplementa: QAbstractScrollArea::wheelEvent(QWheelEvent *e).
© 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.