Класс QStandardItemModel

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

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

Свойства

• sortRole : int

Общедоступные функции

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

Сигналы

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

QStandardItemModel может использоваться в качестве хранилища стандартных типов данных Qt. Это один из Классов модели/представления и является частью фреймворка Qt модель/представление.

QStandardItemModel обеспечивает классический подход на основе элементов для работы с моделью. Элементы в QStandardItemModel предоставляются QStandardItem.

QStandardItemModel реализует интерфейс QAbstractItemModel, что означает, что модель может использоваться для предоставления данных в любом представлении, которое поддерживает этот интерфейс (например, QListView, QTableView и QTreeView, и ваших собственных пользовательских представлений). Для повышения производительности и гибкости вы можете подклассировать QAbstractItemModel, чтобы обеспечить поддержку разных типов хранилищ данных. Например, QDirModel предоставляет интерфейс модели к подлежащей файловой системе.

Если вам нужен список или дерево, обычно создаётся пустой QStandardItemModel и используются appendRow() для добавления элементов в модель и item() для доступа к элементу. Если ваша модель представляет таблицу, вы обычно передаёте размеры таблицы в конструктор QStandardItemModel и используете setItem() для размещения элементов в таблице. Вы также можете использовать setRowCount() и setColumnCount() для изменения размеров модели. Для вставки элементов используйте insertRow() или insertColumn(), а для удаления элементов используйте removeRow() или removeColumn().

Вы можете установить метки заголовков вашей модели с помощью setHorizontalHeaderLabels() и setVerticalHeaderLabels().

Вы можете искать элементы в модели с помощью findItems() и сортировать модель, вызвав sort().

Вызовите clear() для удаления всех элементов из модели.

Пример использования QStandardItemModel для создания таблицы:

QStandardItemModel model(4, 4);
for (int row = 0; row < model.rowCount(); ++row) {
    for (int column = 0; column < model.columnCount(); ++column) {
        QStandardItem *item = new QStandardItem(QString("row %0, column %1").arg(row).arg(column));
        model.setItem(row, column, item);
    }
}

Пример использования QStandardItemModel для создания дерева:

QStandardItemModel model;
QStandardItem *parentItem = model.invisibleRootItem();
for (int i = 0; i < 4; ++i) {
    QStandardItem *item = new QStandardItem(QString("item %0").arg(i));
    parentItem->appendRow(item);
    parentItem = item;
}

После установки модели на представлении, вы обычно хотите реагировать на действия пользователя, такие как щелчок по элементу. Поскольку QAbstractItemView предоставляет сигналы и функции на основе QModelIndex, вам нужен способ получения QStandardItem, соответствующего заданному QModelIndex, и наоборот. itemFromIndex() и indexFromItem() обеспечивают это отображение. Типичное использование itemFromIndex() включает получение элемента в текущем индексе в представлении и получение элемента, соответствующего индексу, переданному сигналом QAbstractItemView, например, QAbstractItemView::clicked(). Сначала подключите сигнал представления к слоту в вашем классе:

QTreeView *treeView = new QTreeView(this);
treeView->setModel(myStandardItemModel);
connect(treeView, &QTreeView::clicked,
        this, &MyWidget::clicked);

При получении сигнала вы вызываете itemFromIndex() на заданном индексе модели, чтобы получить указатель на элемент:

void MyWidget::clicked(const QModelIndex &index)
{
    QStandardItem *item = myStandardItemModel->itemFromIndex(index);
    // Do stuff with the item ...
}

Обратно, вы должны получить QModelIndex элемента, когда хотите вызвать функцию модели/представления, которая принимает индекс в качестве аргумента. Вы можете получить индекс, используя функцию модели indexFromItem(), или, что эквивалентно, вызвав QStandardItem::index():

treeView->scrollTo(item->index());

Конечно, вы не обязаны использовать подход на основе элементов; вы можете вместо этого полностью полагаться на интерфейс QAbstractItemModel при работе с моделью или использовать сочетание обоих методов, как это необходимо.

См. также QStandardItem, Моделирование/Представление, QAbstractItemModel, Пример простой модели дерева и Классы удобства просмотра элементов.

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

QStandardItemModel::QStandardItemModel(int rows, int columns, QObject *parent = nullptr)

