Qtopia Home - Classes - Hierachy - Annotated - Functions - Licenses - Reference

QTable Class Reference
[table module]

A flexible and editable table widget. More...

#include <qtable.h>

Inherits QScrollView.

List of all member functions.

Public Members

Public Slots

Signals

Properties

Protected Members

Protected Slots

Detailed Description

A flexible and editable table widget.

QTable has been designed to use 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. You should also reimplement QTable::paintCell() if you wish to change the alignment of your items in the QTable.

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().

Member Type Documentation

QTable::SelectionMode

Member Function Documentation

QTable::QTable ( QWidget * parent = 0, const char * name = 0 )

Constructs a table of 10 * 10 cells.

Performance is boosted by modifying the widget flags so that only part of the QTableItem children is redrawn. This may be unsuitable for custom QTableItem classes, in which case WNorthWestGravity and WRepaintNoErase should be cleared.

See also QWidget::clearWFlags() and Qt::WidgetFlags.

QTable::QTable ( int numRows, int numCols, QWidget * parent = 0, const char * name = 0 )

Constructs a table with a range of numRows * numCols cells.

Performance is boosted by modifying the widget flags so that only part of the QTableItem children is redrawn. This may be unsuitable for custom QTableItem classes, in which case the widget flags should be reset using QWidget::setWFlags().

QTable::~QTable ()

Destructor.

void QTable::activateNextCell () [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.

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. Don't forget to call QTableSelection::init() and QTableSelection::expandTo() to make it valid (see also QTableSelection::isActive()).

void QTable::adjustColumn ( int col ) [virtual slot]

Resizes the column col to be exactly wide enough so that the whole contents is visible.

void QTable::adjustRow ( int row ) [virtual slot]

Resizes the row row to be exactly high enough so that the whole contents is visible.

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, 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().

QRect QTable::cellGeometry ( int row, int col ) const [virtual]

Returns the bounding rect of the cell row, col in contents coordinates.

QWidget * QTable::cellWidget ( int row, int col ) const [virtual]

Returns the widget which has been set to the cell row, col of 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) which is set for the cell row, col.

void QTable::clearSelection ( bool repaint = TRUE ) [slot]

Clears all selections.

