Contents

• Properties
• Public Functions
• Reimplemented Public Functions
• Public Slots
• Reimplemented Protected Functions
• Protected Slots
• Detailed Description
• Navigation
• Visual Appearance
• Coordinate Systems
• Styles

Detailed Description

TheQTableView class provides a default model/view implementation of a table view.

AQTableView implements a table view that displays items from a model. This class is used to provide standard tables that were previously provided by theQTable class, but using the more flexible approach provided by Qt's model/view architecture.

TheQTableView class is one of theModel/View Classes and is part of Qt'smodel/view framework.

QTableView implements the interfaces defined by theQAbstractItemView class to allow it to display data provided by models derived from theQAbstractItemModel class.

Navigation

You can navigate the cells in the table by clicking on a cell with the mouse, or by using the arrow keys. BecauseQTableView enablestabKeyNavigation by default, you can also hit Tab and Backtab to move from cell to cell.

Visual Appearance

The table has a vertical header that can be obtained using theverticalHeader() function, and a horizontal header that is available through thehorizontalHeader() function. The height of each row in the table can be found by usingrowHeight(); similarly, the width of columns can be found usingcolumnWidth(). Since both of these are plain widgets, you can hide either of them using theirhide() functions.

Rows and columns can be hidden and shown withhideRow(),hideColumn(),showRow(), andshowColumn(). They can be selected withselectRow() andselectColumn(). The table will show a grid depending on theshowGrid property.

The items shown in a table view, like those in the other item views, are rendered and edited using standarddelegates. However, for some tasks it is sometimes useful to be able to insert widgets in a table instead. Widgets are set for particular indexes with thesetIndexWidget() function, and later retrieved withindexWidget().

By default, the cells in a table do not expand to fill the available space. You can make the cells fill the available space by stretching the last header section. Access the relevant header usinghorizontalHeader() orverticalHeader() and set the header'sstretchLastSection property. To distribute the available space according to the space requirement of each column or row, call the view'sresizeColumnsToContents() orresizeRowsToContents() functions.

Coordinate Systems

For some specialized forms of tables it is useful to be able to convert between row and column indexes and widget coordinates. TherowAt() function provides the y-coordinate within the view of the specified row; the row index can be used to obtain a corresponding y-coordinate withrowViewportPosition(). ThecolumnAt() andcolumnViewportPosition() functions provide the equivalent conversion operations between x-coordinates and column indexes.

Styles

QTableView is styled appropriately for each platform. The following images show how it looks on three different platforms. Go to theQt Widget Gallery to see its appearance in other styles.

AWindows XP style table view.	AMacintosh style table view.	APlastique style table view.

Property Documentation

cornerButtonEnabled :bool

This property holds whether the button in the top-left corner is enabled.

If this property is true then button in the top-left corner of the table view is enabled. Clicking on this button will select all the cells in the table view.

This property is true by default.

This property was introduced in Qt 4.3.

Access functions:

gridStyle :Qt::PenStyle

This property holds the pen style used to draw the grid.

This property holds the style used when drawing the grid (seeshowGrid).

Access functions:

showGrid :bool

This property holds whether the grid is shown.

If this property is true a grid is drawn for the table; if the property is false, no grid is drawn. The default value is true.

Access functions:

sortingEnabled :bool

This property holds whether sorting is enabled.

If this property is true, sorting is enabled for the table. If this property is false, sorting is not enabled. The default value is false.

Note:. Setting the property to true with setSortingEnabled() immediately triggers a call tosortByColumn() with the current sort section and order.

This property was introduced in Qt 4.2.

Access functions:

See alsosortByColumn().

wordWrap :bool

This property holds the item text word-wrapping policy.

If this property is true then the item text is wrapped where necessary at word-breaks; otherwise it is not wrapped at all. This property is true by default.

Note that even of wrapping is enabled, the cell will not be expanded to fit all text. Ellipsis will be inserted according to the currenttextElideMode.

This property was introduced in Qt 4.3.

Access functions:

Member Function Documentation

QTableView::QTableView(QWidget * parent = 0)

Constructs a table view with aparent to represent the data.

See alsoQAbstractItemModel.

QTableView::~QTableView()

Destroys the table view.

void QTableView::clearSpans()

Removes all row and column spans in the table view.

This function was introduced in Qt 4.4.

See alsosetSpan().

int QTableView::columnAt(int x) const

Returns the column in which the given x-coordinate,x, in contents coordinates is located.

Note:This function returns -1 if the given coordinate is not valid (has no column).

See alsorowAt().

[protected slot]void QTableView::columnCountChanged(int oldCount,int newCount)

This slot is called whenever columns are added or deleted. The previous number of columns is specified byoldCount, and the new number of columns is specified bynewCount.

[protected slot]void QTableView::columnMoved(int column,int oldIndex,int newIndex)

