En esta página

QTableWidget Class

La clase QTableWidget ofrece una vista de tabla basada en elementos con un modelo predeterminado. Más información...

Encabezado: #include <QTableWidget>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
Heredan: QTableView

Propiedades

Funciones públicas

QTableWidget(QWidget *parent = nullptr)
QTableWidget(int rows, int columns, QWidget *parent = nullptr)
virtual ~QTableWidget()
QWidget *cellWidget(int row, int column) const
void closePersistentEditor(QTableWidgetItem *item)
int column(const QTableWidgetItem *item) const
int columnCount() const
int currentColumn() const
QTableWidgetItem *currentItem() const
int currentRow() const
void editItem(QTableWidgetItem *item)
QList<QTableWidgetItem *> findItems(const QString &text, Qt::MatchFlags flags) const
QTableWidgetItem *horizontalHeaderItem(int column) const
QModelIndex indexFromItem(const QTableWidgetItem *item) const
bool isPersistentEditorOpen(QTableWidgetItem *item) const
QTableWidgetItem *item(int row, int column) const
QTableWidgetItem *itemAt(const QPoint &point) const
QTableWidgetItem *itemAt(int ax, int ay) const
QTableWidgetItem *itemFromIndex(const QModelIndex &index) const
const QTableWidgetItem *itemPrototype() const
QList<QTableWidgetItem *> items(const QMimeData *data) const
void openPersistentEditor(QTableWidgetItem *item)
void removeCellWidget(int row, int column)
int row(const QTableWidgetItem *item) const
int rowCount() const
QList<QTableWidgetItem *> selectedItems() const
QList<QTableWidgetSelectionRange> selectedRanges() const
void setCellWidget(int row, int column, QWidget *widget)
void setColumnCount(int columns)
void setCurrentCell(int row, int column)
void setCurrentCell(int row, int column, QItemSelectionModel::SelectionFlags command)
void setCurrentItem(QTableWidgetItem *item)
void setCurrentItem(QTableWidgetItem *item, QItemSelectionModel::SelectionFlags command)
void setHorizontalHeaderItem(int column, QTableWidgetItem *item)
void setHorizontalHeaderLabels(const QStringList &labels)
void setItem(int row, int column, QTableWidgetItem *item)
void setItemPrototype(const QTableWidgetItem *item)
void setRangeSelected(const QTableWidgetSelectionRange &range, bool select)
void setRowCount(int rows)
void setSupportedDragActions(Qt::DropActions actions)
void setVerticalHeaderItem(int row, QTableWidgetItem *item)
void setVerticalHeaderLabels(const QStringList &labels)
void sortItems(int column, Qt::SortOrder order = Qt::AscendingOrder)
Qt::DropActions supportedDragActions() const
QTableWidgetItem *takeHorizontalHeaderItem(int column)
QTableWidgetItem *takeItem(int row, int column)
QTableWidgetItem *takeVerticalHeaderItem(int row)
QTableWidgetItem *verticalHeaderItem(int row) const
int visualColumn(int logicalColumn) const
QRect visualItemRect(const QTableWidgetItem *item) const
int visualRow(int logicalRow) const

Ranuras públicas

void clear()
void clearContents()
void insertColumn(int column)
void insertRow(int row)
void removeColumn(int column)
void removeRow(int row)
void scrollToItem(const QTableWidgetItem *item, QAbstractItemView::ScrollHint hint = EnsureVisible)

Señales

void cellActivated(int row, int column)
void cellChanged(int row, int column)
void cellClicked(int row, int column)
void cellDoubleClicked(int row, int column)
void cellEntered(int row, int column)
void cellPressed(int row, int column)
void currentCellChanged(int currentRow, int currentColumn, int previousRow, int previousColumn)
void currentItemChanged(QTableWidgetItem *current, QTableWidgetItem *previous)
void itemActivated(QTableWidgetItem *item)
void itemChanged(QTableWidgetItem *item)
void itemClicked(QTableWidgetItem *item)
void itemDoubleClicked(QTableWidgetItem *item)
void itemEntered(QTableWidgetItem *item)
void itemPressed(QTableWidgetItem *item)
void itemSelectionChanged()

