Classes - Annotated - Tree - Functions - Home - Structure

QTableItem Class Reference
[table module]

The QTableItem class provides the cell content in a QTable. More...

#include <qtable.h>

Inherits Qt.

Inherited by QComboTableItem and QCheckTableItem.

List of all member functions.

Public Members


Detailed Description

The QTableItem class provides the cell content in a QTable.

A QTableItem contains the data of a table cell and provides means to change them. It specifies whether and under which circumstances the cell might be edited by the user (see EditType) and the kind of editor that is used for changing its content.

Items may contain a text string and one pixmap each. If a pixmap has been defined it is presented to the left of the text. By default a QLineEdit that aligns its input to the left is provided for editing.

Furthermore, a QTableItem defines the cell size and the alignment of the displayed data. The item defines whether the respective cell data can be replaced, and whether word wrapping is desired when cell contents exceed the width of the cell. In addition the QTableItem class provides the API needed for sorting table items.

QTableItems are added to a QTable using QTable::setItem(). As long as they haven't been attached to the table this way QTable cells are empty.

To get rid of an item, simply delete it. By doing so, all required actions for removing it from the table are taken.

To define another editor you have to reimplement createEditor() and setContentFromEditor(). By reimplementing paint() and adding the relevant set- and "get"-functions custom subclasses of QTableItem may overcome the restriction of one text string and one pixmap per cell. If sorting is required reimplementing the key() function might be neccessary.


Member Type Documentation

QTableItem::EditType

This enum is used to define whether a cell is editable or read-only (possibly in conjunction with other settings) and how the cell should be displayed.

Note that QComboTableItems have an isEditable() property. This property is used to indicate whether the user may enter their own text or are restricted to choosing one of the choices in the list. QComboTableItems may be edited (i.e. interacted with) only if they are editable in accordance with their EditType as described above.


Member Function Documentation

QTableItem::QTableItem ( QTable * table, EditType et, const QString & text )

Creates a table item for the table table that contains the text text. et determines its EditType.

To insert the item into a table use QTable::setItem():

        QTableItem * discount = new QTableItem( this, QTableItem::Always,
                                                "-0.00" );
        setItem( discountRow, 3, discount );

(Code taken from table/wineorder2/productlist.cpp )

Whilst the parent of the item (i.e. table) and the QTable it has been inserted into might occasionally be different, a table item can't be inserted into more than one tables at a time.

QTableItem::QTableItem ( QTable * table, EditType et, const QString & text, const QPixmap & p )

Creates a child item of the table table with the text text and the pixmap p. The item has the EditType et.

When shown in a table cell the pixmap appears to the left of text.

To insert the item into table (or another QTable object) use QTable::setItem().

Whilst the parent of the item (i.e. table) and the QTable it has been inserted into might occasionally be different, a table item can't be inserted into more than one tables at a time.

QTableItem::~QTableItem () [virtual]

The destructor deletes this item and frees all allocated resources.

If the item has been attached to a table it is safely removed from it.

int QTableItem::alignment () const [virtual]

The alignment function returns how text contents of the cell are drawn. The default implementation aligns numbers to the right and other text to the left.

See also Qt::AlignmentFlags.

int QTableItem::col () const

Returns the column where the item is located. If the cell spans multiple columns, this function returns the leftmost column.

See also row() and setCol().

int QTableItem::colSpan () const

Returns the column span of the item, usually 1.

See also setSpan() and rowSpan().

QWidget * QTableItem::createEditor () const [virtual]

This virtual function creates the editor with which the user can edit the cell. The default implementation creates a QLineEdit that aligns everything to the left.

If the function returns 0, the relevant cell cannot be edited.

The returned widget should preferably be unvisible, and it should have QTable::viewport() as parent.

If you reimplement this function, you probably also need to reimplement setContentFromEditor().

    QWidget * SpinBoxItem::createEditor() const
    {
        QSpinBox * quantities = new QSpinBox( table->viewport(), "quantities" );
        return quantities;
    }

(Code taken from table/wineorder2/spinboxitem.cpp )

See also QTable::createEditor(), setContentFromEditor() and QTable::viewport().

Example: table/wineorder2/spinboxitem.cpp.

EditType QTableItem::editType () const

Returns the edit type of an item.

This is determined at creation time of the item object. Items automatically created by the convenient functions QTable::setText() and QTable::setPixmap() default to QTableItem::OnTyping.

See also EditType and QTableItem().

bool QTableItem::isEnabled () const

Returns whether the item is enabled or disabled.

See also setEnabled().

bool QTableItem::isReplaceable () const

This function returns whether the relevant QTableItem can be replaced with another item or not. Only items that cover no more than one cell might be replaced.

Note that this property is about exchanging one table item with another and not about whether the content of one item might be changed.

See also setReplaceable() and EditType.

Example: table/wineorder/productlist.cpp.

QString QTableItem::key () const [virtual]