Создаёт новую модель элементов, которая изначально содержит rows строк и columns столбцов и имеет указанный parent.

QStandardItemModel::QStandardItemModel(QObject *parent = nullptr)

Создаёт новую модель элементов с заданным parent.

[signal] void QStandardItemModel::itemChanged(QStandardItem *item)

Этот сигнал излучается всякий раз, когда данные item изменились.

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

[virtual] QStandardItemModel::~QStandardItemModel()

Уничтожает модель. Модель уничтожает все свои элементы.

void QStandardItemModel::appendColumn(const QList<QStandardItem *> &items)

Добавляет столбец, содержащий items. При необходимости количество строк увеличивается до размера items.

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

См. также insertColumn() и appendRow().

void QStandardItemModel::appendRow(const QList<QStandardItem *> &items)

Добавляет строку, содержащую items. При необходимости количество столбцов увеличивается до размера items.

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

См. также insertRow() и appendColumn().

void QStandardItemModel::appendRow(QStandardItem *item)

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

При построении списка или дерева, имеющего только один столбец, эта функция обеспечивает удобный способ добавления одного нового item.

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

void QStandardItemModel::clear()

Удаляет все элементы (включая заголовки) из модели и устанавливает количество строк и столбцов в ноль.

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

bool QStandardItemModel::clearItemData(const QModelIndex &index)

Удаляет данные, хранящиеся во всех ролях для данного index. Возвращает true если index допустима и данные были очищены, false в противном случае.

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

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

[override virtual] int QStandardItemModel::columnCount(const QModelIndex &parent = QModelIndex()) const

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

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

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

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

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

[override virtual] bool QStandardItemModel::dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent)

Переопределяет: QAbstractItemModel::dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent).

QList<QStandardItem *> QStandardItemModel::findItems(const QString &text, Qt::MatchFlags flags = Qt::MatchExactly, int column = 0) const

Возвращает список элементов, которые соответствуют заданному text, используя заданные flags, в заданном column.

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

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

Переопределяет: QAbstractItemModel::flags(const QModelIndex &index) const.

[override virtual] bool QStandardItemModel::hasChildren(const QModelIndex &parent = QModelIndex()) const

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

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

Переопределяет: QAbstractItemModel::headerData(int section, Qt::Orientation orientation, int role) const.

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

QStandardItem *QStandardItemModel::horizontalHeaderItem(int column) const

Возвращает элемент горизонтального заголовка для column, если он был задан; в противном случае возвращает nullptr.

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

См. также setHorizontalHeaderItem() и verticalHeaderItem().

[override virtual] QModelIndex QStandardItemModel::index(int row, int column, const QModelIndex &parent = QModelIndex()) const

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

QModelIndex QStandardItemModel::indexFromItem(const QStandardItem *item) const

Возвращает QModelIndex, связанный с данным item.

Используйте эту функцию, когда хотите выполнить операцию, которая требует QModelIndex элемента, например, QAbstractItemView::scrollTo(). QStandardItem::index() предоставляется для удобства; она эквивалентна вызову этой функции.

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

См. также itemFromIndex() и QStandardItem::index().

void QStandardItemModel::insertColumn(int column, const QList<QStandardItem *> &items)

Вставляет столбец в column, содержащий items. При необходимости количество строк увеличивается до размера items.

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

См. также takeColumn(), appendColumn(), и insertRow().

bool QStandardItemModel::insertColumn(int column, const QModelIndex &parent = QModelIndex())

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

См. также insertColumns(), insertRow(), и removeColumn().

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

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

void QStandardItemModel::insertRow(int row, const QList<QStandardItem *> &items)

Вставляет строку в позиции row, содержащую элементы items. При необходимости, количество столбцов увеличивается до размера items.

Данная функция была введена в Qt 4.2.

См. также takeRow(), appendRow() и insertColumn().

void QStandardItemModel::insertRow(int row, QStandardItem *item)

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

Вставляет строку в позиции row, содержащую элемент item.

При создании списка или дерева с одним столбцом, эта функция предоставляет удобный способ добавления одного нового элемента.

Данная функция была введена в Qt 4.2.

bool QStandardItemModel::insertRow(int row, const QModelIndex &parent = QModelIndex())