Funciones protegidas

virtual bool dropMimeData(int row, int column, const QMimeData *data, Qt::DropAction action)
virtual QMimeData *mimeData(const QList<QTableWidgetItem *> &items) const
virtual QStringList mimeTypes() const
virtual Qt::DropActions supportedDropActions() const

Funciones protegidas reimplementadas

virtual void dropEvent(QDropEvent *event) override
virtual bool event(QEvent *e) override

Descripción detallada

Tabla de meses e importes

Los widgets de tabla proporcionan funciones estándar de visualización de tablas para las aplicaciones. Los elementos de un QTableWidget los proporciona QTableWidgetItem.

Si deseas una tabla que utilice tu propio modelo de datos, debes utilizar QTableView en lugar de esta clase.

Los widgets de tabla se pueden crear con el número de filas y columnas que se necesite:

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

Alternativamente, las tablas se pueden crear sin un tamaño determinado y redimensionarlas posteriormente:

tableWidget = new QTableWidget(this);
tableWidget->setRowCount(10);
tableWidget->setColumnCount(5);

Los elementos se crean fuera de la tabla (sin widget padre) y se insertan en la tabla con ` setItem()`:

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

Si deseas habilitar la ordenación en tu widget de tabla, hazlo después de haberla rellenado con elementos; de lo contrario, la ordenación podría interferir con el orden de inserción (consulta setItem() para más detalles).

A las tablas se les pueden asignar encabezados tanto horizontales como verticales. La forma más sencilla de crear los encabezados es proporcionar una lista de cadenas a las funciones ` setHorizontalHeaderLabels()` y ` setVerticalHeaderLabels()`. Estas proporcionarán encabezados textuales sencillos para las columnas y filas de la tabla. Se pueden crear encabezados más sofisticados a partir de elementos de tabla existentes que, por lo general, se construyen fuera de la tabla. Por ejemplo, podemos crear un elemento de tabla con un icono y texto alineado, y utilizarlo como encabezado de una columna concreta:

QTableWidgetItem *cubesHeaderItem = new QTableWidgetItem(tr("Cubes"));
cubesHeaderItem->setIcon(QIcon(QPixmap(":/Images/cubed.png")));
cubesHeaderItem->setTextAlignment(Qt::AlignVCenter);

El número de filas de la tabla se puede obtener con rowCount(), y el número de columnas con columnCount(). La tabla se puede borrar con la función clear().

Véase también QTableWidgetItem, QTableView y Programación de modelos y vistas.

Documentación de propiedades

columnCount : int

Esta propiedad indica el número de columnas de la tabla

Por defecto, en el caso de una tabla creada sin especificar el número de filas ni de columnas, esta propiedad tiene un valor de 0.

Funciones de Access:

int columnCount() const
void setColumnCount(int columns)

rowCount : int

Esta propiedad contiene el número de filas de la tabla

Por defecto, en el caso de una tabla creada sin recuento de filas ni columnas, esta propiedad contiene el valor 0.

Funciones de Access:

int rowCount() const
void setRowCount(int rows)

[since 6.10] supportedDragActions : Qt::DropActions

Esta propiedad contiene las acciones de arrastre compatibles con esta vista

Esta enumeración se introdujo en Qt 6.10.

Funciones de acceso:

Qt::DropActions supportedDragActions() const
void setSupportedDragActions(Qt::DropActions actions)

Véase también Qt::DropActions y supportedDropActions().

Documentación de las funciones de miembro

[explicit] QTableWidget::QTableWidget(QWidget *parent = nullptr)

Crea una nueva vista de tabla con el « parent » indicado.

QTableWidget::QTableWidget(int rows, int columns, QWidget *parent = nullptr)

Crea una nueva vista de tabla con los valores indicados para ` rows ` y ` columns`, así como con el valor indicado para ` parent`.

[virtual noexcept] QTableWidget::~QTableWidget()

Elimina esto: QTableWidget.

[signal] void QTableWidget::cellActivated(int row, int column)

Esta señal se emite cuando se ha activado la celda especificada en row y column

[signal] void QTableWidget::cellChanged(int row, int column)

