QTableWidget Class

The QTableWidget class provides a table of items. More…

List of all members, including inherited members

Public Functions

Public Slots

Signals

Reimplemented Protected Functions

Detailed Description

A table has rows and columns of cells, with a header for each: the horizontal header names the columns and the vertical one numbers the rows. A cell is empty, or has a QTableWidgetItem. The user clicks a cell, or moves with the arrow keys, to select it. The table scrolls when it is larger than its viewport:

QTableWidget *table = new QTableWidget(3, 2, window);
table->setHorizontalHeaderLabels({"Name", "Role"});
table->setItem(0, 0, new QTableWidgetItem("Ada"));
table->setItem(0, 1, new QTableWidgetItem("Engineer"));
connect(table, &QTableWidget::cellClicked, [](int row, int column) { qDebug() << row << column; });

The width of a column and the height of a row are the sizes of the sections of the headers: change them with setColumnWidth() and setRowHeight(), or let the user drag the edge of a header. An item can have a tool tip, which the table shows over its cell.

A table in the light color scheme with alternating row colors, a selected cell, a colored item and a wide column.

See also QTableWidgetItem, QHeaderView and QScrollArea.

Differences from Qt

Member Function Documentation

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

Constructs an empty table with the given parent.

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

Constructs a table of rows by columns empty cells with the given parent.

[override] QTableWidget::~QTableWidget()

Destroys the table, and the items in it.

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

This signal is emitted when the user clicks the cell at row and column.

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

This signal is emitted when the user double-clicks the cell at row and column.

[override, protected] void QTableWidget::changeEvent(QEvent *event)

Reimplements QAbstractItemView::changeEvent().

[slot] void QTableWidget::clear()

Removes and deletes every item, and the labels of the headers, and clears the selection. The size of the table and of its sections stays.

See also clearContents().

[slot] void QTableWidget::clearContents()

Removes and deletes every item, and clears the selection. The labels of the headers stay.

See also clear().

int QTableWidget::columnAt(int x) const

Returns the column at x, a position in the viewport, or -1 if there is none.

See also rowAt().

int QTableWidget::columnCount() const

Returns the number of columns.

See also setColumnCount().

int QTableWidget::columnWidth(int column) const

Returns the width of column in pixels.

See also setColumnWidth().

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

This signal is emitted when the current cell changes from (previousRow, previousColumn) to (currentRow, currentColumn). A cell that does not exist is -1.

int QTableWidget::currentColumn() const

Returns the column of the current cell, or -1 if there is none.

See also currentRow() and setCurrentCell().

QTableWidgetItem * QTableWidget::currentItem() const

Returns the current item, or nullptr if the current cell is empty or there is none.

See also setCurrentItem() and currentRow().

int QTableWidget::currentRow() const

Returns the row of the current cell, or -1 if there is none.

See also currentColumn() and setCurrentCell().

[override, protected] void QTableWidget::focusInEvent(QFocusEvent *event)

Reimplements QAbstractItemView::focusInEvent().

[override, protected] void QTableWidget::focusOutEvent(QFocusEvent *event)

Reimplements QAbstractItemView::focusOutEvent().

QHeaderView * QTableWidget::horizontalHeader() const

Returns the header of the columns.

See also verticalHeader().

void QTableWidget::insertColumn(int column)

Inserts an empty column at column, before the column that is there; columns that follow move to the right. column is brought into the range 0 to columnCount().

See also removeColumn() and setColumnCount().

void QTableWidget::insertRow(int row)

Inserts an empty row at row, before the row that is there; rows that follow move down. row is brought into the range 0 to rowCount().

See also removeRow() and setRowCount().

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

Returns the item at row and column, or nullptr if the cell is empty or there is no such cell.

See also setItem().

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

Returns the item at pos, a position in the viewport, or nullptr if the cell there is empty or there is none.

See also visualItemRect().

QTableWidgetItem * QTableWidget::itemAt(int x, int y) const

This is an overloaded function.

Returns the item at the position (x, y) in the viewport.

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

This signal is emitted when the user clicks item.

[signal] void QTableWidget::itemSelectionChanged()

This signal is emitted when the selection changes.

[override, protected] void QTableWidget::keyPressEvent(QKeyEvent *event)

Reimplements QAbstractItemView::keyPressEvent().

The arrow keys move the current cell by one, skipping cells that cannot be selected; Page Up and Page Down by the rows in view; Home and End go to the first and last cell of the row, and with Control to the first and last of the table. If there is no current cell, any of them selects the first one.

[override, protected] void QTableWidget::mouseDoubleClickEvent(QMouseEvent *event)

Reimplements QAbstractItemView::mouseDoubleClickEvent().