This slot is called to change the index of the givencolumn in the table view. The old index is specified byoldIndex, and the new index bynewIndex.

See alsorowMoved().

[protected slot]void QTableView::columnResized(int column,int oldWidth,int newWidth)

This slot is called to change the width of the givencolumn. The old width is specified byoldWidth, and the new width bynewWidth.

See alsorowResized().

int QTableView::columnSpan(int row,int column) const

Returns the column span of the table element at (row,column). The default is 1.

This function was introduced in Qt 4.2.

See alsosetSpan() androwSpan().

int QTableView::columnViewportPosition(int column) const

Returns the x-coordinate in contents coordinates of the givencolumn.

int QTableView::columnWidth(int column) const

Returns the width of the givencolumn.

See alsosetColumnWidth(),resizeColumnToContents(), androwHeight().

[virtual protected]void QTableView::currentChanged(constQModelIndex & current, constQModelIndex & previous)

Reimplemented fromQAbstractItemView::currentChanged().

[slot]void QTableView::hideColumn(int column)

Hide the givencolumn.

See alsoshowColumn() andhideRow().

[slot]void QTableView::hideRow(int row)

Hide the givenrow.

See alsoshowRow() andhideColumn().

QHeaderView * QTableView::horizontalHeader() const

Returns the table view's horizontal header.

See alsosetHorizontalHeader(),verticalHeader(), andQAbstractItemModel::headerData().

[virtual protected]int QTableView::horizontalOffset() const

Reimplemented fromQAbstractItemView::horizontalOffset().

Returns the horizontal offset of the items in the table view.

Note that the table view uses the horizontal header section positions to determine the positions of columns in the view.

See alsoverticalOffset().

[virtual]QModelIndex QTableView::indexAt(constQPoint & pos) const

Reimplemented fromQAbstractItemView::indexAt().

Returns the index position of the model item corresponding to the table item at positionpos in contents coordinates.

bool QTableView::isColumnHidden(int column) const

Returns true if the givencolumn is hidden; otherwise returns false.

See alsoisRowHidden().

[virtual protected]bool QTableView::isIndexHidden(constQModelIndex & index) const

Reimplemented fromQAbstractItemView::isIndexHidden().

bool QTableView::isRowHidden(int row) const

Returns true if the givenrow is hidden; otherwise returns false.

See alsoisColumnHidden().

[virtual protected]QModelIndex QTableView::moveCursor(CursorAction cursorAction,Qt::KeyboardModifiers modifiers)

Reimplemented fromQAbstractItemView::moveCursor().

Moves the cursor in accordance with the givencursorAction, using the information provided by themodifiers.

See alsoQAbstractItemView::CursorAction.

[virtual protected]void QTableView::paintEvent(QPaintEvent * event)

Reimplemented fromQWidget::paintEvent().

Paints the table on receipt of the given paint eventevent.

[slot]void QTableView::resizeColumnToContents(int column)

Resizes the givencolumn based on the size hints of the delegate used to render each item in the column.

Note:Only visible columns will be resized. ReimplementsizeHintForColumn() to resize hidden columns as well.

[slot]void QTableView::resizeColumnsToContents()

Resizes all columns based on the size hints of the delegate used to render each item in the columns.

[slot]void QTableView::resizeRowToContents(int row)

Resizes the givenrow based on the size hints of the delegate used to render each item in the row.

[slot]void QTableView::resizeRowsToContents()

Resizes all rows based on the size hints of the delegate used to render each item in the rows.

int QTableView::rowAt(int y) const

Returns the row in which the given y-coordinate,y, in contents coordinates is located.

Note:This function returns -1 if the given coordinate is not valid (has no row).

See alsocolumnAt().

[protected slot]void QTableView::rowCountChanged(int oldCount,int newCount)

This slot is called whenever rows are added or deleted. The previous number of rows is specified byoldCount, and the new number of rows is specified bynewCount.

int QTableView::rowHeight(int row) const

Returns the height of the givenrow.

See alsosetRowHeight(),resizeRowToContents(), andcolumnWidth().

[protected slot]void QTableView::rowMoved(int row,int oldIndex,int newIndex)

This slot is called to change the index of the givenrow in the table view. The old index is specified byoldIndex, and the new index bynewIndex.

See alsocolumnMoved().

[protected slot]void QTableView::rowResized(int row,int oldHeight,int newHeight)

This slot is called to change the height of the givenrow. The old height is specified byoldHeight, and the new height bynewHeight.

See alsocolumnResized().

int QTableView::rowSpan(int row,int column) const

Returns the row span of the table element at (row,column). The default is 1.

This function was introduced in Qt 4.2.

See alsosetSpan() andcolumnSpan().

int QTableView::rowViewportPosition(int row) const

Returns the y-coordinate in contents coordinates of the givenrow.

[slot]void QTableView::selectColumn(int column)

Selects the givencolumn in the table view if the currentSelectionMode andSelectionBehavior allows columns to be selected.