Esta señal se emite cada vez que cambian los datos del elemento de la celda especificada por row y column.

[signal] void QTableWidget::cellClicked(int row, int column)

Esta señal se emite cada vez que se hace clic en una celda de la tabla. Los parámetros « row » y « column » que se han especificado corresponden a la celda en la que se ha hecho clic.

[signal] void QTableWidget::cellDoubleClicked(int row, int column)

Esta señal se emite cada vez que se hace doble clic en una celda de la tabla. Los parámetros « row » y « column » que se especifican corresponden a la celda en la que se ha hecho doble clic.

[signal] void QTableWidget::cellEntered(int row, int column)

Esta señal se emite cuando el cursor del ratón entra en una celda. La celda se especifica mediante row y column.

Esta señal solo se emite cuando el seguimiento del ratón está activado, o cuando se pulsa un botón del ratón mientras se desplaza hacia un elemento.

[signal] void QTableWidget::cellPressed(int row, int column)

Esta señal se emite cada vez que se pulsa una celda de la tabla. Los parámetros « row » y « column » indican la celda que se ha pulsado.

QWidget *QTableWidget::cellWidget(int row, int column) const

Devuelve el widget que se muestra en la celda de las coordenadas row y column.

Nota: La tabla asume la propiedad del widget.

Véase también setCellWidget().

[slot] void QTableWidget::clear()

Elimina todos los elementos de la vista. Esto también eliminará todas las selecciones y los encabezados. Si no quieres eliminar los encabezados, utiliza QTableWidget::clearContents(). Las dimensiones de la tabla se mantienen iguales.

[slot] void QTableWidget::clearContents()

Elimina de la vista todos los elementos que no se encuentren en los encabezados. Esto también eliminará todas las selecciones. Las dimensiones de la tabla se mantienen iguales.

void QTableWidget::closePersistentEditor(QTableWidgetItem *item)

Cierra el editor persistente de « item ».

Véase también openPersistentEditor() y isPersistentEditorOpen().

int QTableWidget::column(const QTableWidgetItem *item) const

Devuelve la columna correspondiente a « item ».

int QTableWidget::columnCount() const

Devuelve el número de columnas.

Nota: Funcióngetter para la propiedad columnCount.

Véase también ` setColumnCount()`.

[signal] void QTableWidget::currentCellChanged(int currentRow, int currentColumn, int previousRow, int previousColumn)

Esta señal se emite cada vez que cambia la celda activa. La celda especificada por previousRow y previousColumn es la que tenía el foco anteriormente, mientras que la celda especificada por currentRow y currentColumn es la nueva celda activa.

int QTableWidget::currentColumn() const

Devuelve la columna del elemento actual.

Véase también currentRow() y setCurrentCell().

QTableWidgetItem *QTableWidget::currentItem() const

Devuelve el elemento actual.

Véase también setCurrentItem().

[signal] void QTableWidget::currentItemChanged(QTableWidgetItem *current, QTableWidgetItem *previous)

Esta señal se emite cada vez que cambia el elemento actual. El elemento « previous » es aquel que tenía el foco anteriormente, mientras que « current » es el nuevo elemento actual.

int QTableWidget::currentRow() const

Devuelve la fila del elemento actual.

Véase también currentColumn() y setCurrentCell().

[override virtual protected] void QTableWidget::dropEvent(QDropEvent *event)

Reimplementa: QTableView::dropEvent(QDropEvent *event).

[virtual protected] bool QTableWidget::dropMimeData(int row, int column, const QMimeData *data, Qt::DropAction action)

Gestiona el objeto ` data ` proporcionado por una operación de arrastrar y soltar que ha finalizado con el objeto ` action ` dado en los objetos ` row ` y ` column` especificados. Devuelve ` true ` si el modelo puede gestionar los datos y la acción; en caso contrario, devuelve ` false`.

Véase también supportedDropActions() y supportedDragActions.

void QTableWidget::editItem(QTableWidgetItem *item)

Comienza a editar el archivo « item » si es editable.

[override virtual protected] bool QTableWidget::event(QEvent *e)

