Класс QSqlTableModel

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

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

Типы публичного доступа

Функции публичного доступа

Реализованные функции публичного доступа

Слот публичного доступа

Сигналы

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

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

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

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

    QSqlTableModel *model = new QSqlTableModel(parentObject, database);
    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.

Обратите внимание, что будут обновлены только значения, помеченные как сгенерированные. Флаг сгенерированного значения можно установить с помощью 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().