![]() |
| ||
Classes - Annotated - Tree - Functions - Home - Structure |
The QTable class provides a flexible editable table widget. More...
#include <qtable.h>
Inherits QScrollView.
Inherited by QDataTable.
The QTable class provides a flexible editable table widget.
QTable is easy to use, although it does have a large API because of the comprehensive functionality that it provides. QTable includes functions for manipulating headers, rows and columns, cells and selections. QTable also provides in-place editing and drag and drop. QTable efficiently supports very large tables, for example, tables one million by one million cells are perfectly possible. QTable is economical with memory, using none for unused cells.
QTable table( numRows, numCols );
table.setPixmap( 3, 2, pix ); table.setText( 3, 2, "A Pixmap" );
(Code taken from table/small-table-demo/main.cpp.) The first line constructs the table specifying its size in rows and columns. We then insert a pixmap and some text into the same cell, with the pixmap appearing to the left of the text. By default a vertical header appears at the left of the table showing row numbers and a horizontal header appears at the top of the table showing column numbers. (The numbers displayed start at 1, although row and column numbers within QTable begin at 0.)
Headers
QTable supports a header column, e.g. to display row numbers, and a
header row, e.g to display column titles. To set row or column
labels use QHeader::setLabel() on the pointers returned by
verticalHeader() and horizontalHeader() respectively. The vertical
header is displayed in the table's left margin whose width is set
with setLeftMargin(). The horizontal header is displayed in the
table's top margin whose height is set with setTopMargin(). The
table's grid can be switched off with setShowGrid().
Rows and Columns
Row and column sizes are set with setRowHeight() and
setColumnWidth(). If you want a row high enough to show the
tallest item in its entirety, use adjustRow(). Similarly, to make a
column wide enough to show the widest item use adjustColumn(). If
you want the row height and column width to adjust automatically as
the contents of the table changes use setRowStretchable() and
setColumnStretchable().
Rows and columns can be hidden and shown with hideRow(), hideColumn(), showRow() and showColumn(). New rows and columns are inserted using insertRows() and insertColumns(). Additional rows and columns and rows are added at the bottom (rows) or right (columns) if you set setNumRows() or setNumCols() to be larger than numRows() or numCols(). Existing rows and columns are removed with removeRow() and removeColumn(). Multiple rows and columns can be removed with removeRows() and removeColumns().
Rows and columns can be set to be moveable, i.e. the user can drag them to reorder them, using rowMovingEnabled() and columnMovingEnabled(). The table can be sorted using sortColumn(). Users can sort a column by clicking its header if setSorting() is set to TRUE. Rows can be swapped with swapRows(), columns with swapColumns() and cells with swapCells().
For editable tables (see setReadOnly()) you can set the read-only property of individual rows and columns with setRowReadOnly() and setColumnReadOnly(). (Whether a cell is editable or read-only depends on these settings and the cell's QTableItem::EditType.)
The row and column which have the focus are returned by currentRow() and currentColumn() respectively.
Although many QTable functions operate in terms of rows and columns the indexOf() function returns a single integer representing a particular cell.
There are two approaches to populating the table's cells. The first
and simplest approach is to use QTableItems or QTableItem
subclasses. The second approach doesn't use QTableItems at all which
is useful for very large sparse tables but requires you to
reimplement a number of functions. We'll look at each approach in
turn.
To put a string in a cell use setText(). This function will create a
new QTableItem for the cell if one doesn't already exist, and
display the text in it. By default the table item's widget will be a
QLineEdit. A pixmap may be put in a cell with setPixmap(), which
also creates a table item if required. A cell may contain both a
pixmap and text; the pixmap is displayed to the left of the text.
Another approach is to construct a QTableItem or QTableItem
subclass, set its properties, then insert it into a cell with
setItem().
If you want cells which contain comboboxes use the
QComboTableItem class. Similarly if you require cells containing
checkboxes use the QCheckTableItem class. These table items look and
behave just like the combobox or checkbox widgets but consume far
less memory.
QTable takes ownership of its QTableItems and will delete them when
the table itself is destroyed. You can take ownership of a table
item using takeItem() which is used to move a cell's contents from
one place to another, or one table to another. (See also,
swapCells()).
In-place editing of the text in QTableItems, and the values in
QComboTableItems and QCheckTableItems works automatically. Cells may
be editable or read-only,
see QTableItem::EditType.
The contents of a cell can be retrieved as a QTableItem using
item(), or as a string with text() or as a pixmap (if there is one)
with pixmap(). A cell's bounding rectangle is given by
cellGeometry(). Use updateCell() to repaint a cell, for example to
clear away a cell's visual representation after it has been deleted
with clearCell(). The table can be forced to scroll to show a
particular cell with ensureCellVisible(). The isSelected() function
indicates if a cell is selected.
It is possible to use your own widget as a cell's widget using
setCellWidget(), but subclassing QTableItem might be a simpler
approach. The cell's widget (if there is one) can be removed with
clearCellWidget().
For large, sparse, tables using QTableItems or other widgets is
inefficient. The solution is to draw the cell as it should appear
and to create and destroy cell editors on demand.
This approach requires that you reimplement various functions.
Reimplement paintCell() to display your data, and createEditor() and
setCellContentFromEditor() to facilitate in-place editing. It is
very important to reimplement resizeData() to have no functionality,
to prevent QTable from attempting to create a huge array. You will
also need to reimplement item(), setItem(), clearCell(), and
insertWidget(), cellWidget() and clearCellWidget(). If you wish to
support sorting you should also reimplement swapRows(), swapCells()
and swapColumns().
If you represent active cells with a dictionary of QTableItems and
QWidgets, i.e. only store references to cells that are actually
used, most of the functions can be implemented with a single line of
code. (See the table/bigtable/main.cpp example.)
For more information on cells see the QTableItem documenation.
QTable's support single selection, multi-selection (multiple cells)
or no selection. The selection mode is set with setSelectionMode().
Use isSelected() to determine if a particular cell is selected, and
isRowSelected() and isColumnSelected() to see if a row or column is
selected.
QTable's support multiple selections. You can programmatically
select cells with addSelection(). The number of selections is given
by numSelections(). The current selection is returned by
currentSelection(). You can remove a selection with
removeSelection() and remove all selections with clearSelection().
Selections are QTableSelection objects.
Call setNumRows() and setNumCols() to set the table size before
populating the table if you're using QTableItems.
Performance will be improved by modifying the table widget's
window-system properties (widget flags) using setWFlags() so that only
part of each QTableItem child is redrawn. This may be unsuitable for
custom QTableItem subclasses, in which case the WNorthWestGravity
and WRepaintNoErase flags should be cleared.
See also QWidget::clearWFlags() and Qt::WidgetFlags.
Performance will be improved by modifying the table widget's
window-system properties (widget flags) using setWFlags() so that only
part of each QTableItem child is redrawn. This may be unsuitable for
custom QTableItem subclasses, in which case the WNorthWestGravity
and WRepaintNoErase flags should be cleared.
If you're using QTableItems to populate the table's cells, you can
create QTableItem, QComboTableItem and QCheckTableItem items and
insert them into the table using setItem(). (See the notes on large tables for an alternative to using
QTableItems.)
See also QWidget::clearWFlags() and Qt::WidgetFlags.
If you want a different behavior than going from top to bottom,
reimplement this function.
Remember to call QTableSelection::init() and
QTableSelection::expandTo() to make the selection valid (see also
QTableSelection::isActive()).
See also numSelections(), removeSelection() and clearSelection().
(Code taken from table/euroconversion/converter.cpp)
See also adjustRow().
See also adjustColumn().
This function calls createEditor() to obtain the editor which should be
used for editing the cell. After that setCellWidget() is used to make this
editor the widget of the cell.
See also endEdit().
If you don't use QTableItems you may need to reimplement this function:
see the notes on large tables.
See also clearCellWidget() and setCellWidget().
If you don't use QTableItems you may need to reimplement this function:
see the notes on large tables.
If you don't use QTableItems you may need to reimplement this function:
see the notes on large tables.
See also cellWidget() and setCellWidget().
Repainting is the default. If this is not desired set
repaint to FALSE.
See also removeSelection().
This signal is emitted when mouse button button is clicked. The
cell where the event took place is at row row, column col, and
the mouse's position is in mousePos.
See also columnPos() and rowAt().
If you want to change the column order programmatically, call
QHeader::moveSection() on the horizontalHeader().
See also QHeader::indexChange() and rowIndexChanged().
Returns TRUE whether columns can be moved by the user, otherwise returns FALSE. See the "columnMovingEnabled" property for details. See also columnAt() and rowPos().
See also setColumnWidth and rowHeight().
Cells
All of a QTable's cells are empty when the table is constructed.
for ( int j = 0; j < numRows; ++j )
table.setItem( j, 1, new QCheckTableItem( &table, "Check me" ) );
In the example above we create a column of QCheckTableItems and
insert them into the table using setItem().
Selections
Member Type Documentation
QTable::EditMode
QTable::SelectionMode
Member Function Documentation
QTable::QTable ( QWidget * parent = 0, const char * name = 0 )
Creates an empty table object called name as a child of parent.
QTable::QTable ( int numRows, int numCols, QWidget * parent = 0, const char * name = 0 )
Constructs an empty table called name with numRows rows and numCols columns. The table is a child of parent.
QTable::~QTable ()
Destructor. Deletes all the resources used by a QTable object,
including all QTableItems and their widgets.
void QTable::activateNextCell () [virtual protected]
This function is called to activate the next cell if in-place editing was
stopped by pressing the Return key.
int QTable::addSelection ( const QTableSelection & s ) [virtual]
Adds a selection described by s to the table and returns its
number or -1 if the selection is invalid.
void QTable::adjustColumn ( int col ) [virtual slot]
Resizes the column col so that its
entire content is visible, e.g.
adjustColumn( 1 );
void QTable::adjustRow ( int row ) [virtual slot]
Resizes the row row to be high enough to fit
its entire content.
QWidget * QTable::beginEdit ( int row, int col, bool replace ) [virtual protected]
This function is called to start in-place editing of the cell row, col. If replace is TRUE the content of this cell will be
replaced by the content of the editor later, otherwise the current
content of the cell (if existing) will be modified by the editor.
QRect QTable::cellGeometry ( int row, int col ) const [virtual]
Returns the bounding rectangle of the cell at row, col in content
coordinates.
QWidget * QTable::cellWidget ( int row, int col ) const [virtual]
Returns the widget that has been set to the cell row, col,
or 0 if there is no widget.
void QTable::clearCell ( int row, int col ) [virtual]
Removes the QTableItem in position row, col.
void QTable::clearCellWidget ( int row, int col ) [virtual]
Removes the widget (if there is any) set for the cell row, col.
void QTable::clearSelection ( bool repaint = TRUE ) [slot]
Clears all selections and repaints the appropriate
regions if repaint is TRUE.
void QTable::clicked ( int row, int col, int button, const QPoint & mousePos ) [signal]
int QTable::columnAt ( int pos ) const [virtual]
Returns the number of the column at pos. pos must be given in
content coordinates.
void QTable::columnClicked ( int col ) [virtual protected slot]
This function is called when the column col has been
clicked. The default implementation sorts this column if
sorting() is TRUE.
void QTable::columnIndexChanged ( int section, int fromIndex, int toIndex ) [virtual protected slot]
This function is called when column order is to be changed, i.e.
when the user moved the column header section
from fromIndex to toIndex.
bool QTable::columnMovingEnabled () const
int QTable::columnPos ( int col ) const [virtual]
Returns the x-coordinate of the column col in content
coordinates.
int QTable::columnWidth ( int col ) const [virtual]
Returns the width of column col.
void QTable::columnWidthChanged ( int col ) [virtual protected slot]
This function should be called whenever the column width of col
has been changed. It updates the geometry of any affected columns and
repaints the table to reflect the changes it has made.
void QTable::contentsDragEnterEvent ( QDragEnterEvent * e ) [virtual protected]
This event handler is called whenever a QTable object receives a
QDragEnterEvent e, i.e. when the user pressed the mouse
button to drag something.
The focus is moved to the cell where the QDragEnterEvent occurred.
Reimplemented from QScrollView.
Reimplemented from QScrollView.
The focus is moved to the cell where the QDragMoveEvent occurred.
Reimplemented from QScrollView.
Reimplemented from QScrollView.
This signal is emitted when the user invokes a context menu with the right mouse button (or with a system-specific keyboard key). The cell where the event took place is at row row, column col. pos is the position where the context menu will appear in the global coordinate system.
If initFromCell is TRUE, the editor is used to edit the current contents of the cell (so the editor widget should be initialized with this content). If initFromCell is FALSE, the content of the cell is replaced with the new content which the user entered into the widget created by this function.
The default functionality is as follows: if initFromCell is TRUE or the cell has a QTableItem and the item's QTableItem::isReplaceable() is FALSE then the cell is asked to create an appropriate editor (using QTableItem::createEditor()). Otherwise a QLineEdit is used as the editor.
If you want to create your own editor for certain cells, implement a custom QTableItem subclass and reimplement QTableItem::createEditor().
If you are not using QTableItems and you don't want to use a QLineEdit as the default editor, subclass QTable and reimplement this function and use code like this:
QTableItem *i = item( row, col ); if ( initFromCell || ( i && !i->isReplaceable() ) ) // If we had a QTableItem ask the base class to create the editor return QTable::createEditor( row, col, initFromCell ); else return ...(create your editor)Ownership of the editor widget is transferred to the caller.
If you reimplement this function return 0 for read-only cells. You will need to reimplement setCellContentFromEditor() to retrieve the data the user entered.
See also QTableItem::createEditor().
Example: table/wineorder/productlist.cpp.
This signal is emitted when the current cell has changed to row, col.
Returns the current column.
See also currentRow().
Returns the current row.
See also currentColumn().
See also numSelection().
This signal is emitted when mouse button button is double-clicked. The cell where the event took place is at row row, column col, and the mouse's position is in mousePos.
See also setDragEnabled().
By default this function returns 0. You might reimplement it and create a QDragObject depending on the selected items.
See also dropped().
Additionally, drawContents() highlights the current cell.
Reimplemented from QScrollView.
This signal is emitted when a drop event occurred onto the table.
e gives you all information about the drop.
If accept is TRUE the content of the editor has to be transferred to the relevant cell. If replace is TRUE the current content of this cell should be replaced by the content of the editor (this means removing the current QTableItem of the cell and creating a new one for the cell). Otherwise (if possible) the content of the editor should just be set to the existing QTableItem of this cell.
If the cell contents should be replaced or if no QTableItem exists for the cell yet, setCellContentFromEditor() is called. Otherwise QTableItem::setContentFromEditor() is called on the QTableItem of the cell.
After that clearCellWidget() is called to get rid of the editor widget.
See also setCellContentFromEditor() and beginEdit().
See also showColumn() and hideRow().
See also showRow() and hideColumn().
This header contains the column labels.
To modify a column label use QHeader::setLabel(), e.g.
horizontalHeader()->setLabel( 0, tr( "File" ) );
See also verticalHeader(), setTopMargin() and QHeader.
Example: table/small-table-demo/main.cpp.
See also insertRows() and removeColumn().
See also insertColumns() and removeRow().
If you don't use QTableItems you may need to reimplement this function: see the notes on large tables.
Whether a cell in this column is editable or read-only depends on the cell's EditType, and this setting: see QTableItem::EditType.
See also setColumnReadOnly() and isRowReadOnly().
Returns TRUE if col is selected; otherwise returns FALSE.
If full is FALSE (the default), 'col is selected' means that at least one cell in the column is selected. If full is TRUE, then 'col is selected' means every cell in the column is selected.
See also isRowSelected() and isSelected().
See also setColumnStretchable() and isRowStretchable().
Returns TRUE whether the table is read-only, otherwise returns FALSE. See the "readOnly" property for details.
Whether a cell in this row is editable or read-only depends on the cell's EditType, and this setting: see QTableItem::EditType.
See also setRowReadOnly and isColumnReadOnly().
If full is FALSE (the default), 'row is selected' means that at least one cell in the row is selected. If full is TRUE, then 'row is selected' means every cell in the row is selected.
See also isColumnSelected() and isSelected().
See also setRowStretchable() and isColumnStretchable().
See also isRowSelected() and isColumnSelected().
If row or col are out of range or no content has been set for this cell, item() returns 0.
If you don't use QTableItems you may need to reimplement this function: see the notes on large tables.
See also setItem().
Returns the number of columns of the table. See the "numCols" property for details.
Returns the number of rows of the table. See the "numRows" property for details.
See also currentSelection().
If selected is TRUE the cell is highlighted.
If you want to draw custom cell content, for example right-aligned text, you must either reimplement paintCell(), or subclass QTableItem and reimplement QTableItem::paint() to do the custom drawing.
If you're using a QTableItem subclass, for example, to store a data structure, then reimplementing QTableItem::paint() may be the best approach. For data you want to draw immediately, e.g. data retrieved from a database, it is probably best to reimplement paintCell(). Note that if you reimplement paintCell, i.e. don't use QTableItems, you will have to reimplement other functions: see the notes on large tables.
paintEmptyArea() is invoked by drawContents() to erase or fill unused areas.
The painter p is already translated to the cell's origin, while cr specifies the cell's geometry in content coordinates.
See also setPixmap().
This signal is emitted when mouse button button is pressed. The cell where the event took place is at row row, column col, and the mouse's position is in mousePos.
See also removeColumns(), hideColumn(), insertColumns() and removeRow().
See also removeColumn(), insertColumns() and removeRows().
See also hideRow(), insertRows(), removeColumn() and removeRows().
See also removeRow(), insertRows() and removeColumns().
See also addSelection() and numSelections().
Removes selection number num from the table.
See also numSelections() and addSelection().
If you don't use QTableItems you should reimplement this as an empty method to avoid wasting memory. See the notes on large tables for further details.
See also rowPos() and columnAt().
See also setRowHeight and columnWidth().
Example: table/small-table-demo/main.cpp.
If you want to change the order programmatically, call QHeader::moveSection() on the verticalHeader().
See also QHeader::indexChange() and columnIndexChanged().
Returns TRUE whether rows can be moved by the user, otherwise returns FALSE. See the "rowMovingEnabled" property for details.
See also rowAt() and columnPos().
This signal is emitted whenever a selection changes.
See also QTableSelection.
See also SelectionMode and setSelectionMode().
If you for example want to create different QTableItems depending on the contents of the editor, you might reimplement this function. Also if you want to work without QTableItems, you need to reimplement this function to save the data the user entered to your data structure.
If you don't use QTableItems you may need to reimplement this function: see the notes on large tables.
See also QTableItem::setContentFromEditor() and createEditor().
Example: table/wineorder/productlist.cpp.
QSpinBox * quantities = new QSpinBox( (QTable * ) this, "quantities" );
( (QTable * ) this )->setCellWidget( row, col, quantities );
(Code taken from table/wineorder/productlist.cpp)
If the cell geometry changes setCellWidget() takes care about correct resizing and replacement.
By default widgets are inserted into a vector of numRows() x numCols() elements. Widgets of very big tables you probably want to store in a datastructure that needs less memory (like a hash-table). To make this possible this functions calls insertWidget() to add the widget to the internal datastructure.
If you want to use your own datastructure, you therefore have to reimplement insertWidget(), cellWidget() and clearCellWidget().
Sets whether columns can be moved by the user to b. See the "columnMovingEnabled" property for details.
Whether a cell in this column is editable or read-only depends on the cell's EditType, and this setting: see QTableItem::EditType.
See also isColumnReadOnly(), setRowReadOnly() and readOnly.
This means that whenever the table widget becomes wider than its contents, stretchable columns are stretched so that the table contents fit exactly into the widget.
See also isColumnStretchable() and setRowStretchable().
See also columnWidth() and setRowHeight().
See also currentRow() and currentColumn().
See also EditMode.
If you don't use QTableItems you may need to reimplement this function: see the notes on large tables.
See also item() and takeItem().
Example: table/small-table-demo/main.cpp.
The left header, which displays row labels, occupies this margin.
See also leftMargin(), setTopMargin() and verticalHeader().
Sets the number of columns of the table to c. See the "numCols" property for details.
Sets the number of rows of the table to r. See the "numRows" property for details.
If the cell does not contain a table item a QTableItem is created with an EditType of OnTyping, otherwise the existing table item's pixmap (if any) is replaced with pix.
QImage img( qtlogo_xpm ); QPixmap pix = img.scaleHeight( table.rowHeight(3) ); table.setPixmap( 3, 2, pix );
(Code from table/small-table-demo/main.cpp.) In the example we create an image, scale it to the height of the table's fourth row (row 3), then set the pixmap for the cell at row 3, column 2 to the scaled pixmap.
QComboTableItems and QCheckTableItems don't show pixmaps.
See also pixmap(), setText(), setItem() and QTableItem::setPixmap().
Example: table/small-table-demo/main.cpp.
Sets whether the table is read-only to b. See the "readOnly" property for details.
See also rowHeight() and setColumnWidth().
Sets whether rows can be moved by the user to b. See the "rowMovingEnabled" property for details.
Whether a cell in this row is editable or read-only depends on the cell's EditType, and this setting: see QTableItem::EditType.
See also isRowReadOnly(), setColumnReadOnly() and readOnly.
This means that whenever the table widgets becomes higher than its contents, stretchable rows are stretched so that the table contents fit exactly into the widget.
See also isRowStretchable() and setColumnStretchable().
See also SelectionMode and selectionMode().
Sets whether the table's grid is displayed to b. See the "showGrid" property for details.
Sets whether a click on the header of a column sorts that column to b. See the "sorting" property for details.
If the cell does not contain a table item a QTableItem is created with an EditType of OnTyping, otherwise the existing table item's text (if any) is replaced with text.
See also text(), setPixmap(), setItem() and QTableItem::setText().
Example: table/small-table-demo/main.cpp.
The top header, which displays column labels, occupies this margin.
See also topMargin() and setLeftMargin().
See also hideColumn() and showRow().
Returns TRUE whether the table's grid is displayed, otherwise returns FALSE. See the "showGrid" property for details.
See also hideRow() and showColumn().
If wholeRows is TRUE changing data of the cells is done using swapRows(). Otherwise swapCells() is called.
Note that if you are not using QTableItems you will need to reimplement swapRows() and swapCells().
See also swapRows().
Reimplemented in QDataTable.
Returns TRUE whether a click on the header of a column sorts that column, otherwise returns FALSE. See the "sorting" property for details.
Usually you don't need to call or reimplement this function yourself.
See also dragObject().
This function is also called when the table is sorted.
If you don't use QTableItems and want your users to be able to swap cells, you will need to reimplement this function. (See the notes on large tables.)
See also swapColumns() and swapRows().
This function is used to swap the positions of two columns. It is called when the user changes the order of columns (see setColumnMovingEnabled(), and when columns are sorted.
If you don't use QTableItems and want your users to be able to swap columns you will need to reimplement this function. (See the notes on large tables.)
See also swapCells().
This function is used to swap the positions of two rows. It is called when the user changes the order of rows (see setRowMovingEnabled(), and when rows are sorted.
If you don't use QTableItems and want your users to be able to swap rows, e.g. for sorting, you will need to reimplement this function. (See the notes on large tables.)
See also swapColumns() and swapCells().
Use this function if you want to move an item from one place in a table to another, or to move an item from one table to another, reinserting the item with setItem().
If you want to exchange two cells use swapCells().
See also setText() and setPixmap().
Reimplemented in QDataTable.
This signal is emitted when the user changed the value in cell row, col.
This header contains the row labels.
See also horizontalHeader(), setLeftMargin() and QHeader.
This property holds whether columns can be moved by the user.
Set this property's value with setColumnMovingEnabled() and get this property's value with columnMovingEnabled().
See also rowMovingEnabled.
This property holds the number of columns of the table.
Set this property's value with setNumCols() and get this property's value with numCols().
See also numRows.
This property holds the number of rows of the table.
Set this property's value with setNumRows() and get this property's value with numRows().
See also numCols.
This property holds whether the table is read-only.
Whether a cell in the table is editable or read-only depends on the cell's EditType, and this setting: see QTableItem::EditType.
Set this property's value with setReadOnly() and get this property's value with isReadOnly().
See also QWidget::enabled, setColumnReadOnly() and setRowReadOnly().
This property holds whether rows can be moved by the user.
Set this property's value with setRowMovingEnabled() and get this property's value with rowMovingEnabled().
See also columnMovingEnabled.
This property holds whether the table's grid is displayed.
The grid is shown by default.
Set this property's value with setShowGrid() and get this property's value with showGrid().
This property holds whether a click on the header of a column sorts that column.
Set this property's value with setSorting() and get this property's value with sorting().
See also sortColumn().
Search the documentation, FAQ, qt-interest archive and more (uses
www.trolltech.com):
This file is part of the Qt toolkit, copyright © 1995-2000 Trolltech, all rights reserved.
Copyright © 2000 Trolltech | Trademarks | Qt version main-beta1
|