Класс QSqlTableModel

Класс QSqlTableModel предоставляет редактируемую модель данных для одной таблицы базы данных. Подробнее...

• Список всех членов, включая унаследованные члены

Открытые типы

Открытые функции

Переопределённые открытые функции

Открытые слоты

Сигналы

Защищённые функции

Переопределённые защищённые функции

Подробное описание

QSqlTableModel — это высокоуровневый интерфейс для чтения и записи записей базы данных из одной таблицы. Он построен поверх более низкоуровневого QSqlQuery и может использоваться для предоставления данных классам представлений, таким как QTableView. Например:

    QSqlTableModel *model = new QSqlTableModel;
    model->setTable("employee");
    model->setEditStrategy(QSqlTableModel::OnManualSubmit);
    model->select();
    model->setHeaderData(0, Qt::Horizontal, tr("Name"));
    model->setHeaderData(1, Qt::Horizontal, tr("Salary"));

    QTableView *view = new QTableView;
    view->setModel(model);
    view->hideColumn(0); // don't show the ID
    view->show();

Мы задаём имя таблицы SQL и стратегию редактирования, затем настраиваем метки, отображаемые в заголовке представления. Стратегия редактирования определяет, когда изменения, внесённые пользователем в представлении, фактически применяются к базе данных. Возможные значения — OnFieldChange, OnRowChange и OnManualSubmit.

QSqlTableModel также можно использовать для доступа к базе данных программно, не связывая её с представлением:

    QSqlTableModel model;
    model.setTable("employee");
    model.select();
    int salary = model.record(4).value("salary").toInt();

В приведенном фрагменте кода извлекается поле salary из записи 4 в наборе результатов запроса SELECT * from employee.

Возможна установка фильтров с помощью setFilter() или изменение порядка сортировки с помощью setSort(). В конце необходимо вызвать select() для заполнения модели данными.

Пример tablemodel демонстрирует, как использовать QSqlTableModel в качестве источника данных для QTableView.

QSqlTableModel не предоставляет прямой поддержки внешних ключей. Используйте QSqlRelationalTableModel и QSqlRelationalDelegate, если вам нужно разрешить внешние ключи.

См. также QSqlRelationalTableModel, QSqlQuery, Модель/Представление, Пример модели таблицы и Пример кэшированной таблицы.

Документация по типам членов

перечисление QSqlTableModel::EditStrategy

Этот тип перечисления описывает стратегию выбора при редактировании значений в базе данных.

Примечание: Для предотвращения вставки только частично инициализированных строк в базу данных, OnFieldChange будет вести себя как OnRowChange для вновь вставленных строк.

См. также setEditStrategy().

Документация по документации функций-членов

QSqlTableModel::QSqlTableModel(QObject *parent = nullptr, QSqlDatabase db = QSqlDatabase())

Создаёт пустой QSqlTableModel и устанавливает родителя в parent, а подключение к базе данных — в db. Если db недействительно, будет использоваться подключение к базе данных по умолчанию.

По умолчанию стратегия редактирования — OnRowChange.

[signal] void QSqlTableModel::beforeDelete(int row)

Этот сигнал излучается deleteRowFromTable() перед удалением строки row из активной таблицы базы данных.

[signal] void QSqlTableModel::beforeInsert(QSqlRecord &record)

Этот сигнал излучается insertRowIntoTable() перед вставкой новой строки в активную таблицу базы данных. Значения, которые будут вставлены, хранятся в record и могут быть изменены перед вставкой.

[signal] void QSqlTableModel::beforeUpdate(int row, QSqlRecord &record)

Этот сигнал излучается updateRowInTable() перед обновлением строки row в активной таблице базы данных значениями из record.

Обратите внимание, что обновляются только поля, помеченные как сгенерированные. Флаг generated можно установить с помощью QSqlRecord::setGenerated() и проверить с помощью QSqlRecord::isGenerated().

См. также QSqlRecord::isGenerated().

[signal] void QSqlTableModel::primeInsert(int row, QSqlRecord &record)