Reimplementa: QAbstractItemView::event(QEvent *event).

QList<QTableWidgetItem *> QTableWidget::findItems(const QString &text, Qt::MatchFlags flags) const

Busca los elementos que coincidan con el « text » utilizando el « flags » indicado.

QTableWidgetItem *QTableWidget::horizontalHeaderItem(int column) const

Devuelve el elemento de encabezado horizontal de la columna, column, si se ha establecido alguno; en caso contrario, devuelve nullptr.

Véase también setHorizontalHeaderItem().

QModelIndex QTableWidget::indexFromItem(const QTableWidgetItem *item) const

Devuelve el objeto ` QModelIndex ` asociado al ` item` indicado.

Nota: En las versiones de Qt anteriores a la 5.10, esta función aceptaba un ` item` que no era de tipo `const `.

[slot] void QTableWidget::insertColumn(int column)

Inserta una columna vacía en la tabla en column.

[slot] void QTableWidget::insertRow(int row)

Inserta una fila vacía en la tabla en row.

bool QTableWidget::isPersistentEditorOpen(QTableWidgetItem *item) const

Devuelve si hay un editor persistente abierto para el elemento item.

Véase también openPersistentEditor() y closePersistentEditor().

QTableWidgetItem *QTableWidget::item(int row, int column) const

Devuelve el elemento correspondiente a « row » y « column » si se han establecido; de lo contrario, devuelve « nullptr ».

Véase también setItem().

[signal] void QTableWidget::itemActivated(QTableWidgetItem *item)

Esta señal se emite cuando se ha activado el « item » especificado.

QTableWidgetItem *QTableWidget::itemAt(const QPoint &point) const

Devuelve un puntero al elemento situado en la posición indicada point, o bien devuelve nullptr si point no está cubierto por ningún elemento del widget de tabla.

Véase también item().

QTableWidgetItem *QTableWidget::itemAt(int ax, int ay) const

Devuelve el elemento situado en la posición equivalente a QPoint(ax, ay) en el sistema de coordenadas del widget de tabla, o bien devuelve nullptr si el punto especificado no está cubierto por ningún elemento del widget de tabla.

Véase también item().

[signal] void QTableWidget::itemChanged(QTableWidgetItem *item)

Esta señal se emite cada vez que cambian los datos de item.

[signal] void QTableWidget::itemClicked(QTableWidgetItem *item)

Esta señal se emite cada vez que se hace clic en un elemento de la tabla. El objeto ` item ` especificado es el elemento en el que se ha hecho clic.

[signal] void QTableWidget::itemDoubleClicked(QTableWidgetItem *item)

Esta señal se emite cada vez que se hace doble clic en un elemento de la tabla. El objeto ` item ` especificado es el elemento sobre el que se ha hecho doble clic.

[signal] void QTableWidget::itemEntered(QTableWidgetItem *item)

Esta señal se emite cuando el cursor del ratón se sitúa sobre un elemento. El « item » es el elemento sobre el que se ha situado el cursor.

Esta señal solo se emite cuando el seguimiento del ratón está activado o cuando se pulsa un botón del ratón al desplazarse hacia un elemento.

QTableWidgetItem *QTableWidget::itemFromIndex(const QModelIndex &index) const

Devuelve un puntero al objeto « QTableWidgetItem » asociado al objeto « index » indicado.

[signal] void QTableWidget::itemPressed(QTableWidgetItem *item)

Esta señal se emite cada vez que se pulsa un elemento de la tabla. El item especificado es el elemento que se ha pulsado.

const QTableWidgetItem *QTableWidget::itemPrototype() const

Devuelve el prototipo del elemento utilizado por la tabla.

Véase también setItemPrototype().

[signal] void QTableWidget::itemSelectionChanged()

Esta señal se emite cada vez que cambia la selección.

Véase también selectedItems() y QTableWidgetItem::isSelected().

QList<QTableWidgetItem *> QTableWidget::items(const QMimeData *data) const

Devuelve una lista de punteros a los elementos contenidos en el objeto ` data `. Si el objeto no ha sido creado mediante una llamada a ` QTreeWidget ` en el mismo proceso, la lista estará vacía.