Вставляет отдельную строку перед заданной строкой row в дочерние элементы родительского элемента parent. Возвращает true если строка была вставлена; в противном случае возвращает false.

См. также insertRows(), insertColumn() и removeRow().

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

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

QStandardItem *QStandardItemModel::invisibleRootItem() const

Возвращает скрытый корневой элемент модели.

Скрытый корневой элемент предоставляет доступ к элементам верхнего уровня модели через API QStandardItem, что позволяет создавать функции, которые могут обрабатывать элементы верхнего уровня и их потомков единообразно; например, рекурсивные функции, использующие модель дерева.

Примечание: Вызов index() для объекта QStandardItem, полученного из этой функции, некорректен.

Данная функция была введена в Qt 4.2.

QStandardItem *QStandardItemModel::item(int row, int column = 0) const

Возвращает элемент для заданного row и column, если он был задан; в противном случае возвращает nullptr.

Данная функция была введена в Qt 4.2.

См. также setItem(), takeItem() и itemFromIndex().

[override virtual] QMap<int, QVariant> QStandardItemModel::itemData(const QModelIndex &index) const

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

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

QStandardItem *QStandardItemModel::itemFromIndex(const QModelIndex &index) const

Возвращает указатель на QStandardItem, связанный с заданным index.

Вызов этой функции обычно является начальным шагом при обработке сигналов на основе QModelIndex от представления, таких как QAbstractItemView::activated(). В вашем слоте вы вызываете itemFromIndex() с QModelIndex, переданным сигналом, в качестве аргумента, чтобы получить указатель на соответствующий QStandardItem.

Обратите внимание, что эта функция лениво создаёт элемент для индекса (используя itemPrototype()) и устанавливает его в таблицу дочерних элементов родительского элемента, если там ещё нет элемента в этом индексе.

Если index является недействительным индексом, эта функция возвращает nullptr.

Данная функция была введена в Qt 4.2.

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

const QStandardItem *QStandardItemModel::itemPrototype() const

Возвращает прототип элемента, используемый моделью. Модель использует прототип элемента как фабрику элементов при необходимости создания новых элементов по требованию (например, когда представление или делегат элемента вызывают setData()).

Данная функция была введена в Qt 4.2.

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

[override virtual] QMimeData *QStandardItemModel::mimeData(const QModelIndexList &indexes) const

Реализует: QAbstractItemModel::mimeData(const QModelIndexList &indexes) const.

[override virtual] QStringList QStandardItemModel::mimeTypes() const

Реализует: QAbstractItemModel::mimeTypes() const.

[override virtual] QModelIndex QStandardItemModel::parent(const QModelIndex &child) const

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

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

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

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

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

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

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

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

void QStandardItemModel::setColumnCount(int columns)

Устанавливает количество столбцов в этой модели на columns. Если это значение меньше, чем columnCount(), данные в нежелательных столбцах удаляются.

Данная функция была введена в Qt 4.2.

См. также columnCount() и setRowCount().

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

Реализует: QAbstractItemModel::setData(const QModelIndex &index, const QVariant &value, int role).

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

[override virtual] bool QStandardItemModel::setHeaderData(int section, Qt::Orientation orientation, const QVariant &value, int role = Qt::EditRole)

Реализует: QAbstractItemModel::setHeaderData(int section, Qt::Orientation orientation, const QVariant &value, int role).

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

void QStandardItemModel::setHorizontalHeaderItem(int column, QStandardItem *item)

Устанавливает горизонтальный заголовок для столбца column в элемент item. Модель принимает владение элементом. Если необходимо, количество столбцов увеличивается для размещения элемента. Предыдущий заголовок (если он был) удаляется.

Данная функция была введена в Qt 4.2.

См. также horizontalHeaderItem(), setHorizontalHeaderLabels() и setVerticalHeaderItem().

void QStandardItemModel::setHorizontalHeaderLabels(const QStringList &labels)

Устанавливает метки горизонтальной заголовка используя labels. Если необходимо, количество столбцов увеличивается до размера labels.

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

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

void QStandardItemModel::setItem(int row, int column, QStandardItem *item)

Устанавливает элемент для заданной row и column в item. Модель принимает владение элементом. Если необходимо, количество строк и столбцов увеличивается для размещения элемента. Предыдущий элемент в заданном месте (если он был) удаляется.

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

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