Этот сигнал излучается insertRows() при инициировании вставки в заданной строке row активной таблицы базы данных. Параметр record может быть записан в (поскольку это ссылка), например, для заполнения некоторых полей значениями по умолчанию и установки флагов сгенерированных полей. Не пытайтесь редактировать запись другими способами, такими как setData() или setRecord() при обработке этого сигнала.

[override virtual slot] void QSqlTableModel::revert()

Переопределяет: QAbstractItemModel::revert().

Этот переопределённый слот вызывается делегатами элементов при отмене редактирования текущей строки пользователем.

Отменяет изменения, если стратегия модели установлена в OnRowChange или OnFieldChange. Не выполняет никаких действий для стратегии OnManualSubmit.

Используйте revertAll() для отмены всех ожидаемых изменений для стратегии OnManualSubmit или revertRow() для отмены конкретной строки.

См. также submit(), submitAll(), revertRow() и revertAll().

[slot] void QSqlTableModel::revertAll()

Отменяет все ожидаемые изменения.

См. также revert(), revertRow() и submitAll().

[virtual slot] bool QSqlTableModel::select()

Заполняет модель данными из таблицы, заданной с помощью setTable(), используя указанный фильтр и условие сортировки, и возвращает true при успехе; в противном случае возвращает false.

Примечание: Вызов select() отменит любые неподтверждённые изменения и удалит любые вставленные столбцы.

См. также setTable(), setFilter() и selectStatement().

[virtual slot] bool QSqlTableModel::selectRow(int row)

Обновляет строку row в модели значениями из строки таблицы базы данных, соответствующей значениям первичного ключа. Без первичного ключа все значения столбцов должны совпадать. Если соответствующая строка не найдена, модель покажет пустую строку.

Возвращает true при успехе; в противном случае возвращает false.

Эта функция была добавлена в Qt 5.0.

См. также select().

[override virtual slot] bool QSqlTableModel::submit()

Переопределяет: QAbstractItemModel::submit().

Этот переопределённый слот вызывается делегатами элементов при завершении редактирования текущей строки пользователем.

Подтверждает текущую редактируемую строку, если стратегия модели установлена в OnRowChange или OnFieldChange. Не выполняет никаких действий для стратегии OnManualSubmit.

Используйте submitAll() для подтверждения всех ожидаемых изменений для стратегии OnManualSubmit.

Возвращает true при успехе; в противном случае возвращает false. Используйте lastError() для запроса подробной информации об ошибке.

Не перестраивает модель автоматически. Подтверждённые строки обновляются из базы данных при успехе.

См. также revert(), revertRow(), submitAll(), revertAll() и lastError().

[slot] bool QSqlTableModel::submitAll()

Подтверждает все ожидаемые изменения и возвращает true при успехе. Возвращает false при ошибке, подробную информацию об ошибке можно получить с помощью lastError().

В режиме OnManualSubmit при успехе модель будет перестроена. Любые представления, которые её отображают, потеряют свои выделения.

Примечание: В режиме OnManualSubmit уже подтверждённые изменения не будут очищены из кэша при неудаче submitAll(). Это позволяет отменять транзакции и повторно подтверждать их без потери данных.

См. также revertAll() и lastError().

[virtual] QSqlTableModel::~QSqlTableModel()

Уничтожает объект и освобождает все выделенные ресурсы.

[override virtual] void QSqlTableModel::clear()

Реализует: QSqlQueryModel::clear().

[override virtual] QVariant QSqlTableModel::data(const QModelIndex &index, int role = Qt::DisplayRole) const

Реализует: QSqlQueryModel::data(const QModelIndex &item, int role) const.

См. также setData().

QSqlDatabase QSqlTableModel::database() const

Возвращает подключение к базе данных модели.

[virtual protected] bool QSqlTableModel::deleteRowFromTable(int row)

Удаляет заданную строку row из текущей активной таблицы базы данных.

Это метод низкого уровня, который работает непосредственно с базой данных и не должен вызываться напрямую. Используйте removeRow() или removeRows() для удаления значений. Модель сама решит, когда изменить базу данных в зависимости от своей стратегии редактирования.

Возвращает true если строка была удалена; в противном случае возвращает false.

См. также removeRow() и removeRows().

QSqlTableModel::EditStrategy QSqlTableModel::editStrategy() const

