Класс QSqlTableModel

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

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

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

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

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

• 16 открытых функций, унаследованных от QSqlQueryModel
• 4 открытых функции, унаследованных от QAbstractTableModel
• 39 открытых функций, унаследованных от QAbstractItemModel
• 31 открытых функций, унаследованных от QObject

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

• 2 открытых слота, унаследованных от QAbstractItemModel
• 1 открытый слот, унаследованный от QObject

Сигналы

• 18 сигналов, унаследованных от QAbstractItemModel
• 2 сигнала, унаследованных от QObject

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

Реализованные защищённые функции

• 3 защищённых функции, унаследованные от QSqlQueryModel
• 19 защищённых функций, унаследованных от QAbstractItemModel
• 9 защищённых функций, унаследованных от QObject

Дополнительные унаследованные члены

• 1 свойство, унаследованное от QObject
• 11 статических публичных членов, унаследованных от QObject
• 1 защищённый слот, унаследованный от QAbstractItemModel

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

Класс 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 = Q_NULLPTR, QSqlDatabase db = QSqlDatabase())

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

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

[virtual] QSqlTableModel::~QSqlTableModel()

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

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

[virtual] void QSqlTableModel::clear()

Переопределено из QSqlQueryModel::clear().

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

Переопределено из QAbstractItemModel::data().

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

QSqlDatabase QSqlTableModel::database() const

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

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

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

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

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

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

EditStrategy QSqlTableModel::editStrategy() const

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

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

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

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

QString QSqlTableModel::filter() const

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

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

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

Переопределено из QAbstractItemModel::flags().

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

Переопределено из QAbstractItemModel::headerData().

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

Переопределено из QSqlQueryModel::indexInQuery().

Возвращает индекс значения в наборе результатов базы данных для заданного элемента 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().

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

Переопределено из QAbstractItemModel::insertRows().

Вставляет 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().

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

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

QSqlRecord QSqlTableModel::record() const

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

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

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

QSqlRecord QSqlTableModel::record(int row) const

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

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

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

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

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

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

Переопределено из QAbstractItemModel::removeColumns().

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

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

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

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

Переопределено из QAbstractItemModel::removeRows().

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

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

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

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

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

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

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

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

[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] void QSqlTableModel::revertRow(int row)

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

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

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

Реализация QAbstractItemModel::rowCount().

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

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

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

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

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

Переопределённо из QAbstractItemModel::setData().

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

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

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

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

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

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

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

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

Это приведет к отмене всех ожидающих изменений.

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

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

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

Фильтр — это SQL-условие без ключевого слова 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 сохраняются и определяют, используются ли соответствующие поля при отправке изменений в базу данных. Вызывающий должен помнить, что установить сгенерированный флаг в FALSE для полей, где база данных предназначена для обеспечения значения, например, автоматически инкрементируемого идентификатора.

Для стратегий редактирования 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().

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

Переопределённо из QAbstractItemModel::sort().

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

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

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

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().