[virtual protected] QMimeData *QTableWidget::mimeData(const QList<QTableWidgetItem *> &items) const

Devuelve un objeto que contiene una descripción serializada de la lista de elementos especificada ` items`. El formato utilizado para describir los elementos se obtiene mediante la función ` mimeTypes()`.

Si la lista de elementos está vacía, se devuelve nullptr en lugar de una lista vacía serializada.

[virtual protected] QStringList QTableWidget::mimeTypes() const

Devuelve una lista de tipos MIME que se pueden utilizar para describir una lista de elementos de un «tablewidget».

Véase también ` mimeData()`.

void QTableWidget::openPersistentEditor(QTableWidgetItem *item)

Abre un editor para el archivo item. El editor permanece abierto tras la edición.

Véase también closePersistentEditor() y isPersistentEditorOpen().

void QTableWidget::removeCellWidget(int row, int column)

Elimina el conjunto de widgets de la celda indicada por row y column.

[slot] void QTableWidget::removeColumn(int column)

Elimina la columna « column » y todos sus elementos de la tabla.

[slot] void QTableWidget::removeRow(int row)

Elimina de la tabla la fila « row » y todos sus elementos.

int QTableWidget::row(const QTableWidgetItem *item) const

Devuelve la fila correspondiente a item.

int QTableWidget::rowCount() const

Devuelve el número de filas.

Nota: Funcióngetter para la propiedad rowCount.

Véase también setRowCount().

[slot] void QTableWidget::scrollToItem(const QTableWidgetItem *item, QAbstractItemView::ScrollHint hint = EnsureVisible)

Desplaza la vista si es necesario para garantizar que el elemento « item » quede visible. El parámetro « hint » especifica con mayor precisión dónde debe situarse el elemento « item » tras la operación.

QList<QTableWidgetItem *> QTableWidget::selectedItems() const

Devuelve una lista con todos los elementos seleccionados.

Esta función devuelve una lista de punteros al contenido de las celdas seleccionadas. Utiliza la función ` selectedIndexes()` para recuperar la selección completa, incluidas las celdas vacías.

Véase también selectedIndexes().

QList<QTableWidgetSelectionRange> QTableWidget::selectedRanges() const

Devuelve una lista con todos los rangos seleccionados.

Véase también QTableWidgetSelectionRange.

void QTableWidget::setCellWidget(int row, int column, QWidget *widget)

Establece que el widget « widget » especificado se muestre en la celda de las coordenadas « row » y « column » indicadas, transfiriendo la propiedad del widget a la tabla.

Si el widget de celda A se sustituye por el widget de celda B, el widget de celda A se eliminará. Por ejemplo, en el fragmento de código que aparece a continuación, el objeto QLineEdit se eliminará.

setCellWidget(row, column, new QLineEdit);
...
setCellWidget(row, column, new QTextEdit);

Véase también cellWidget().

void QTableWidget::setColumnCount(int columns)

Establece el número de columnas en el modelo de esta tabla en ` columns`. Si este valor es inferior a ` columnCount()`, se descartan los datos de las columnas no deseadas.

Nota: Funciónde asignación para la propiedad columnCount.

Véase también columnCount() y setRowCount().

void QTableWidget::setCurrentCell(int row, int column)

Establece la celda actual como la celda situada en la posición (row, column).

Dependiendo del valor actual de selection mode, la celda también puede quedar seleccionada.

Véanse también setCurrentItem(), currentRow() y currentColumn().

void QTableWidget::setCurrentCell(int row, int column, QItemSelectionModel::SelectionFlags command)

Establece la celda actual como la celda situada en la posición (row, column), utilizando el command indicado.

Véanse también setCurrentItem(), currentRow() y currentColumn().

void QTableWidget::setCurrentItem(QTableWidgetItem *item)

Establece el elemento actual como « item ».

A menos que el modo de selección sea « NoSelection », el elemento también queda seleccionado.

Véase también currentItem() y setCurrentCell().

void QTableWidget::setCurrentItem(QTableWidgetItem *item, QItemSelectionModel::SelectionFlags command)

Establece el elemento actual como « item », utilizando el « command » indicado.