void QStandardItemModel::setItem(int row, QStandardItem *item)

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

[override virtual] bool QStandardItemModel::setItemData(const QModelIndex &index, const QMap<int, QVariant> &roles)

Переопределяет: QAbstractItemModel::setItemData(const QModelIndex &index, const QMap<int, QVariant> &roles).

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

void QStandardItemModel::setItemPrototype(const QStandardItem *item)

Устанавливает прототип элемента для модели в указанный item. Модель принимает владение прототипом.

Прототип элемента действует как фабрика QStandardItem, используя функцию QStandardItem::clone(). Для создания своего собственного прототипа, подклассируйте QStandardItem, переопределите QStandardItem::clone() и установите прототип в экземпляр вашего пользовательского класса. Всякий раз, когда QStandardItemModel нуждается в создании элемента по запросу (например, когда виджет или делегат вызывают setData()), новые элементы будут экземплярами вашего пользовательского класса.

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

См. также itemPrototype() и QStandardItem::clone().

void QStandardItemModel::setItemRoleNames(const QHash<int, QByteArray> &roleNames)

Устанавливает имена ролей элементов в roleNames.

void QStandardItemModel::setRowCount(int rows)

Устанавливает количество строк в этой модели на rows. Если это меньше, чем rowCount(), данные в ненужных строках удаляются.

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

См. также rowCount() и setColumnCount().

void QStandardItemModel::setVerticalHeaderItem(int row, QStandardItem *item)

Устанавливает элемент вертикального заголовка для row в item. Модель принимает владение элементом. Если необходимо, количество строк увеличивается для размещения элемента. Предыдущий элемент заголовка (если он был) удаляется.

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

См. также verticalHeaderItem(), setVerticalHeaderLabels(), и setHorizontalHeaderItem().

void QStandardItemModel::setVerticalHeaderLabels(const QStringList &labels)

Устанавливает метки вертикального заголовка, используя labels. Если необходимо, количество строк увеличивается до размера labels.

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

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

[override virtual] QModelIndex QStandardItemModel::sibling(int row, int column, const QModelIndex &idx) const

Переопределяет: QAbstractItemModel::sibling(int row, int column, const QModelIndex &index) const.

[override virtual] void QStandardItemModel::sort(int column, Qt::SortOrder order = Qt::AscendingOrder)

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

[override virtual] Qt::DropActions QStandardItemModel::supportedDropActions() const

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

QStandardItemModel поддерживает копирование и перемещение.

QList<QStandardItem *> QStandardItemModel::takeColumn(int column)

Удаляет заданный column без удаления элементов столбца и возвращает список указателей на удаленные элементы. Модель высвобождает владение элементами. Для элементов в столбце, которые не были установлены, соответствующие указатели в списке будут nullptr.

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

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

QStandardItem *QStandardItemModel::takeHorizontalHeaderItem(int column)

Удаляет элемент горизонтального заголовка в column из заголовка без удаления его и возвращает указатель на элемент. Модель высвобождает владение элементом.

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

См. также horizontalHeaderItem() и takeVerticalHeaderItem().

QStandardItem *QStandardItemModel::takeItem(int row, int column = 0)

Удаляет элемент в (row, column) без его удаления. Модель высвобождает владение элементом.

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

См. также item(), takeRow(), и takeColumn().

QList<QStandardItem *> QStandardItemModel::takeRow(int row)

Удаляет заданную row без удаления элементов строки и возвращает список указателей на удаленные элементы. Модель высвобождает владение элементами. Для элементов в строке, которые не были установлены, соответствующие указатели в списке будут nullptr.

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

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

QStandardItem *QStandardItemModel::takeVerticalHeaderItem(int row)

Удаляет элемент вертикального заголовка в row из заголовка без удаления его и возвращает указатель на элемент. Модель высвобождает владение элементом.

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

См. также verticalHeaderItem() и takeHorizontalHeaderItem().

QStandardItem *QStandardItemModel::verticalHeaderItem(int row) const

Возвращает элемент вертикального заголовка для строки row, если он был установлен; в противном случае возвращает nullptr.

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

См. также setVerticalHeaderItem() и horizontalHeaderItem().