Возвращает текущую стратегию редактирования.

См. также setEditStrategy().

int QSqlTableModel::fieldIndex(const QString &fieldName) const

Возвращает индекс поля fieldName или -1, если соответствующее поле не существует в модели.

QString QSqlTableModel::filter() const

Возвращает текущий установленный фильтр.

См. также setFilter() и select().

[override virtual] Qt::ItemFlags QSqlTableModel::flags(const QModelIndex &index) const

Реализует: QAbstractTableModel::flags(const QModelIndex &index) const.

[override virtual] QVariant QSqlTableModel::headerData(int section, Qt::Orientation orientation, int role = Qt::DisplayRole) const

Реализует: QSqlQueryModel::headerData(int section, Qt::Orientation orientation, int role) const.

[override virtual protected] QModelIndex QSqlTableModel::indexInQuery(const QModelIndex &item) const

Реализует: QSqlQueryModel::indexInQuery(const QModelIndex &item) const.

Возвращает индекс значения в наборе результатов базы данных для данного item в модели.

Возвращаемое значение идентично item, если столбцы или строки не были вставлены, удалены или перемещены.

Возвращает недействительный индекс модели, если item находится за пределами границ или если item не указывает на значение в наборе результатов.

См. также QSqlQueryModel::indexInQuery().

bool QSqlTableModel::insertRecord(int row, const QSqlRecord &record)

Вставляет record в позицию row. Если row отрицательное, запись будет добавлена в конец. Вызывает insertRows() и setRecord() внутри.

Возвращает true если запись была вставлена, в противном случае false.

Изменения отправляются немедленно для OnFieldChange и OnRowChange. Ошибка не оставит новую строку в модели.

См. также insertRows(), removeRows() и setRecord().

[virtual protected] bool QSqlTableModel::insertRowIntoTable(const QSqlRecord &values)

Вставляет значения values в текущую активную таблицу базы данных.

Это метод низкого уровня, который работает непосредственно с базой данных и не должен вызываться напрямую. Используйте insertRow() и setData() для вставки значений. Модель сама решит, когда изменить базу данных в зависимости от своей стратегии редактирования.

Возвращает true если значения были вставлены, в противном случае false. Информацию об ошибке можно получить с помощью lastError().

См. также lastError(), insertRow() и insertRows().

[override virtual] bool QSqlTableModel::insertRows(int row, int count, const QModelIndex &parent = QModelIndex())

Реализует: QAbstractItemModel::insertRows(int row, int count, const QModelIndex &parent).

Вставляет count пустых строк в позицию row. Обратите внимание, что parent должен быть недействительным, так как эта модель не поддерживает родительско-дочерние отношения.

Для стратегий редактирования OnFieldChange и OnRowChange может быть вставлена только одна строка за раз, и модель не может содержать другие сохранённые изменения.

Сигнал primeInsert() будет выпущен для каждой новой строки. Подключитесь к нему, если хотите инициализировать новую строку значениями по умолчанию.

Не отправляет строки, независимо от стратегии редактирования.

Возвращает false если параметры находятся вне границ или строка не может быть вставлена; в противном случае возвращает true.

См. также primeInsert() и insertRecord().

bool QSqlTableModel::isDirty(const QModelIndex &index) const

Возвращает true если значение по индексу index является изменённым, в противном случае false. Изменённые значения — это значения, которые были изменены в модели, но ещё не записаны в базу данных.

Если index недействителен или указывает на несуществующую строку, возвращается false.

bool QSqlTableModel::isDirty() const

Это перегруженный метод.

Возвращает true если модель содержит изменённые значения, которые не были сохранены в базе данных, в противном случае false.

Этот метод был добавлен в Qt 5.0.

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

Возвращает SQL-оператор ORDER BY на основе текущего порядка сортировки.

См. также setSort() и selectStatement().

QSqlIndex QSqlTableModel::primaryKey() const

Возвращает первичный ключ для текущей таблицы или пустой QSqlIndex, если таблица не установлена или не имеет первичного ключа.

См. также setTable(), setPrimaryKey() и QSqlDatabase::primaryIndex().