Véanse también currentItem() y setCurrentCell().

void QTableWidget::setHorizontalHeaderItem(int column, QTableWidgetItem *item)

Establece el elemento de encabezado horizontal de la columna column como item. Si es necesario, se aumenta el número de columnas para que quepa el elemento. Se elimina el elemento de encabezado anterior (si lo había).

Véase también horizontalHeaderItem().

void QTableWidget::setHorizontalHeaderLabels(const QStringList &labels)

Establece las etiquetas horizontales de los encabezados utilizando ` labels`.

void QTableWidget::setItem(int row, int column, QTableWidgetItem *item)

Establece el elemento correspondiente a row y column en item.

La tabla asume la propiedad del elemento.

Ten en cuenta que, si la ordenación está habilitada (véase sortingEnabled) y column es la columna de ordenación actual, row se moverá a la posición ordenada determinada por item.

Si desea establecer varios elementos de una fila concreta (por ejemplo, llamando a setItem() en un bucle), es posible que le convenga desactivar la ordenación antes de hacerlo y volver a activarla después; esto le permitirá utilizar el mismo argumento row para todos los elementos de la misma fila (es decir, setItem() no moverá la fila).

Véanse también item() y takeItem().

void QTableWidget::setItemPrototype(const QTableWidgetItem *item)

Establece el prototipo de elemento de la tabla en el valor especificado item.

El widget de tabla utilizará la función de clonación del prototipo de elemento cuando necesite crear un nuevo elemento de la tabla. Por ejemplo, cuando el usuario está editando una celda vacía. Esto resulta útil cuando se dispone de una subclase de ` QTableWidgetItem ` y se quiere garantizar que ` QTableWidget ` cree instancias de dicha subclase.

La tabla asume la propiedad del prototipo.

Véase también itemPrototype().

void QTableWidget::setRangeSelected(const QTableWidgetSelectionRange &range, bool select)

Activa o desactiva la opción « range » ( ) en función de « select » ( ).

void QTableWidget::setRowCount(int rows)

Establece el número de filas del modelo de esta tabla en ` rows`. Si este valor es inferior a ` rowCount()`, se descartan los datos de las filas no deseadas.

Nota: Funciónde asignación para la propiedad rowCount.

Véase también rowCount() y setColumnCount().

void QTableWidget::setVerticalHeaderItem(int row, QTableWidgetItem *item)

Establece el elemento de encabezado vertical de la fila « row » en « item ».

Véase también verticalHeaderItem().

void QTableWidget::setVerticalHeaderLabels(const QStringList &labels)

Establece las etiquetas verticales de los encabezados utilizando « labels ».

void QTableWidget::sortItems(int column, Qt::SortOrder order = Qt::AscendingOrder)

Ordena todas las filas del widget de tabla según column y order.

[virtual protected] Qt::DropActions QTableWidget::supportedDropActions() const

Devuelve las acciones de arrastrar y soltar compatibles con esta vista.

Véase también Qt::DropActions, supportedDragActions y dropMimeData().

QTableWidgetItem *QTableWidget::takeHorizontalHeaderItem(int column)

Elimina el elemento horizontal del encabezado situado en column del encabezado sin borrarlo.

QTableWidgetItem *QTableWidget::takeItem(int row, int column)

Elimina de la tabla los elementos de row y column sin borrarlos.

QTableWidgetItem *QTableWidget::takeVerticalHeaderItem(int row)

Elimina el elemento vertical del encabezado situado en row del encabezado sin borrarlo.

QTableWidgetItem *QTableWidget::verticalHeaderItem(int row) const

Devuelve el elemento de encabezado vertical correspondiente a la fila row.

Véase también setVerticalHeaderItem().

int QTableWidget::visualColumn(int logicalColumn) const

Devuelve la columna visual del objeto ` logicalColumn` indicado.

QRect QTableWidget::visualItemRect(const QTableWidgetItem *item) const

Devuelve el rectángulo de la ventana gráfica que ocupa el elemento en item.

int QTableWidget::visualRow(int logicalRow) const

Devuelve la fila visual del objeto ` logicalRow` indicado.

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