Contents

• Properties
• Public Functions
• Public Slots
• Signals
• Protected Functions
• Reimplemented Protected Functions
• Detailed Description

Detailed Description

TheQTableWidget class provides an item-based table view with a default model.

Table widgets provide standard table display facilities for applications. The items in aQTableWidget are provided byQTableWidgetItem.

If you want a table that uses your own data model you should useQTableView rather than this class.

Table widgets can be constructed with the required numbers of rows and columns:

    tableWidget=newQTableWidget(12,3,this);

Alternatively, tables can be constructed without a given size and resized later:

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

Items are created ouside the table (with no parent widget) and inserted into the table withsetItem():

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

If you want to enable sorting in your table widget, do so after you have populated it with items, otherwise sorting may interfere with the insertion order (seesetItem() for details).

Tables can be given both horizontal and vertical headers. The simplest way to create the headers is to supply a list of strings to thesetHorizontalHeaderLabels() andsetVerticalHeaderLabels() functions. These will provide simple textual headers for the table's columns and rows. More sophisticated headers can be created from existing table items that are usually constructed outside the table. For example, we can construct a table item with an icon and aligned text, and use it as the header for a particular column:

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

The number of rows in the table can be found withrowCount(), and the number of columns withcolumnCount(). The table can be cleared with theclear() function.

AWindows XP style table widget.	AMacintosh style table widget.	APlastique style table widget.

Property Documentation

columnCount :int

This property holds the number of columns in the table.

By default, for a table constructed without row and column counts, this property contains a value of 0.

Access functions:

rowCount :int

This property holds the number of rows in the table.

By default, for a table constructed without row and column counts, this property contains a value of 0.

Access functions:

Member Function Documentation

QTableWidget::QTableWidget(QWidget * parent = 0)

Creates a new table view with the givenparent.

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

Creates a new table view with the givenrows andcolumns, and with the givenparent.

QTableWidget::~QTableWidget()

Destroys thisQTableWidget.

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

This signal is emitted when the cell specified byrow andcolumn has been activated

This function was introduced in Qt 4.1.

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

This signal is emitted whenever the data of the item in the cell specified byrow andcolumn has changed.

This function was introduced in Qt 4.1.

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

This signal is emitted whenever a cell in the table is clicked. Therow andcolumn specified is the cell that was clicked.

This function was introduced in Qt 4.1.

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

This signal is emitted whenever a cell in the table is double clicked. Therow andcolumn specified is the cell that was double clicked.

This function was introduced in Qt 4.1.

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

This signal is emitted when the mouse cursor enters a cell. The cell is specified byrow andcolumn.

This signal is only emitted whenmouseTracking is turned on, or when a mouse button is pressed while moving into an item.

This function was introduced in Qt 4.1.

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

This signal is emitted whenever a cell in the table is pressed. Therow andcolumn specified is the cell that was pressed.

This function was introduced in Qt 4.1.

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

Returns the widget displayed in the cell in the givenrow andcolumn.

Note:The table takes ownership of the widget.

This function was introduced in Qt 4.1.

See alsosetCellWidget().

[slot]void QTableWidget::clear()

Removes all items in the view. This will also remove all selections. The table dimensions stay the same.

[slot]void QTableWidget::clearContents()

Removes all items not in the headers from the view. This will also remove all selections. The table dimensions stay the same.

This function was introduced in Qt 4.2.

void QTableWidget::closePersistentEditor(QTableWidgetItem * item)

Closes the persistent editor foritem.

See alsoopenPersistentEditor().

int QTableWidget::column(constQTableWidgetItem * item) const

Returns the column for theitem.

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

This signal is emitted whenever the current cell changes. The cell specified bypreviousRow andpreviousColumn is the cell that previously had the focus, the cell specified bycurrentRow andcurrentColumn is the new current cell.

This function was introduced in Qt 4.1.

int QTableWidget::currentColumn() const

Returns the column of the current item.

See alsocurrentRow() andsetCurrentCell().