[protected] QSqlRecord QSqlTableModel::primaryValues(int row) const

Возвращает запись, содержащую поля, представленные в первичном ключе, установленные на значения в row. Если первичный ключ не определён, возвращаемая запись будет содержать все поля.

Этот метод был добавлен в Qt 5.1.

См. также primaryKey().

QSqlRecord QSqlTableModel::record() const

Это перегруженный метод.

Возвращает пустую запись, содержащую только имена полей. Этот метод может использоваться для получения имён полей записи.

См. также setRecord() и QSqlRecord::isEmpty().

QSqlRecord QSqlTableModel::record(int row) const

Возвращает запись в позиции row в модели.

Если row — индекс корректной строки, запись будет заполнена значениями из этой строки.

Если модель не инициализирована, будет возвращена пустая запись.

Этот метод был добавлен в Qt 5.0.

См. также QSqlRecord::isEmpty().

[override virtual] bool QSqlTableModel::removeColumns(int column, int count, const QModelIndex &parent = QModelIndex())

Реализует: QSqlQueryModel::removeColumns(int column, int count, const QModelIndex &parent).

Удаляет count столбцов из модели parent, начиная с индекса column.

Возвращает true, если столбцы были успешно удалены; в противном случае возвращает false.

См. также removeRows().

[override virtual] bool QSqlTableModel::removeRows(int row, int count, const QModelIndex &parent = QModelIndex())

Переопределяет: QAbstractItemModel::removeRows(int row, int count, const QModelIndex &parent).

Удаляет count строк, начиная со строки row. Поскольку эта модель не поддерживает иерархические структуры, parent должна быть недействительным индексом модели.

Когда стратегия редактирования — OnManualSubmit, удаление строк из базы данных откладывается до вызова submitAll().

Для OnFieldChange и OnRowChange может быть удалена только одна строка за раз и только если ни в одной другой строке нет кэшированных изменений. Удаления отправляются в базу данных немедленно. Модель сохраняет пустую строку для успешно удалённой строки до момента обновления с помощью select().

После неудачного удаления операция не отменяется в модели. Приложение может повторить или отменить операцию.

Вставленные, но ещё не успешно отправленные строки в удаляемом диапазоне немедленно удаляются из модели.

Перед удалением строки из базы данных посылается сигнал beforeDelete().

Если row < 0 или row + count > rowCount(), никаких действий не выполняется и возвращается false. Возвращает true если все строки были удалены; в противном случае возвращает false. Подробную информацию об ошибке базы данных можно получить с помощью lastError().

См. также removeColumns() и insertRows().

[virtual] void QSqlTableModel::revertRow(int row)

Отменяет все изменения для указанной row.

См. также revert(), revertAll(), submit(), и submitAll().

[override virtual] int QSqlTableModel::rowCount(const QModelIndex &parent = QModelIndex()) const

Переопределяет: QSqlQueryModel::rowCount(const QModelIndex &parent) const.

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

Возвращает используемое внутри SQL SELECT-выражение для заполнения модели. Выражение включает фильтр и ORDER BY-оператор.

См. также filter() и orderByClause().

[override virtual] bool QSqlTableModel::setData(const QModelIndex &index, const QVariant &value, int role = Qt::EditRole)

Переопределяет: QAbstractItemModel::setData(const QModelIndex &index, const QVariant &value, int role).

Устанавливает данные для элемента index для роли role на значение value.

Для стратегии редактирования OnFieldChange индекс может получить изменение только если ни один другой индекс не имеет кэшированного изменения. Изменения отправляются немедленно. Однако, строки, которые ещё не были вставлены в базу данных, могут быть изменены свободно и не отправляются автоматически. Отправленные изменения не отменяются при ошибке.

Для OnRowChange индекс может получить изменение только если ни одна другая строка не имеет кэшированного изменения. Изменения не отправляются автоматически.

Возвращает true если value равно текущему значению. Однако значение не будет отправлено в базу данных.

Возвращает true если значение может быть установлено, или false при ошибке, например, если index выходит за границы.

Возвращает false если роль не Qt::EditRole. Для установки данных для ролей, отличных от EditRole, используйте либо пользовательскую прокси-модель, либо подкласс QSqlTableModel.

