QListView Class
La clase QListView proporciona una vista de lista o icono en un modelo. Más...
| Cabecera: | #include <QListView> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets)target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| Hereda: | 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
Un QListView presenta 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 anteriormente eran proporcionadas por las clases QListBox y QIconView, pero utilizando el enfoque más flexible proporcionado por la arquitectura modelo/vista de Qt.
La clase QListView es una de las Clases Modelo/Vista y forma parte del marco modelo/vista de Qt.
Esta vista no muestra cabeceras horizontales o verticales; para mostrar una lista de elementos con una cabecera horizontal, utilice QTreeView en su lugar.
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 pueden mostrarse 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 de un gestor de archivos. Por defecto, la vista de lista está 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 disponen en la dirección especificada por la función flow() de la vista de lista. Los elementos pueden estar fijos en su lugar o moverse, dependiendo del estado de la vista movement().
Si los elementos del modelo no pueden disponerse completamente en la dirección del flujo, pueden envolverse en el límite del widget de la vista; esto depende de isWrapping(). Esta propiedad es útil cuando los elementos están siendo representados por una vista de iconos.
Las propiedades resizeMode() y layoutMode() regulan cómo y cuándo se disponen los elementos. Los elementos se espacian según su spacing(), y pueden existir dentro de una rejilla nocional de tamaño especificado por gridSize(). Los elementos pueden representarse como iconos grandes o pequeños en función de su iconSize().
Mejorar el rendimiento
Es posible dar a la vista pistas sobre los datos que está manejando para mejorar su rendimiento al mostrar un gran número de elementos. Un enfoque que puede adoptarse para las vistas que pretenden mostrar elementos con tamaños iguales es establecer la propiedad uniformItemSizes a true.
Ver también Clases de Vistas, QTreeView, QTableView, y QListWidget.
Documentación de 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 a abajo. |
enum QListView::LayoutMode
| Constante | Valor | Descripción |
|---|---|---|
QListView::SinglePass | 0 | Los artículos se colocan todos a la vez. |
QListView::Batched | 1 | Los elementos se colocan en lotes de batchSize elementos. |
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 cuando se mueven; véase setGridSize(). |
enum QListView::ResizeMode
| Constante | Valor | Descripción |
|---|---|---|
QListView::Fixed | 0 | Los elementos sólo se dispondrán la primera vez que se muestre la vista. |
QListView::Adjust | 1 | Los elementos se dispondrán cada vez que se cambie el tamaño de la vista. |
enum QListView::ViewMode
| Constante | Valor | Descripción |
|---|---|---|
QListView::ListMode | 0 | Los elementos se colocan utilizando el flujo TopToBottom, con tamaño pequeño y movimiento estático. |
QListView::IconMode | 1 | Los elementos se colocan utilizando el flujo LeftToRight, con tamaño grande y movimiento libre. |
Documentación de propiedades
batchSize : int
Esta propiedad contiene el número de artículos dispuestos en cada lote si layoutMode se establece en Batched.
El valor por defecto es 100.
Funciones de acceso:
| int | batchSize() const |
| void | setBatchSize(int batchSize) |
flow : Flow
Esta propiedad indica la dirección en la que deben colocarse los elementos.
Si esta propiedad es LeftToRight, los elementos se dispondrán de izquierda a derecha. Si la propiedad isWrapping es true, la disposición se envolverá cuando alcance el lado derecho del área visible. Si esta propiedad es TopToBottom, los elementos se dispondrán desde la parte superior del área visible, envolviéndose cuando llegue a la parte inferior.
Establecer esta propiedad cuando la vista es visible hará que los elementos se desplieguen de nuevo.
Por defecto, esta propiedad es TopToBottom.
Funciones de acceso:
| QListView::Flow | flow() const |
| void | setFlow(QListView::Flow flow) |
Véase también viewMode.
gridSize : QSize
Esta propiedad contiene el tamaño de la rejilla de disposición
Esta propiedad es el tamaño de la rejilla en la que se disponen los elementos. El valor por defecto es un tamaño vacío, lo que significa que no hay rejilla y la disposición no se realiza en una rejilla. Establecer esta propiedad a un tamaño no vacío activa la disposición en cuadrícula. (Cuando una disposición en rejilla está en vigor la propiedad spacing es ignorada).
Establecer esta propiedad cuando la vista es visible hará que los elementos se vuelvan a maquetar.
Funciones de acceso:
| QSize | gridSize() const |
| void | setGridSize(const QSize &size) |
Véase también viewMode.
isWrapping : bool
Esta propiedad indica si el diseño de los ítems debe ajustarse.
Esta propiedad indica si el diseño debe envolverse cuando no hay más espacio en el área visible. El punto en el que el diseño se envuelve depende de la propiedad flow.
Establecer esta propiedad cuando la vista es visible hará que los elementos se vuelvan a distribuir.
Por defecto, esta propiedad es false.
Funciones de acceso:
| bool | isWrapping() const |
| void | setWrapping(bool enable) |
Véase también viewMode.
itemAlignment : Qt::Alignment
Esta propiedad contiene la alineación de cada elemento en su celda.
Sólo se admite en ListMode con flujo TopToBottom y con la opción de ajuste activada. La alineación por defecto es 0, lo que significa que un elemento llena su celda por completo.
Funciones de acceso:
| Qt::Alignment | itemAlignment() const |
| void | setItemAlignment(Qt::Alignment alignment) |
layoutMode : LayoutMode
determina si la disposición de los elementos debe ser inmediata o retardada.
Esta propiedad contiene el modo de disposición de los elementos. Cuando el modo es SinglePass (el predeterminado), los elementos se disponen 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 instantáneamente con los elementos visibles mientras se dispone el resto.
Funciones de acceso:
| QListView::LayoutMode | layoutMode() const |
| void | setLayoutMode(QListView::LayoutMode mode) |
Véase también viewMode.
modelColumn : int
Esta propiedad contiene la columna del modelo que es visible
Por defecto, esta propiedad contiene 0, indicando 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 ítems se pueden mover libremente, si están fijados a una rejilla o si no se pueden mover en absoluto.
Esta propiedad determina cómo el usuario puede mover los elementos en la vista. Static significa que los elementos no pueden ser movidos por el usuario. Free significa que el usuario puede arrastrar y soltar los elementos a cualquier posición en la vista. Snap significa que el usuario puede arrastrar y soltar los elementos, pero sólo a las posiciones en una rejilla nocional significada por la propiedad gridSize.
Establecer esta propiedad cuando la vista es visible hará que los elementos se dispongan de nuevo.
Por defecto, esta propiedad se establece en Static.
Funciones de acceso:
| QListView::Movement | movement() const |
| void | setMovement(QListView::Movement movement) |
Ver también gridSize, resizeMode, y viewMode.
resizeMode : ResizeMode
Esta propiedad indica si los elementos se colocan de nuevo cuando se redimensiona la vista.
Si el valor de esta propiedad es Adjust, los ítems se dispondrán de nuevo cuando se redimensione la vista. Si el valor es Fixed, los ítems no se dispondrán cuando se redimensione la vista.
Por defecto, esta propiedad tiene el valor Fixed.
Funciones de acceso:
| QListView::ResizeMode | resizeMode() const |
| void | setResizeMode(QListView::ResizeMode mode) |
Ver también movement, gridSize, y viewMode.
selectionRectVisible : bool
si el rectángulo de selección debe ser visible
Si esta propiedad es true entonces el rectángulo de selección será visible; en caso contrario estará oculto.
Nota: El rectángulo de selección sólo será visible si el modo de selección está en un modo en el que se puede seleccionar más de un elemento; es decir, no dibujará un rectángulo de selección si el modo de selección es QAbstractItemView::SingleSelection.
Por defecto, esta propiedad es false.
Funciones de acceso:
| bool | isSelectionRectVisible() const |
| void | setSelectionRectVisible(bool show) |
spacing : int
Esta propiedad contiene el espacio alrededor de los elementos de la presentación
Esta propiedad es el tamaño del espacio vacío que se rellena alrededor de un elemento en la presentación.
Establecer esta propiedad cuando la vista es visible hará que los elementos se vuelvan a disponer.
Por defecto, esta propiedad contiene un valor de 0.
Funciones de acceso:
| int | spacing() const |
| void | setSpacing(int space) |
Véase también viewMode.
uniformItemSizes : bool
Esta propiedad indica si todos los elementos de la lista tienen el mismo tamaño.
Esta propiedad sólo debe establecerse a true si se garantiza que todos los elementos de la vista tienen el mismo tamaño. Esto permite a la vista realizar algunas optimizaciones por motivos de rendimiento.
Por defecto, esta propiedad es false.
Funciones de acceso:
| bool | uniformItemSizes() const |
| void | setUniformItemSizes(bool enable) |
viewMode : ViewMode
Esta propiedad contiene el modo de vista de QListView.
Esta propiedad cambiará las otras propiedades no establecidas para que se ajusten al modo de vista establecido. QListView-las propiedades específicas que ya han sido establecidas no serán cambiadas, a menos que se haya llamado a clearPropertyFlags().
Al establecer el modo de vista se activará o desactivará la función de arrastrar y soltar en función del movimiento seleccionado. Para ListMode, el movimiento por defecto es Static (arrastrar y soltar desactivado); para IconMode, el movimiento por defecto es Free (arrastrar y soltar activado).
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 contiene la política de ajuste de palabras del texto del elemento.
Si esta propiedad es true entonces el texto del elemento se envuelve cuando es necesario en los saltos de palabra; en caso contrario no se envuelve en absoluto. Esta propiedad es false por defecto.
Tenga en cuenta que incluso si se activa el ajuste, la celda no se expandirá para dejar espacio para el texto. Se imprimirán elipsis para el texto que no pueda mostrarse, de acuerdo con la vista textElideMode.
Funciones de acceso:
| bool | wordWrap() const |
| void | setWordWrap(bool on) |
Documentación de funciones miembro
[explicit] QListView::QListView(QWidget *parent = nullptr)
Crea un nuevo QListView con el parent dado para ver un modelo. Utilice setModel() para establecer el modelo.
[virtual noexcept] QListView::~QListView()
Destruye la vista.
void QListView::clearPropertyFlags()
Borra los indicadores de propiedad específicos de QListView. Véase viewMode.
Las propiedades heredadas de QAbstractItemView no están cubiertas por los indicadores de propiedades. Específicamente, dragEnabled y acceptsDrops son computadas por QListView cuando se llama 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 los indexes especificados se mueven en la vista.
[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 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 modificadores).
[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 en la posición index en el modelo. El rectángulo está 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 inicio, int fin).
[override virtual protected] void QListView::rowsInserted(const QModelIndex &parent, int start, int end)
Reimplementa: QAbstractItemView::rowsInserted(const QModelIndex &parent, int inicio, int fin).
[override virtual protected] void QListView::scrollContentsBy(int dx, int dy)
Reimplementa: QAbstractScrollArea::scrollContentsBy(int dx, int dy).
Desplaza el contenido de la vista por 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 en index en el modelo al position dado. Si el modo de movimiento de la vista de lista es Estático o su modo de vista 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 dado; 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 4.7, la región devuelta sólo contiene rectángulos que intersecan (o están incluidos en) la ventana gráfica.
[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.