void QTable::clicked ( int row, int col, int button, const QPoint & mousePos ) [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.

int QTable::columnAt ( int pos ) const [virtual]

Returns the column which is at pos. pos has to be given in contents 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 s, int oi, int ni ) [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 swapRows() or swapColumns().

bool QTable::columnMovingEnabled () const

Returns whether columns can be moved by the user.

int QTable::columnPos ( int col ) const [virtual]

Returns the x-position of the column col in contents coordinates

int QTable::columnWidth ( int col ) const [virtual]

Returns the width of the 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 will then rearrange the content appropriately.

QWidget * QTable::createEditor ( int row, int col, bool initFromCell ) const [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().

void QTable::currentChanged ( int row, int col ) [signal]

This signal is emitted if the current cell has been changed to row, col.

int QTable::currentColumn () const

Returns the current column.

int QTable::currentRow () const

Returns the current row.

int QTable::currentSelection () const [virtual]

Returns the number of the current selection or -1 if there is none.

void QTable::doubleClicked ( int row, int col, int button, const QPoint & mousePos ) [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.

void QTable::drawContents ( QPainter * p, int cx, int cy, int cw, int ch ) [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.

void QTable::endEdit ( int row, int col, bool accept, bool replace ) [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().

void QTable::ensureCellVisible ( int row, int col )

Scrolls the table until the cell row, col becomes visible.

void QTable::hideColumn ( int col ) [virtual slot]

Hides the column col.

See also showCol().

void QTable::hideRow ( int row ) [virtual slot]

Hides the row row.

See also showRow().

QHeader * QTable::horizontalHeader () const

Returns the top QHeader of the table.

int QTable::indexOf ( int row, int col ) const [protected]

Maps 2D table to 1D array index.

void QTable::insertWidget ( int row, int col, QWidget * w ) [virtual protected]

Inserts the widget w into the internal datastructure. See the documentation of setCellWidget() for further details.

bool QTable::isColumnSelected ( int col, bool full = FALSE ) const

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.

bool QTable::isColumnStretchable ( int col ) const [slot]

Returns wheather the column col is stretchable or not.

See also setColumnStretchable().

bool QTable::isRowSelected ( int row, bool full = FALSE ) const

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.

bool QTable::isRowStretchable ( int row ) const [slot]

Returns wheather the row row is stretchable or not.

See also setRowStretchable().

bool QTable::isSelected ( int row, int col ) const

Checks whether the cell at position row, col is selected.

QTableItem * QTable::item ( int row, int col ) const [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.

int QTable::numCols () const

Returns the number of columns of the table.

int QTable::numRows () const

Returns the number of rows of the table.

int QTable::numSelections () const

Returns the number of selections.

void QTable::paintCell ( QPainter * p, int row, int col, const QRect & cr, bool selected ) [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().

If you want to change the alignment of your items then you will need to reimplement paintCell().

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.

void QTable::paintEmptyArea ( QPainter * p, int cx, int cy, int cw, int ch ) [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.

void QTable::paintFocus ( QPainter * p, const QRect & cr ) [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.

QPixmap QTable::pixmap ( int row, int col ) const [virtual]

Returns the pixmap set for the cell row, col, or a null-pixmap if the cell contains no pixmap.

void QTable::pressed ( int row, int col, int button, const QPoint & mousePos ) [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.

void QTable::removeSelection ( const QTableSelection & s ) [virtual]

Removes the selection matching the values of s from the table.

void QTable::removeSelection ( int num ) [virtual]

Removes selection number num.

void QTable::resizeData ( int len ) [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.

int QTable::rowAt ( int pos ) const [virtual]

Returns the row which is at pos. pos has to be given in contents coordinates.

int QTable::rowHeight ( int row ) const [virtual]

Returns the height of the row row.

void QTable::rowHeightChanged ( int row ) [virtual protected slot]

Call this function whenever the height of row row has changed in order to rearrange its contents.

void QTable::rowIndexChanged ( int s, int oi, int ni ) [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 swapRows() or swapColumns().

bool QTable::rowMovingEnabled () const

Returns whether rows can be moved by the user.

int QTable::rowPos ( int row ) const [virtual]

Returns the y-position of the row row in contents coordinates

QTableSelection QTable::selection ( int num ) const

Returns selection number num, or an empty QTableSelection if num is out of range (see QTableSelection::isNull()).

void QTable::selectionChanged () [signal]

Whenever a selection changes, this signal is emitted.

SelectionMode QTable::selectionMode () const

Reveals the current selection mode.

void QTable::setCellContentFromEditor ( int row, int col ) [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().

void QTable::setCellWidget ( int row, int col, QWidget * e ) [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().

void QTable::setColumnMovingEnabled ( bool b ) [virtual slot]

If b is set to TRUE, columns can be moved by the user.

void QTable::setColumnStretchable ( int col, bool stretch ) [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.

void QTable::setColumnWidth ( int col, int w ) [virtual slot]

Resizes the column to w pixel wide.

void QTable::setCurrentCell ( int row, int col ) [virtual slot]

Moves the focus to the cell at position row, col.

See also currentRow() and currentColumn().

void QTable::setItem ( int row, int col, QTableItem * item ) [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.

void QTable::setLeftMargin ( int m ) [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();

void QTable::setNumCols ( int c ) [virtual slot]

Sets the number of columns to c.

void QTable::setNumRows ( int r ) [virtual slot]

Sets the number of rows to r.

void QTable::setPixmap ( int row, int col, const QPixmap & pix ) [virtual]

Sets the pixmap in cell row, col to pix. If no QTableItem belongs to the cell yet, an item is created.

void QTable::setRowHeight ( int row, int h ) [virtual slot]

Resizes the row to be h pixel height.

void QTable::setRowMovingEnabled ( bool b ) [virtual slot]

If b is set to TRUE, rows can be moved by the user.

void QTable::setRowStretchable ( int row, bool stretch ) [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.

void QTable::setSelectionMode ( SelectionMode mode ) [virtual]

Sets the table's selection mode to mode. By default multi-range selections (Multi) are allowed.

void QTable::setShowGrid ( bool b ) [virtual slot]

If b is TRUE, the table grid is shown, otherwise not. The default is TRUE.

void QTable::setSorting ( bool b ) [virtual slot]

If b is set to TRUE, clicking on the header of a column sorts this column.

See also sortColumn().

void QTable::setText ( int row, int col, const QString & text ) [virtual]

Sets the text in cell row, col to text. If no QTableItem belongs to the cell yet, an item is created.

void QTable::setTopMargin ( int m ) [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();

void QTable::showColumn ( int col ) [virtual slot]

Shows the column col.

See also hideColumn().

bool QTable::showGrid () const

Returns whether the table grid shows up or not.

void QTable::showRow ( int row ) [virtual slot]

Shows the row row.

See also hideRow().

void QTable::sortColumn ( int col, bool ascending = TRUE, bool wholeRows = FALSE ) [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().

bool QTable::sorting () const

Returns wheather clicking on a column header sorts the column.

See also setSorting().

void QTable::swapCells ( int row1, int col1, int row2, int col2 ) [virtual slot]

Swaps the content of the cells row1, col1 and row2, col2. This function is used for sorting cells.

void QTable::swapColumns ( int col1, int col2 ) [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.

void QTable::swapRows ( int row1, int row2 ) [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.

void QTable::takeItem ( QTableItem * i ) [virtual]

Takes the item i out of the table. This functions doesn't delete it.

QString QTable::text ( int row, int col ) const [virtual]

Returns the text in cell row, col, or an empty string if the relevant item does not exist or includes no text.

void QTable::updateCell ( int row, int col )

Repaints the cell at position row, col.

void QTable::valueChanged ( int row, int col ) [signal]

This signal is emitted if the user edited the cell row, col.

QHeader * QTable::verticalHeader () const

Returns the outer left QHeader.

This file is part of the Qtopia platform, copyright © 1995-2005 Trolltech, all rights reserved.

Copyright © 2005 Trolltech Trademarks
Qtopia version 2.2.0