Contents

• Public Types
• Public Functions
• Reimplemented Public Functions
• Public Slots
• Reimplemented Protected Functions
• Detailed Description

Detailed Description

TheQSqlRelationalTableModel class provides an editable data model for a single database table, with foreign key support.

QSqlRelationalTableModel acts likeQSqlTableModel, but allows columns to be set as foreign keys into other database tables.

The screenshot on the left shows a plainQSqlTableModel in aQTableView. Foreign keys (city andcountry) aren't resolved to human-readable values. The screenshot on the right shows aQSqlRelationalTableModel, with foreign keys resolved into human-readable text strings.

The following code snippet shows how theQSqlRelationalTableModel was set up:

    model->setTable("employee");    model->setRelation(2,QSqlRelation("city","id","name"));    model->setRelation(3,QSqlRelation("country","id","name"));

ThesetRelation() function calls establish a relationship between two tables. The first call specifies that column 2 in tableemployee is a foreign key that maps with fieldid of tablecity, and that the view should present thecity'sname field to the user. The second call does something similar with column 3.

If you use a read-writeQSqlRelationalTableModel, you probably want to useQSqlRelationalDelegate on the view. Unlike the default delegate,QSqlRelationalDelegate provides a combobox for fields that are foreign keys into other tables. To use the class, simply callQAbstractItemView::setItemDelegate() on the view with an instance ofQSqlRelationalDelegate:

QTableView*view=newQTableView;    view->setModel(model);    view->setItemDelegate(newQSqlRelationalDelegate(view));

Thesql/relationaltablemodel example illustrates how to useQSqlRelationalTableModel in conjunction withQSqlRelationalDelegate to provide tables with foreign key support.

Notes:

• The table must have a primary key declared.
• The table's primary key may not contain a relation to another table.
• If a relational table contains keys that refer to non-existent rows in the referenced table, the rows containing the invalid keys will not be exposed through the model. The user or the database is responsible for keeping referential integrity.
• If a relation's display column name is also used as a column name in the main table, or if it is used as display column name in more than one relation it will be aliased. The alias is is the relation's table name and display column name joined by an underscore (e.g. tablename_columnname). All occurrences of the duplicate display column name are aliased when duplication is detected, but no aliasing is done to the column names in the main table. The aliasing doesn't affectQSqlRelation, soQSqlRelation::displayColumn() will return the original display column name, butQSqlRecord::fieldName() will return aliases.
• When usingsetData() the role should always beQt::EditRole, and when usingdata() the role should always beQt::DisplayRole.

Member Type Documentation

enum QSqlRelationalTableModel::JoinMode

This enum specifies the type of mode to use when joining two tables.

This enum was introduced or modified in Qt 4.8.

See alsoQSqlRelationalTableModel::setJoinMode().

Member Function Documentation

QSqlRelationalTableModel::QSqlRelationalTableModel(QObject * parent = 0,QSqlDatabase db = QSqlDatabase())

Creates an emptyQSqlRelationalTableModel and sets the parent toparent and the database connection todb. Ifdb is not valid, the default database connection will be used.

[virtual]QSqlRelationalTableModel::~QSqlRelationalTableModel()

Destroys the object and frees any allocated resources.

[virtual]void QSqlRelationalTableModel::clear()

Reimplemented fromQSqlQueryModel::clear().

[virtual]QVariant QSqlRelationalTableModel::data(constQModelIndex & index,int role = Qt::DisplayRole) const

Reimplemented fromQAbstractItemModel::data().

See alsosetData().

[virtual protected]bool QSqlRelationalTableModel::insertRowIntoTable(constQSqlRecord & values)

Reimplemented fromQSqlTableModel::insertRowIntoTable().

[virtual protected]QString QSqlRelationalTableModel::orderByClause() const

Reimplemented fromQSqlTableModel::orderByClause().

QSqlRelation QSqlRelationalTableModel::relation(int column) const

Returns the relation for the columncolumn, or an invalid relation if no relation is set.

See alsosetRelation() andQSqlRelation::isValid().

[virtual]QSqlTableModel * QSqlRelationalTableModel::relationModel(int column) const

Returns aQSqlTableModel object for accessing the table for whichcolumn is a foreign key, or 0 if there is no relation for the givencolumn.

The returned object is owned by theQSqlRelationalTableModel.

See alsosetRelation() andrelation().

[virtual]bool QSqlRelationalTableModel::removeColumns(int column,int count, constQModelIndex & parent = QModelIndex())

Reimplemented fromQAbstractItemModel::removeColumns().

[virtual slot]void QSqlRelationalTableModel::revertRow(int row)

Reimplemented fromQSqlTableModel::revertRow().

[virtual]bool QSqlRelationalTableModel::select()

Reimplemented fromQSqlTableModel::select().

[virtual protected]QString QSqlRelationalTableModel::selectStatement() const

Reimplemented fromQSqlTableModel::selectStatement().

[virtual]bool QSqlRelationalTableModel::setData(constQModelIndex & index, constQVariant & value,int role = Qt::EditRole)

Reimplemented fromQAbstractItemModel::setData().

Sets the data for therole in the item with the specifiedindex to thevalue given. Depending on the edit strategy, the value might be applied to the database at once, or it may be cached in the model.

Returns true if the value could be set, or false on error (for example, ifindex is out of bounds).

For relational columns,value must be the index, not the display value. The index must also exist in the referenced table, otherwise the function returns false.

See alsoeditStrategy(),data(),submit(), andrevertRow().

void QSqlRelationalTableModel::setJoinMode(QSqlRelationalTableModel::JoinMode joinMode)

Sets the SQL join mode to the value given byjoinMode to show or hide rows with NULL foreign keys.

InInnerJoin mode (the default) these rows will not be shown; use theLeftJoin mode if you want to show them.

This function was introduced in Qt 4.8.

See alsoQSqlRelationalTableModel::JoinMode.

[virtual]void QSqlRelationalTableModel::setRelation(int column, constQSqlRelation & relation)

Lets the specifiedcolumn be a foreign index specified byrelation.

Example:

    model->setTable("employee");    model->setRelation(2,QSqlRelation("city","id","name"));

The setRelation() call specifies that column 2 in tableemployee is a foreign key that maps with fieldid of tablecity, and that the view should present thecity'sname field to the user.

Note: The table's primary key may not contain a relation to another table.

See alsorelation().

[virtual]void QSqlRelationalTableModel::setTable(constQString & table)

Reimplemented fromQSqlTableModel::setTable().

[virtual protected]bool QSqlRelationalTableModel::updateRowInTable(int row, constQSqlRecord & values)

Reimplemented fromQSqlTableModel::updateRowInTable().