QTableWidgetItem * QTableWidget::currentItem() const

Returns the current item.

See alsosetCurrentItem().

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

This signal is emitted whenever the current item changes. Theprevious item is the item that previously had the focus,current is the new current item.

int QTableWidget::currentRow() const

Returns the row of the current item.

See alsocurrentColumn() andsetCurrentCell().

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

Reimplemented fromQWidget::dropEvent().

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

Handles thedata supplied by a drag and drop operation that ended with the givenaction in the givenrow andcolumn. Returns true if the data and action can be handled by the model; otherwise returns false.

See alsosupportedDropActions().

void QTableWidget::editItem(QTableWidgetItem * item)

Starts editing theitem if it is editable.

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

Reimplemented fromQObject::event().

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

Finds items that matches thetext using the givenflags.

QTableWidgetItem * QTableWidget::horizontalHeaderItem(int column) const

Returns the horizontal header item for column,column, if one has been set; otherwise returns 0.

See alsosetHorizontalHeaderItem().

[protected]QModelIndex QTableWidget::indexFromItem(QTableWidgetItem * item) const

Returns theQModelIndex assocated with the givenitem.

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

Inserts an empty column into the table atcolumn.

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

Inserts an empty row into the table atrow.

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

Returns the item for the givenrow andcolumn if one has been set; otherwise returns 0.

See alsosetItem().

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

This signal is emitted when the specifieditem has been activated

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

Returns a pointer to the item at the givenpoint, or returns 0 ifpoint is not covered by an item in the table widget.

See alsoitem().

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

Returns the item at the position equivalent toQPoint(ax,ay) in the table widget's coordinate system, or returns 0 if the specified point is not covered by an item in the table widget.

See alsoitem().

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

This signal is emitted whenever the data ofitem has changed.

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

This signal is emitted whenever an item in the table is clicked. Theitem specified is the item that was clicked.

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

This signal is emitted whenever an item in the table is double clicked. Theitem specified is the item that was double clicked.

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

This signal is emitted when the mouse cursor enters an item. Theitem is the item entered.

This signal is only emitted whenmouseTracking is turned on, or when a mouse button is pressed while moving into an item.

[protected]QTableWidgetItem * QTableWidget::itemFromIndex(constQModelIndex & index) const

Returns a pointer to theQTableWidgetItem assocated with the givenindex.

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

This signal is emitted whenever an item in the table is pressed. Theitem specified is the item that was pressed.

constQTableWidgetItem * QTableWidget::itemPrototype() const

Returns the item prototype used by the table.

See alsosetItemPrototype().

[signal]void QTableWidget::itemSelectionChanged()

This signal is emitted whenever the selection changes.

See alsoselectedItems() andQTableWidgetItem::isSelected().

[protected]QList<QTableWidgetItem *> QTableWidget::items(constQMimeData * data) const

Returns a list of pointers to the items contained in thedata object. If the object was not created by aQTreeWidget in the same process, the list is empty.

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

Returns an object that contains a serialized description of the specifieditems. The format used to describe the items is obtained from themimeTypes() function.

If the list of items is empty, 0 is returned rather than a serialized empty list.

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

Returns a list of MIME types that can be used to describe a list of tablewidget items.

See alsomimeData().

void QTableWidget::openPersistentEditor(QTableWidgetItem * item)

Opens an editor for the giveitem. The editor remains open after editing.

See alsoclosePersistentEditor().

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

Removes the widget set on the cell indicated byrow andcolumn.

This function was introduced in Qt 4.3.

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

Removes the columncolumn and all its items from the table.

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

Removes the rowrow and all its items from the table.

int QTableWidget::row(constQTableWidgetItem * item) const

Returns the row for theitem.

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

Scrolls the view if necessary to ensure that theitem is visible. Thehint parameter specifies more precisely where theitem should be located after the operation.

QList<QTableWidgetItem *> QTableWidget::selectedItems()

Returns a list of all selected items.

This function returns a list of pointers to the contents of the selected cells. Use theselectedIndexes() function to retrieve the complete selectionincluding empty cells.