This virtual function returns the key that should be used for sorting. The default implementation returns the text() of the relevant item.

See also QTable::setSorting.

void QTableItem::paint ( QPainter * p, const QColorGroup & cg, const QRect & cr, bool selected ) [virtual]

This virtual function is used to paint the contents of an item on the painter p in the rectangular area cr using the color group cg.

If selected is TRUE the cell is represented in a highlighted manner.

Usually you don't need to use this function but if you want to draw custom content in a cell you have to reimplement it.

QPixmap QTableItem::pixmap () const [virtual]

Returns the item's pixmap or a null-pixmap if no pixmap has been set so far.

In the default implementation no more than one pixmap per item are allowed.

See also setPixmap() and text().

int QTableItem::row () const

Returns the row where the item is located. If the cell spans multiple rows, this function returns the top most of them.

See also col() and setRow().

int QTableItem::rowSpan () const

Returns the row span of an item, usually 1.

See also setSpan() and colSpan().

int QTableItem::rtti () const [virtual]

Returns the Run Time Type Identification number of this item. All QTableItem objects of the default implementation return 0.

Although often frowned upon by purists, Run Time Type Identification is very useful for QTables as it allows for an efficient indexed storage mechanism.

To distinguish between table items of various types create custom classes derived from QTableItem and make them return one unique rtti() value each. It is advisable to use values greater than 1000, preferably large random numbers, to allow for extensions to this class.

See also QCheckTableItem::rtti() and QComboTableItem::rtti().

Reimplemented in QComboTableItem and QCheckTableItem.

void QTableItem::setCol ( int c ) [virtual]

Makes c the item's column. Usually you will not need to call this function.

If the cell spans multiple columns, this function sets the leftmost column and retains the width.

See also col(), setRow() and colSpan().

void QTableItem::setContentFromEditor ( QWidget * w ) [virtual]

Whenever the content of a cell has been edited by the editor w, QTable calls this virtual function to copy the new values into the QTableItem.

You probably must reimplement this function if you reimplement createEditor() and return something that is not a QLineEdit.

    void SpinBoxItem::setContentFromEditor( QWidget * spinbox )
    {
        setText( ( (QSpinBox *) spinbox )->text() );
    }

(Code taken from table/wineorder2/spinboxitem.cpp )

See also QTable::setCellContentFromEditor().

Example: table/wineorder2/spinboxitem.cpp.

void QTableItem::setEnabled ( bool b ) [virtual]

If b is TRUE, the item is enabled, otherwise it is disabled.

A disabled item doesn't react to user input.

See also isEnabled().

void QTableItem::setPixmap ( const QPixmap & p ) [virtual]

Makes p the pixmap of this item.

If text() has been defined for the item the pixmap is by default presented on its left hand side.

Note that setPixmap() does not update the cell the item belongs to. Use QTable::updateCell() to repaint cell contents immediately.

For QComboTableItems and QCheckTableItems this function has no visible effect.

See also QTable::setPixmap(), pixmap() and setText().

void QTableItem::setReplaceable ( bool b ) [virtual]

If it shouldn't be possible to replace the contents of the relevant cell with those of another QTableItem, set b to FALSE.

Mind the difference between this property and the EditType that defines whether the user is able to change the content of a dedicated table item.

See also isReplaceable().

void QTableItem::setRow ( int r ) [virtual]

This function determines r as the item's row. Usually you do not need to call this function.

If the cell spans multiple rows, this function sets the top row and retains the height.

See also row(), setCol() and rowSpan().

void QTableItem::setSpan ( int rs, int cs ) [virtual]

Creates a multi-cell QTableItem covering rs rows and cs columns. The top left corner of the item is at the item's former position.

See also rowSpan() and colSpan().

void QTableItem::setText ( const QString & str ) [virtual]

Changes the text of the item to str. Note that the cell is not repainted.

        suffix = " btls";
       setText( QString::number( value ) + suffix );

(Code taken from table/wineorder2/productlist.cpp and table/wineorder2/spinboxitem.cpp )

See also QTable::setText(), text(), setPixmap() and QTable::updateCell().

void QTableItem::setWordWrap ( bool b ) [virtual]

If b is TRUE, the cell's text is wrapped into multiple lines, otherwise it will be written on one line.

See also wordWrap().

QSize QTableItem::sizeHint () const [virtual]

This virtual function returns the size a cell needs to show its entire content.

Custom table items will often require reimplementation of this function.

QTable * QTableItem::table () const

Returns the QTable the item belongs to.

Note that this is the parent table object of the item even if the item fills a cell of another table.

See also QTable::setItem() and QTableItem().

QString QTableItem::text () const [virtual]

Provides the text of the item or an empty string.

See also setText() and pixmap().

bool QTableItem::wordWrap () const

If word wrap has been turned on for the cell in question, wordWrap() is TRUE, otherwise it returns FALSE.

See also setWordWrap().


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 TrolltechTrademarks
Qt version main-beta1