[override, protected] void QTableWidget::mousePressEvent(QMouseEvent *event)

Reimplements QAbstractItemView::mousePressEvent().

[override, protected] void QTableWidget::mouseReleaseEvent(QMouseEvent *event)

Reimplements QAbstractItemView::mouseReleaseEvent().

[override, protected] void QTableWidget::paintEvent(QPaintEvent *event)

Reimplements QAbstractItemView::paintEvent().

void QTableWidget::removeColumn(int column)

Removes the column column, and deletes its items. Does nothing if there is no such column.

See also insertColumn() and setColumnCount().

void QTableWidget::removeRow(int row)

Removes the row row, and deletes its items. Does nothing if there is no such row.

See also insertRow() and setRowCount().

void QTableWidget::resizeColumnsToContents()

Makes every column as wide as its widest text.

See also resizeColumnToContents().

void QTableWidget::resizeColumnToContents(int column)

Makes column as wide as its widest text, the label in the header included.

See also resizeColumnsToContents().

[override, protected] void QTableWidget::resizeEvent(QResizeEvent *event)

Reimplements QAbstractItemView::resizeEvent().

int QTableWidget::rowAt(int y) const

Returns the row at y, a position in the viewport, or -1 if there is none.

See also columnAt().

int QTableWidget::rowCount() const

Returns the number of rows.

See also setRowCount().

int QTableWidget::rowHeight(int row) const

Returns the height of row in pixels.

See also setRowHeight().

[override, protected] void QTableWidget::scrollContentsBy(int dx, int dy)

Reimplements QAbstractItemView::scrollContentsBy().

void QTableWidget::scrollToItem(const QTableWidgetItem *item)

Scrolls the table so that item is in view. Does nothing if item is not in this table.

See also setCurrentItem().

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

Returns the selected items: the current item if it is selected, none otherwise. An empty selected cell does not count.

See also currentItem().

[override, protected] void QTableWidget::selectionModeChanged()

Reimplements QAbstractItemView::selectionModeChanged().

The current cell is selected unless the mode is NoSelection.

void QTableWidget::setColumnCount(int columns)

Sets the number of columns to columns. New columns are empty; the items of columns that go are deleted.

See also columnCount(), insertColumn() and removeColumn().

void QTableWidget::setColumnWidth(int column, int width)

Sets the width of column to width pixels.

See also columnWidth().

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

Makes the cell at row and column the current cell, which selects it, and scrolls it into view. Does nothing if there is no such cell, or if its item cannot be selected.

See also currentRow() and currentColumn().

void QTableWidget::setCurrentItem(QTableWidgetItem *item)

Makes item the current item, which selects it, and scrolls it into view.

See also currentItem().

void QTableWidget::setHorizontalHeaderLabels(const QStringList &labels)

Sets the labels of the columns to labels, and makes the table have as many columns if it had fewer. A column that has no label is named with its number.

See also setVerticalHeaderLabels().

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

Puts item in the cell at row and column, and the table owns it. An item that was in the cell is deleted. An item that is in another cell or table moves. Does nothing, and deletes item, if there is no such cell.

See also item() and takeItem().

void QTableWidget::setRowCount(int rows)

Sets the number of rows to rows. New rows are empty; the items of rows that go are deleted.

See also rowCount(), insertRow() and removeRow().

void QTableWidget::setRowHeight(int row, int height)

Sets the height of row to height pixels.

See also rowHeight().

void QTableWidget::setShowGrid(bool show)

Sets whether the lines between the cells are drawn to show.

See also showGrid().

void QTableWidget::setVerticalHeaderLabels(const QStringList &labels)

Sets the labels of the rows to labels, and makes the table have as many rows if it had fewer. A row that has no label is named with its number.

See also setHorizontalHeaderLabels().

[override, protected] void QTableWidget::showEvent(QShowEvent *event)

Reimplements QAbstractItemView::showEvent().

bool QTableWidget::showGrid() const

Returns whether the lines between the cells are drawn. The default is true.

See also setShowGrid().

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

Removes the item at row and column from the table and returns it; the caller owns it. Returns nullptr if the cell is empty.

See also setItem().

QHeaderView * QTableWidget::verticalHeader() const

Returns the header of the rows.

See also horizontalHeader().

[override, protected] bool QTableWidget::viewportEvent(QEvent *event)

Reimplements QAbstractItemView::viewportEvent().

[override, protected] QSize QTableWidget::viewportSizeHint() const

Reimplements QAbstractItemView::viewportSizeHint().

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

Returns the rectangle of item in the viewport, whether it is in view or not. It is empty if item is not in this table.

See also itemAt().