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

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

См. также 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, если все строки были удалены; в противном случае возвращает 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 равно текущему значению. Однако значение не будет отправлено в базу данных.

Возвращает 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().