See alsoselectRow().

[slot]void QTableView::selectRow(int row)

Selects the givenrow in the table view if the currentSelectionMode andSelectionBehavior allows rows to be selected.

See alsoselectColumn().

[virtual protected]QModelIndexList QTableView::selectedIndexes() const

Reimplemented fromQAbstractItemView::selectedIndexes().

[virtual protected]void QTableView::selectionChanged(constQItemSelection & selected, constQItemSelection & deselected)

Reimplemented fromQAbstractItemView::selectionChanged().

void QTableView::setColumnHidden(int column,bool hide)

Ifhide is true the givencolumn will be hidden; otherwise it will be shown.

See alsoisColumnHidden() andsetRowHidden().

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

Sets the width of the givencolumn to bewidth.

This function was introduced in Qt 4.1.

See alsocolumnWidth().

void QTableView::setHorizontalHeader(QHeaderView * header)

Sets the widget to use for the horizontal header toheader.

See alsohorizontalHeader() andsetVerticalHeader().

[virtual]void QTableView::setModel(QAbstractItemModel * model)

Reimplemented fromQAbstractItemView::setModel().

[virtual]void QTableView::setRootIndex(constQModelIndex & index)

Reimplemented fromQAbstractItemView::setRootIndex().

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

Sets the height of the givenrow to beheight.

This function was introduced in Qt 4.1.

See alsorowHeight().

void QTableView::setRowHidden(int row,bool hide)

Ifhide is truerow will be hidden, otherwise it will be shown.

See alsoisRowHidden() andsetColumnHidden().

[virtual protected]void QTableView::setSelection(constQRect & rect,QItemSelectionModel::SelectionFlags flags)

Reimplemented fromQAbstractItemView::setSelection().

Selects the items within the givenrect and in accordance with the specified selectionflags.

[virtual]void QTableView::setSelectionModel(QItemSelectionModel * selectionModel)

Reimplemented fromQAbstractItemView::setSelectionModel().

void QTableView::setSpan(int row,int column,int rowSpanCount,int columnSpanCount)

Sets the span of the table element at (row,column) to the number of rows and columns specified by (rowSpanCount,columnSpanCount).

This function was introduced in Qt 4.2.

See alsorowSpan() andcolumnSpan().

void QTableView::setVerticalHeader(QHeaderView * header)

Sets the widget to use for the vertical header toheader.

See alsoverticalHeader() andsetHorizontalHeader().

[slot]void QTableView::showColumn(int column)

Show the givencolumn.

See alsohideColumn() andshowRow().

[slot]void QTableView::showRow(int row)

Show the givenrow.

See alsohideRow() andshowColumn().

[virtual protected]int QTableView::sizeHintForColumn(int column) const

Reimplemented fromQAbstractItemView::sizeHintForColumn().

Returns the size hint for the givencolumn's width or -1 if there is no model.

If you need to set the width of a given column to a fixed value, callQHeaderView::resizeSection() on the table's horizontal header.

If you reimplement this function in a subclass, note that the value you return will be used whenresizeColumnToContents() orQHeaderView::resizeSections() is called. If a larger column width is required by either the horizontal header or the item delegate, the larger width will be used instead.

See alsoQWidget::sizeHint andhorizontalHeader().

[virtual protected]int QTableView::sizeHintForRow(int row) const

Reimplemented fromQAbstractItemView::sizeHintForRow().

Returns the size hint for the givenrow's height or -1 if there is no model.

If you need to set the height of a given row to a fixed value, callQHeaderView::resizeSection() on the table's vertical header.

If you reimplement this function in a subclass, note that the value you return is only used whenresizeRowToContents() is called. In that case, if a larger row height is required by either the vertical header or the item delegate, that width will be used instead.

See alsoQWidget::sizeHint andverticalHeader().

void QTableView::sortByColumn(int column,Qt::SortOrder order)

Sorts the model by the values in the givencolumn in the givenorder.

This function was introduced in Qt 4.2.

See alsosortingEnabled.

[virtual protected]void QTableView::timerEvent(QTimerEvent * event)

Reimplemented fromQObject::timerEvent().

[virtual protected]void QTableView::updateGeometries()

Reimplemented fromQAbstractItemView::updateGeometries().

QHeaderView * QTableView::verticalHeader() const

Returns the table view's vertical header.

See alsosetVerticalHeader(),horizontalHeader(), andQAbstractItemModel::headerData().

[virtual protected]int QTableView::verticalOffset() const

Reimplemented fromQAbstractItemView::verticalOffset().

Returns the vertical offset of the items in the table view.

Note that the table view uses the vertical header section positions to determine the positions of rows in the view.

See alsohorizontalOffset().

[virtual protected]QStyleOptionViewItem QTableView::viewOptions() const

Reimplemented fromQAbstractItemView::viewOptions().