Класс 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, const 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.

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

[virtual slot, since 5.0] 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] bool QSqlTableModel::clearItemData(const QModelIndex &index)

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

[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.

[since 5.0] 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, since 5.1] QSqlRecord QSqlTableModel::primaryValues(int row) const

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

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

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

QSqlRecord QSqlTableModel::record() const

Это перегруженная функция.

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

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

[since 5.0] 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, если все строки были удалены; в противном случае возвращает 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().