|
|
A flexible and editable table widget. More...
#include <qtable.h>
Inherits QScrollView.
| Type | Name | READ | WRITE | Options |
|---|---|---|---|---|
| int | numRows | numRows | setNumRows | |
| int | numCols | numCols | setNumCols | |
| bool | showGrid | showGrid | setShowGrid | |
| bool | rowMovingEnabled | rowMovingEnabled | setRowMovingEnabled | |
| bool | columnMovingEnabled | columnMovingEnabled | setColumnMovingEnabled |
QTable has been designed to us no more memory than strictly needed. Thus, for an empty cell, no memory at all is allocated. In order to add data, create a QTableItem and fill it using setItem(). With QTableItem::setText() and QTableItem::setPixmap(), convenient functions for setting table text and pixmaps are provided. To clear a cell use clearCell().
QTable supports various methods for selecting cells, both with keyboard and mouse, thus for example range selection or column and row selection via appropriate header cells. You can add and remove selections using addSelection() and removeSelection(), resp., and gather information about current selections by means of numSelections(), selection(), and currentChanged().
QTable also offers an API for sorting columns. See setSorting(), sortColumn() and QTableItem::key() for details.
Cell editing can be done in two different ways: Either you offer an edit widget the user can use to enter data that should replace the current content, or you provide him or her with an editor to change the data stored in the cell. If you won't allow the content of a cell to be replaced, however make it possible to edit the current data, simply set QTableItem::isReplaceable() to FALSE.
When a user starts typing text in-place editing (replacing) for the current cell is invoked. Additionally, in-place editing (editing) starts as soon as he or she double-clicks a cell. Sometimes, however, it is required that a cell always shows an editor, that the editor shows off as soon as the relevant cell receives the focus, or that the item shouldn't be edited at all. This edit type has to be specified in the constructor of a QTableItem.
In-place editing is invoked by beginEdit(). This function creates the editor widget for the required cell (see createEditor() for detailed information) and shows it at the appropriate location.
As soon as the user finishes editing endEdit() is called. Have a look at the endEdit() documentation for further information e.g. on how content is transferred from the editor to the item or how the editor is destroyed.
In-place editing is implemented in an abstract way to make sure custom edit widgets for certain cells or cell types can be written easily. To obtain this it is possible to place widgets in cells. See setCellWidget(), clearCellWidget() and cellWidget() for further details.
In order to prevent a cell not containing a QTableItem from being edited, you have to reimplement createEditor(). This function should return 0 for cells that must be not edited at all.
It is possible to use QTable without QTableItems. However, as the default implementation of QTable's in-place editing uses QTableItems, you will have to reimplement createEditor() and setCellContentFromEditor() to get in-place editing without QTableItems. The documentation of these two functions explains the details you need to know for that matter.
In order to draw custom content in a cell you have to implement your own subclass of QTableItem and reimplement the QTableItem::paint() method.
If your application stores its data already in a way that allocating a QTableItem for each data containing cell seems inappropriate, you can reimplement QTable::paintCell() and draw the contents directly.
Unless you reimplement them this approach will however prevent you from using functions like setText() etc. Remember that in this case, repainting the cells using updateCell() after each change made is necessary. To make sure you don't waste memory, read the documentation of resizeData().
NoSelection - No cell can be selected by the user.
Single - The user may select one range of cells only.
Multi - Multi-range selections are possible.
Constructs a table of 10 * 10 cells.
Constructs a table with a range of numRows * numCols cells.
Destructor.
[virtual protected]This is called to activate the next cell if in-place editing was finished by pressing the Return key.
If you want a different behaviour then going from top to bottom, reimplement this function.
[virtual]Adds a selection described by s to the table and returns its number or -1 if the selection is invalid. Don't forget to call QTableSelection::init() and QTableSelection::expandTo() to make it valid (see also QTableSelection::isActive()).
[virtual slot]Resizes the column col to be exactly wide enough so that the whole contents is visible.
[virtual slot]Resizes the row row to be exactly high enough so that the whole contents is visible.
[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, else the current content of that cell (if existing) will be edited by the editor.
This function calls createEditor() to get the editor which should be used for editing the cell and after that setCellWidget() to set this editor as the widget of that cell.
See also createEditor(), setCellWidget() and endEdit().
[virtual]Returns the bounding rect of the cell row, col in contents coordinates.
[virtual]Returns the widget which has been set to the cell row, col of 0 if there is no widget.
[virtual]Removes the QTableItem in position row, col.
[virtual]Removes the widget (if there is any) which is set for the cell row, col.
[slot]Clears all selections.
[signal]This signal is emitted as soon as a user clicks on row and col using mousebutton button. The actual mouse position is passed as mousePos.
[virtual]Returns the column which is at pos. pos has to be given in contents coordinates.
[virtual protected slot]This function is called when the column col has been
clicked. The default implementation sorts this column if
sorting() is TRUE.
[virtual protected slot]This function is called if the order of the columns has been changed. If you want to change the order programmatically, call QHeader::moveSection() on the horizontalHeader() or verticalHeader().
Returns whether columns can be moved by the user.
[virtual]Returns the x-position of the column col in contents coordinates.
[virtual]Returns the width of the column col.
[virtual protected slot]This function should be called whenever the column width of col has been changed. It will then rearrange the content appropriately.
[virtual protected]Reimplemented for internal reasons; the API is not affected.
Reimplemented from QScrollView.
[virtual protected]Reimplemented for internal reasons; the API is not affected.
Reimplemented from QScrollView.
[virtual protected]Reimplemented for internal reasons; the API is not affected.
Reimplemented from QScrollView.
[virtual protected]Reimplemented for internal reasons; the API is not affected.
Reimplemented from QScrollView.
[virtual protected]This function returns a widget which should be used as editor for the cell row, col. If initFromCell is TRUE, the editor is used to edit the current content of the cell (so the editor widget should be initialized with that content). Otherwise the content of this cell will be replaced by a new content which the user will enter into the widget which this function should create.
The default implementation looks if there exists a QTableItem for the cell. If this is the case and initFromCell is TRUE or QTableItem::isReplaceable() of the item is FALSE, the item of that cell is asked to create the editor (using QTableItem::createEditor)).
If this is not the case, a QLineEdit is created as editor.
So if you want to create your own editor for certain cells, implement your own QTableItem and reimplement QTableItem::createEditor(). If you want to use a different editor than a QLineEdit as default editor, reimplement this function and use a code like
QTableItem *i = item( row, col );
if ( initFromCell || i && !i->isReplaceable() )
return QTable::createEditor( row, col, initFromCell );
else
return ...(create your editor)
So normally you do not need to reimplement this function. But if you want e.g. work without QTableItems, you will reimplement this function to create the correct editor for the cells.
The ownership of the editor widget is transferred to the caller.
Returning 0 here means that the cell is not editable.
See also QTableItem::createEditor().
[signal]This signal is emitted if the current cell has been changed to row, col.
Returns the current column.
Returns the current row.
[virtual]Returns the number of the current selection or -1 if there is none.
[signal]A double-click with button emits this signal, where row and col denote the position of the cell. The actual mouse position is passed as mousePos.
[virtual protected]Draws the table contents on the painter p. The function is optimized to exclusively draw the cells inside the relevant clipping rectangle cx, cy, cw, ch.
Additionally, drawContents() highlights the current cell.
Reimplemented from QScrollView.
[virtual protected]This function is called if in-place editing of the cell row, col has to be ended. If accept is TRUE the content of the editor of this cell has to be transferred to the cell. If replace is TRUE the current content of that 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), else (if possible) the content of the editor should just be set to the existing QTableItem of this cell.
So, if the cell contents should be replaced or if no QTableItem exists for the cell yet, setCellContentFromEditor() is called, else 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().
Scrolls the table until the cell row, col becomes visible.
[virtual]Reimplemented for internal reasons; the API is not affected.
Reimplemented from QObject.
[virtual protected]Reimplemented for internal reasons; the API is not affected.
Reimplemented from QWidget.
[virtual protected]Reimplemented for internal reasons; the API is not affected.
Reimplemented from QWidget.
[virtual slot]Hides the column col.
See also showCol().
[virtual slot]Hides the row row.
See also showRow().
Returns the top QHeader of the table.
[protected]Maps 2D table to 1D array index.
[virtual protected]Inserts the widget w into the internal datastructure. See the documentation of setCellWidget() for further details.
Returns TRUE if column col is selected, and FALSE otherwise.
If full is TRUE, the entire column must be selected for this function to return TRUE. If full is FALSE, at least one cell in col must be selected.
[slot]Returns wheather the column col is stretchable or not.
See also setColumnStretchable().
Returns TRUE if row is selected, and FALSE otherwise.
If full is TRUE, the entire row must be selected for this function to return TRUE. If full is FALSE, at least one cell in row must be selected.
[slot]Returns wheather the row row is stretchable or not.
See also setRowStretchable().
Checks whether the cell at position row, col is selected.
[virtual]Returns the QTableItem representing the contents of the cell row, col. If row or col are out of range or no content has been set for this cell so far, item() returns 0.
[virtual protected]Reimplemented for internal reasons; the API is not affected.
Reimplemented from QWidget.
Returns the number of columns of the table.
Returns the number of rows of the table.
Returns the number of selections.
[virtual]Paints the cell at the position row, col on the painter p. The painter has already been translated to the cell's origin. cr describes the cell coordinates in the content coordinate system..
If you want to draw custom cell content you have to reimplement paintCell() to do the custom drawing, or else subclass QTableItem and reimplement QTableItem::paint().
Reimplementing this function is probably better e.g. for data you retrieve from a database and draw at once, while using QTableItem::paint() is probably better e.g. if you wish these data to be stored in a data structure in the table.
[virtual protected]This function fills the rectangular cx, cy, cw, ch with the background color. paintEmptyArea() is invoked by drawContents() to erase or fill unused areas.
[virtual]Draws the focus rectangle of the current cell (see currentRow(), currentColumn()). The painter p is already translated to the cell's origin, while cr specifies the cell's geometry in contents coordinates.
[virtual]Returns the pixmap set for the cell row, col, or a null-pixmap if the cell contains no pixmap.
[signal]This signal is emitted whenever the mousebutton button is pressed above the cell located in row and col. The actual mouse position is passed as mousePos.
[virtual]Removes the selection matching the values of s from the table.
[virtual]Removes selection number num.
[virtual protected]This is called when QTable's internal array needs to be resized.
If you don't use QTableItems you should reimplement this as an empty method, thus no memory is wasted. In addition, you will have to reimplement item(), setItem(), and clearCell() as empty functions in a different way.
As soon as you enable sorting or allow the user to change rows or columns (see setRowMovingEnabled(), setColumnMovingEnabled()), you are strongly advised to reimplement swapColumns(), swapRows(), and swapCells() to work with your data.
[virtual protected]Reimplemented for internal reasons; the API is not affected.
Reimplemented from QWidget.
[virtual]Returns the row which is at pos. pos has to be given in contents coordinates.
[virtual]Returns the height of the row row.
[virtual protected slot]Call this function whenever the height of row row has changed in order to rearrange its contents.
[virtual protected slot]This function is called if the order of the rows has been changed. If you want to change the order programmatically, call QHeader::moveSection() on the horizontalHeader() or verticalHeader().
Returns whether rows can be moved by the user.
[virtual]Returns the y-position of the row row in contents coordinates.
Returns selection number num, or an empty QTableSelection if num is out of range (see QTableSelection::isNull()).
[signal]Whenever a selection changes, this signal is emitted.
Reveals the current selection mode.
[virtual protected]This function is called to set the contents of the cell row, col from the editor of this cell to this cell. If there existed already a QTableItem for this cell, this is removed first (see clearCell()).
If you want to create e.g different QTableItems depending on the contents of the editor, you might reimplement this function. Also if you want to work without QTableItems, you will reimplement this function to set the data which the user entered to your datastructure.
See also QTableItem::setContentFromEditor().
[virtual]Sets the widget e to the cell row, col and does all the placement and further stuff and takes care about correctly placing are resizing it when the cell geometry changes.
By default widgets are inserted into a vector with numRows() * numCols() elements. In very big tables you probably want to store the widgets in a datastructure which needs less memory (like a hash-table). To make this possible this functions calls insertWidget() to add the widget to the internal datastructure. So if you want to use your own datastructure, reimplement insertWidget(), cellWidget() and clearCellWidget().
[virtual slot]If b is set to TRUE, columns can be moved by the user.
[virtual slot]Sets the column col to stretchable if stretch is TRUE, else to non-stretchable. So, if the table widgets gets wider than its contents, stretchable columns are stretched so that the contents fits exactly into to widget.
[virtual slot]Resizes the column to w pixel wide.
[virtual slot]Moves the focus to the cell at position row, col.
See also currentRow() and currentColumn().
[virtual]Sets the content for the cell row, col. If cell item already exists in that position, the old one is deleted.
setItem() also repaints the cell.
[virtual slot]Sets the left margin to m pixels.
To get rid of the left header entirely, use the following code:
setLeftMargin( 0 ); verticalHeader()->hide();
[virtual slot]Sets the number of columns to c.
[virtual slot]Sets the number of rows to r.
[virtual]Sets the pixmap in cell row, col to pix. If no QTableItem belongs to the cell yet, an item is created.
[virtual slot]Resizes the row to be h pixel height.
[virtual slot]If b is set to TRUE, rows can be moved by the user.
[virtual slot]Sets the row row to stretchable if stretch is TRUE, else to non-stretchable. So, if the table widgets gets higher than its contents, stretchable rows are stretched so that the contents fits exactly into to widget.
Sets the table's selection mode to mode. By default multi-range
selections (Multi) are allowed.
[virtual slot]If b is TRUE, the table grid is shown, otherwise not. The default is TRUE.
[virtual slot]If b is set to TRUE, clicking on the header of a column sorts this column.
See also sortColumn().
[virtual]Sets the text in cell row, col to text. If no QTableItem belongs to the cell yet, an item is created.
[virtual slot]Sets the top margin to m pixels.
To get rid of the top header entirely, use the following code:
setTopMargin( 0 ); topHeader()->hide();
[virtual slot]Shows the column col.
See also hideColumn().
[virtual protected]Reimplemented for internal reasons; the API is not affected.
Reimplemented from QWidget.
Returns whether the table grid shows up or not.
[virtual slot]Shows the row row.
See also hideRow().
[virtual]Reimplemented for internal reasons; the API is not affected.
Reimplemented from QWidget.
[virtual]Sorts the column col in ascending order if ascending is TRUE, else in descending order. If wholeRows is TRUE, for changing data of the cells swapRows() is called, else swapCells() is called.
See also swapRows().
Returns wheather clicking on a column header sorts the column.
See also setSorting().
[virtual slot]Swaps the content of the cells row1, col1 and row2, col2. This function is used for sorting cells.
[virtual slot]Exchanges col1 with col2 and vice versa. This is useful for sorting, and it allows the user to rearrange the columns in a different order. If you don't use QTableItems you will probably reimplement this function.
[virtual slot]Swaps data of row1 and row2. This is used by sorting mechanisms or when the user changes the order of the rows. If you don't use QTableItems you might wish to reimplement this function.
[virtual]Takes the item i out of the table. This functions doesn't delete it.
[virtual]Returns the text in cell row, col, or an empty string if the relevant item does not exist or includes no text.
Repaints the cell at position row, col.
[signal]This signal is emitted if the user edited the cell row, col.
Returns the outer left QHeader.
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 2.2.1
|