См. также editStrategy(), data(), submit(), submitAll(), и revertRow().

[virtual] void QSqlTableModel::setEditStrategy(QSqlTableModel::EditStrategy strategy)

Устанавливает стратегию редактирования значений в базе данных на strategy.

Это отменит все ожидающие изменения.

См. также editStrategy() и revertAll().

[virtual] void QSqlTableModel::setFilter(const QString &filter)

Устанавливает текущий фильтр на filter.

Фильтр — это SQL WHERE-оператор без ключевого слова WHERE (например, name='Josephine')).

Если модель уже заполнена данными из базы данных, модель перевыбирает их с новым фильтром. В противном случае фильтр будет применён в следующий раз, когда будет вызван select().

См. также filter(), select(), selectStatement(), и orderByClause().

[protected] void QSqlTableModel::setPrimaryKey(const QSqlIndex &key)

Защищённый метод, который позволяет подклассам устанавливать первичный ключ на key.

Обычно первичный индекс устанавливается автоматически всякий раз, когда вызывается setTable().

См. также primaryKey() и QSqlDatabase::primaryIndex().

[protected] void QSqlTableModel::setQuery(const QSqlQuery &query)

Эта функция просто вызывает QSqlQueryModel::setQuery(query). Обычно её не нужно вызывать для QSqlTableModel. Вместо этого используйте setTable(), setSort(), setFilter() и т. д., для настройки запроса.

См. также selectStatement().

bool QSqlTableModel::setRecord(int row, const QSqlRecord &values)

Применяет values к row в модели. Источник и целевые поля сопоставляются по имени поля, а не по положению в записи.

Обратите внимание, что сгенерированные флаги в values сохраняются для определения того, используются ли соответствующие поля при отправке изменений в базу данных. По умолчанию он установлен на true для всех полей в QSqlRecord. Вы должны установить флаг на false с помощью setGenerated(false) для любого значения в values, чтобы сохранить изменения обратно в базу данных.

Для стратегий редактирования OnFieldChange и OnRowChange строка может получить изменение только если ни одна другая строка не имеет кэшированного изменения. Изменения отправляются немедленно. Отправленные изменения не отменяются при ошибке.

Возвращает true если все значения были установлены; в противном случае возвращает false.

См. также record() и editStrategy().

[virtual] void QSqlTableModel::setSort(int column, Qt::SortOrder order)

Устанавливает порядок сортировки для column на order. Это не влияет на текущие данные, чтобы обновить данные с новым порядком сортировки, вызовите select().

См. также sort(), select(), и orderByClause().

[virtual] void QSqlTableModel::setTable(const QString &tableName)

Устанавливает таблицу базы данных, над которой работает модель, на tableName. Данные из таблицы не выбираются, но извлекается информация о её полях.

Для заполнения модели данными таблицы вызовите select().

Информация об ошибке может быть получена с помощью lastError().

См. также select(), setFilter(), и lastError().

[override virtual] void QSqlTableModel::sort(int column, Qt::SortOrder order)

Переопределяет: QAbstractItemModel::sort(int column, Qt::SortOrder order).

Сортирует данные по column с порядком сортировки order. Это немедленно выберет данные, используйте setSort() для установки порядка сортировки без заполнения модели данными.

См. также setSort(), select(), и orderByClause().

QString QSqlTableModel::tableName() const

Возвращает имя текущей выбранной таблицы.

[virtual protected] bool QSqlTableModel::updateRowInTable(int row, const QSqlRecord &values)

Обновляет указанную строку row в текущей активной таблице базы данных заданными значениями values. Возвращает true в случае успеха; в противном случае возвращает false.

Это метод низкого уровня, который работает непосредственно с базой данных и не должен вызываться напрямую. Используйте setData() для обновления значений. Модель определит, когда нужно изменить базу данных, в зависимости от своей стратегии редактирования.

Обратите внимание, что обновляются только значения, для которых установлен флаг generated. Флаг generated можно установить с помощью QSqlRecord::setGenerated() и проверить с помощью QSqlRecord::isGenerated().

См. также QSqlRecord::isGenerated() и setData().