See alsoselectedIndexes().

QList<QTableWidgetSelectionRange> QTableWidget::selectedRanges() const

Returns a list of all selected ranges.

See alsoQTableWidgetSelectionRange.

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

Sets the givenwidget to be displayed in the cell in the givenrow andcolumn, passing the ownership of the widget to the table.

If cell widget A is replaced with cell widget B, cell widget A will be deleted. For example, in the code snippet below, theQLineEdit object will be deleted.

setCellWidget(index,newQLineEdit);...setCellWidget(index,newQTextEdit);

This function was introduced in Qt 4.1.

See alsocellWidget().

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

Sets the current cell to be the cell at position (row,column).

Depending on the currentselection mode, the cell may also be selected.

This function was introduced in Qt 4.1.

See alsosetCurrentItem(),currentRow(), andcurrentColumn().

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

Sets the current cell to be the cell at position (row,column), using the givencommand.

This function was introduced in Qt 4.4.

See alsosetCurrentItem(),currentRow(), andcurrentColumn().

void QTableWidget::setCurrentItem(QTableWidgetItem * item)

Sets the current item toitem.

Unless the selection mode isNoSelection, the item is also be selected.

See alsocurrentItem() andsetCurrentCell().

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

Sets the current item to beitem, using the givencommand.

This function was introduced in Qt 4.4.

See alsocurrentItem() andsetCurrentCell().

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

Sets the horizontal header item for columncolumn toitem.

See alsohorizontalHeaderItem().

void QTableWidget::setHorizontalHeaderLabels(constQStringList & labels)

Sets the horizontal header labels usinglabels.

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

Sets the item for the givenrow andcolumn toitem.

The table takes ownership of the item.

Note that if sorting is enabled (seesortingEnabled) andcolumn is the current sort column, therow will be moved to the sorted position determined byitem.

If you want to set several items of a particular row (say, by calling setItem() in a loop), you may want to turn off sorting before doing so, and turn it back on afterwards; this will allow you to use the samerow argument for all items in the same row (i.e. setItem() will not move the row).

See alsoitem() andtakeItem().

void QTableWidget::setItemPrototype(constQTableWidgetItem * item)

Sets the item prototype for the table to the specifieditem.

The table widget will use the item prototype clone function when it needs to create a new table item. For example when the user is editing in an empty cell. This is useful when you have aQTableWidgetItem subclass and want to make sure thatQTableWidget creates instances of your subclass.

The table takes ownership of the prototype.

See alsoitemPrototype().

void QTableWidget::setRangeSelected(constQTableWidgetSelectionRange & range,bool select)

Selects or deselects therange depending onselect.

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

Sets the vertical header item for rowrow toitem.

See alsoverticalHeaderItem().

void QTableWidget::setVerticalHeaderLabels(constQStringList & labels)

Sets the vertical header labels usinglabels.

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

Sorts all the rows in the table widget based oncolumn andorder.

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

Returns the drop actions supported by this view.

See alsoQt::DropActions.

QTableWidgetItem * QTableWidget::takeHorizontalHeaderItem(int column)

Removes the horizontal header item atcolumn from the header without deleting it.

This function was introduced in Qt 4.1.

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

Removes the item atrow andcolumn from the table without deleting it.

QTableWidgetItem * QTableWidget::takeVerticalHeaderItem(int row)

Removes the vertical header item atrow from the header without deleting it.

This function was introduced in Qt 4.1.

QTableWidgetItem * QTableWidget::verticalHeaderItem(int row) const

Returns the vertical header item for rowrow.

See alsosetVerticalHeaderItem().

int QTableWidget::visualColumn(int logicalColumn) const

Returns the visual column of the givenlogicalColumn.

QRect QTableWidget::visualItemRect(constQTableWidgetItem * item) const

Returns the rectangle on the viewport occupied by the item atitem.

int QTableWidget::visualRow(int logicalRow) const

Returns the visual row of the givenlogicalRow.