En esta página

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:

QHelpIndexWidget, ` QListWidget` y QUndoView

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 &current, 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

Lista de iconos meteorológicos

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

ConstanteValorDescripción
QListView::LeftToRight0Los elementos se disponen en la vista de izquierda a derecha.
QListView::TopToBottom1Los elementos se disponen en la vista de arriba abajo.

enum QListView::LayoutMode

ConstanteValorDescripción
QListView::SinglePass0Los elementos se disponen todos a la vez.
QListView::Batched1Los artículos se distribuyen en lotes de batchSize artículos.

Véase también « batchSize ».

enum QListView::Movement

ConstanteValorDescripción
QListView::Static0El usuario no puede mover los elementos.
QListView::Free1El usuario puede mover los elementos libremente.
QListView::Snap2Los elementos se ajustan a la cuadrícula especificada al moverlos; véase setGridSize().

enum QListView::ResizeMode

ConstanteValorDescripción
QListView::Fixed0Los elementos solo se distribuirán la primera vez que se muestre la vista.
QListView::Adjust1Los elementos se distribuirán cada vez que se cambie el tamaño de la vista.

enum QListView::ViewMode

ConstanteValorDescripción
QListView::ListMode0Los artículos se disponen siguiendo un flujo « TopToBottom », con tamaño «Pequeño» y movimiento «Estático».
QListView::IconMode1Los 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 &current, const QModelIndex &previous)

Reimplementa: QAbstractItemView::currentChanged(const QModelIndex &current, 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.