Класс QTreeWidget

Класс QTreeWidget предоставляет виджет дерева, использующий предопределённую модель дерева. Подробнее...

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

Свойства

• columnCount : int
• topLevelItemCount : const int

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

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

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

Сигналы

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

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

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

Класс QTreeWidget — это вспомогательный класс, который предоставляет стандартное дерево виджетов с классическим интерфейсом на основе элементов, похожим на интерфейс, используемый классом QListView в Qt 3. Этот класс основан на архитектуре Qt Model/View и использует модель по умолчанию для хранения элементов, каждый из которых является QTreeWidgetItem.

Разработчики, которым не нужна гибкость фреймворка Model/View, могут использовать этот класс для очень лёгкого создания простых иерархических списков. Более гибкий подход заключается в объединении QTreeView со стандартной моделью элементов. Это позволяет отделить хранение данных от его представления.

В самом простом виде виджет дерева можно создать следующим образом:

QTreeWidget *treeWidget = new QTreeWidget();
treeWidget->setColumnCount(1);
QList<QTreeWidgetItem *> items;
for (int i = 0; i < 10; ++i)
    items.append(new QTreeWidgetItem(static_cast<QTreeWidget *>(nullptr), QStringList(QString("item: %1").arg(i))));
treeWidget->insertTopLevelItems(0, items);

Перед добавлением элементов в виджет дерева необходимо установить количество столбцов с помощью setColumnCount(). Это позволяет каждому элементу иметь одну или несколько меток или других декораций. Количество используемых столбцов можно найти с помощью функции columnCount().

Дерево может иметь заголовок, содержащий раздел для каждого столбца в виджете. Наиболее простой способ установить метки для каждого раздела — предоставить список строк с помощью setHeaderLabels(), но пользовательский заголовок можно создать с помощью QTreeWidgetItem и вставить его в дерево с помощью функции setHeaderItem().

Элементы в дереве можно сортировать по столбцу в соответствии с предварительно определённым порядком сортировки. Если сортировка включена, пользователь может отсортировать элементы, нажав на заголовок столбца. Сортировку можно включить или выключить, вызвав setSortingEnabled(). Функция isSortingEnabled() указывает, включена ли сортировка.

См. также QTreeWidgetItem, QTreeWidgetItemIterator, QTreeView, Программирование с помощью Model/View и Пример редактора настроек.

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

QTreeWidget::QTreeWidget(QWidget *parent = nullptr)

Конструирует виджет дерева с заданным parent.

[slot] void QTreeWidget::clear()

Очищает виджет дерева, удаляя все его элементы и выделения.

Примечание: Поскольку каждый элемент удаляется из виджета дерева перед удалением, возвращаемое значение QTreeWidgetItem::treeWidget() будет недопустимым при вызове из деструктора элемента.

См. также takeTopLevelItem(), topLevelItemCount(), и columnCount().

[slot] void QTreeWidget::collapseItem(const QTreeWidgetItem *item)

Закрывает элемент item. Это приводит к закрытию дерева, содержащего дочерние элементы элемента.

См. также expandItem(), currentItem(), itemAt() и topLevelItem().

[signal] void QTreeWidget::currentItemChanged(QTreeWidgetItem *current, QTreeWidgetItem *previous)

Этот сигнал излучается, когда текущий элемент изменяется. Текущий элемент указан параметром current, заменяя предыдущий текущий элемент previous.

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

[slot] void QTreeWidget::expandItem(const QTreeWidgetItem *item)

Развертывает элемент item. Это приводит к развёртыванию дерева, содержащего дочерние элементы элемента.

См. также collapseItem(), currentItem(), itemAt(), topLevelItem() и itemExpanded().

[signal] void QTreeWidget::itemActivated(QTreeWidgetItem *item, int column)

Этот сигнал излучается, когда пользователь активирует элемент, щелкнув по нему один раз или два раза (в зависимости от платформы, то есть от стилистического подсказки QStyle::SH_ItemView_ActivateItemOnSingleClick) или нажав специальную клавишу (например, Enter).

Указанный элемент item — это элемент, по которому был произведен щелчок, или nullptr если ни по какому элементу не был произведен щелчок. Столбец column — это столбец элемента, по которому был произведен щелчок, или -1, если по какому-либо элементу не был произведен щелчок.

[signal] void QTreeWidget::itemChanged(QTreeWidgetItem *item, int column)

Этот сигнал излучается, когда содержимое столбца column в указанном элементе item изменяется.

[signal] void QTreeWidget::itemClicked(QTreeWidgetItem *item, int column)

Этот сигнал излучается, когда пользователь щелкает внутри виджета.

Указанный элемент item — это элемент, по которому был произведен щелчок. Столбец column — это столбец элемента, по которому был произведен щелчок. Если ни по какому элементу не был произведен щелчок, сигнал не будет излучен.

[signal] void QTreeWidget::itemCollapsed(QTreeWidgetItem *item)

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

Примечание: Этот сигнал не будет излучен, если элемент изменит свое состояние при вызове collapseAll().

См. также QTreeWidgetItem::isExpanded(), itemExpanded() и collapseItem().

[signal] void QTreeWidget::itemDoubleClicked(QTreeWidgetItem *item, int column)

Этот сигнал излучается, когда пользователь дважды щелкает внутри виджета.

Указанный элемент item — это элемент, по которому был произведен двойной щелчок, или nullptr если ни по какому элементу не был произведен двойной щелчок. Столбец column — это столбец элемента, по которому был произведен двойной щелчок. Если ни по какому элементу не был произведен двойной щелчок, сигнал не будет излучен.

[signal] void QTreeWidget::itemEntered(QTreeWidgetItem *item, int column)

Этот сигнал излучается, когда курсор мыши входит в элемент item над указанным столбцом column. Для работы этой функции необходимо включить отслеживание мыши в QTreeWidget.

[signal] void QTreeWidget::itemExpanded(QTreeWidgetItem *item)

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

Примечание: Этот сигнал не будет излучен, если элемент изменяет свое состояние при вызове expandAll().

См. также QTreeWidgetItem::isExpanded(), itemCollapsed() и expandItem().

[signal] void QTreeWidget::itemPressed(QTreeWidgetItem *item, int column)

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

Указанный элемент item — это элемент, по которому был нажат щелчок, или nullptr если ни по какому элементу не был нажат щелчок. Столбец column — это столбец элемента, по которому был нажат щелчок, или -1, если ни по какому элементу не был нажат щелчок.

[signal] void QTreeWidget::itemSelectionChanged()

Этот сигнал излучается, когда происходит изменение выделения в виджете дерева. Текущее выделение можно найти с помощью selectedItems().

[slot] void QTreeWidget::scrollToItem(const QTreeWidgetItem *item, QAbstractItemView::ScrollHint hint = EnsureVisible)

Обеспечивает видимость элемента item, прокручивая представление при необходимости, используя указанный подсказку hint.

См. также currentItem(), itemAt() и topLevelItem().

[virtual] QTreeWidget::~QTreeWidget()

Уничтожает виджет дерева и все его элементы.

void QTreeWidget::addTopLevelItem(QTreeWidgetItem *item)

Добавляет элемент item в качестве верхнего уровня в виджете.

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

void QTreeWidget::addTopLevelItems(const QList<QTreeWidgetItem *> &items)

Добавляет список элементов items в качестве элементов верхнего уровня в виджете.

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

void QTreeWidget::closePersistentEditor(QTreeWidgetItem *item, int column = 0)

Закрывает постоянный редактор для элемента item в заданном столбце column.

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

См. также openPersistentEditor() и isPersistentEditorOpen().

int QTreeWidget::currentColumn() const

Возвращает текущий столбец в виджете дерева.

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

QTreeWidgetItem *QTreeWidget::currentItem() const

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

См. также setCurrentItem() и currentItemChanged().

[override virtual protected] void QTreeWidget::dropEvent(QDropEvent *event)

Реализует: QAbstractItemView::dropEvent(QDropEvent *event).

[virtual protected] bool QTreeWidget::dropMimeData(QTreeWidgetItem *parent, int index, const QMimeData *data, Qt::DropAction action)

Обрабатывает data, предоставленный операцией перетаскивания и опускания, которая завершилась заданным action в index в заданном элементе parent.

Стандартная реализация возвращает true если опускание было успешно обработано путем декодирования данных mime и вставки их в модель; в противном случае она возвращает false.

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

void QTreeWidget::editItem(QTreeWidgetItem *item, int column = 0)

Начинает редактирование элемента item в заданном столбце column, если он редактируемый.

[override virtual protected] bool QTreeWidget::event(QEvent *e)

Реализует: QAbstractItemView::event(QEvent *event).

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

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

QTreeWidgetItem *QTreeWidget::headerItem() const

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

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

QModelIndex QTreeWidget::indexFromItem(const QTreeWidgetItem *item, int column = 0) const

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

Примечание: В версиях Qt до 5.7 эта функция принимала не-const item.

См. также itemFromIndex() и topLevelItem().

int QTreeWidget::indexOfTopLevelItem(QTreeWidgetItem *item) const

Возвращает индекс заданного верхнеуровневого item, или -1, если элемент не найден.

См. также sortItems() и topLevelItemCount().

void QTreeWidget::insertTopLevelItem(int index, QTreeWidgetItem *item)

Вставляет item в верхнем уровне представления по индексу index.

Если элемент уже вставлен где-то еще, он не будет вставлен.

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

void QTreeWidget::insertTopLevelItems(int index, const QList<QTreeWidgetItem *> &items)

Вставляет список items в верхнем уровне представления по индексу index.

Элементы, которые уже вставлены где-то еще, не будут вставлены.

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

QTreeWidgetItem *QTreeWidget::invisibleRootItem() const

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

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

[since 5.10] bool QTreeWidget::isPersistentEditorOpen(QTreeWidgetItem *item, int column = 0) const

Возвращает, открыт ли постоянный редактор для элемента item в столбце column.

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

См. также openPersistentEditor() и closePersistentEditor().

QTreeWidgetItem *QTreeWidget::itemAbove(const QTreeWidgetItem *item) const

Возвращает элемент, расположенный над заданным item.

QTreeWidgetItem *QTreeWidget::itemAt(const QPoint &p) const

Возвращает указатель на элемент в координатах p. Координаты относительны к области просмотра виджета дерева viewport().

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

QTreeWidgetItem *QTreeWidget::itemAt(int x, int y) const

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

Возвращает указатель на элемент в координатах (x, y). Координаты относительны к области просмотра виджета дерева viewport().

QTreeWidgetItem *QTreeWidget::itemBelow(const QTreeWidgetItem *item) const

Возвращает элемент, расположенный визуально ниже заданного item.

QTreeWidgetItem *QTreeWidget::itemFromIndex(const QModelIndex &index) const

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

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

QWidget *QTreeWidget::itemWidget(QTreeWidgetItem *item, int column) const

Возвращает виджет, отображаемый в ячейке, заданной item и заданным column.

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

[virtual protected] QMimeData *QTreeWidget::mimeData(const QList<QTreeWidgetItem *> &items) const

Возвращает объект, содержащий сериализованное описание указанных items. Формат описания элементов получен из функции mimeTypes().

Если список элементов пуст, nullptr возвращается вместо сериализованного пустого списка.

[virtual protected] QStringList QTreeWidget::mimeTypes() const

Возвращает список MIME-типов, которые могут использоваться для описания списка элементов treewidget.

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

void QTreeWidget::openPersistentEditor(QTreeWidgetItem *item, int column = 0)

Открывает постоянный редактор для item в заданном column.

См. также closePersistentEditor() и isPersistentEditorOpen().

void QTreeWidget::removeItemWidget(QTreeWidgetItem *item, int column)

Удаляет виджет, установленный в заданном item в заданном column.

QList<QTreeWidgetItem *> QTreeWidget::selectedItems() const

Возвращает список всех выбранных элементов, не скрытых.

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

void QTreeWidget::setCurrentItem(QTreeWidgetItem *item)

Устанавливает текущий item в виджете дерева.

Если режим выбора не NoSelection, элемент также выбирается.

См. также currentItem() и currentItemChanged().

void QTreeWidget::setCurrentItem(QTreeWidgetItem *item, int column)

Устанавливает текущий item в виджете дерева и текущий столбец в column.

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

void QTreeWidget::setCurrentItem(QTreeWidgetItem *item, int column, QItemSelectionModel::SelectionFlags command)

Устанавливает текущий item в виджете дерева и текущий столбец в column, используя заданное command.

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

void QTreeWidget::setHeaderItem(QTreeWidgetItem *item)

Устанавливает заголовок item для виджета дерева. Метка каждого столбца в заголовке задаётся соответствующей меткой в элементе.

Виджет дерева принимает владение элементом.

См. также headerItem() и setHeaderLabels().

void QTreeWidget::setHeaderLabel(const QString &label)

То же, что и setHeaderLabels(QStringList(label)).

void QTreeWidget::setHeaderLabels(const QStringList &labels)

Добавляет столбец в заголовке для каждого элемента в списке labels и устанавливает метку для каждого столбца.

Обратите внимание, что setHeaderLabels() не удаляет существующие столбцы.

См. также setHeaderItem() и setHeaderLabel().

void QTreeWidget::setItemWidget(QTreeWidgetItem *item, int column, QWidget *widget)

Устанавливает заданный widget для отображения в ячейке, заданной заданным item и column.

Указанное свойство виджета autoFillBackground должно быть установлено в значение true, в противном случае фон виджета будет прозрачным, что позволит отобразить данные модели и элемент виджета дерева.

Эту функцию следует использовать только для отображения статического содержимого вместо элемента дерева виджета. Если требуется отображать пользовательское динамическое содержимое или реализовывать пользовательский виджет редактора, используйте QTreeView и подкласс QStyledItemDelegate вместо этого.

Данную функцию нельзя вызвать до того, как иерархия элементов будет настроена, то есть QTreeWidgetItem, который будет содержать widget, должен быть добавлен в представление до установки widget.

Примечание: Дерево принимает во владение виджет.

См. также itemWidget() и Классы делегатов.

[override virtual] void QTreeWidget::setSelectionModel(QItemSelectionModel *selectionModel)

Переопределяет: QTreeView::setSelectionModel(QItemSelectionModel *selectionModel).

int QTreeWidget::sortColumn() const

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

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

void QTreeWidget::sortItems(int column, Qt::SortOrder order)

Сортирует элементы в виджете в указанном order по значениям в заданной column.

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

[virtual protected] Qt::DropActions QTreeWidget::supportedDropActions() const

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

См. также Qt::DropActions.

QTreeWidgetItem *QTreeWidget::takeTopLevelItem(int index)

Удаляет верхнеуровневый элемент по заданному index в дереве и возвращает его, в противном случае возвращает nullptr;

См. также insertTopLevelItem(), topLevelItem() и topLevelItemCount().

QTreeWidgetItem *QTreeWidget::topLevelItem(int index) const

Возвращает верхнеуровневый элемент по заданному index или nullptr если элемент не существует.

См. также topLevelItemCount() и insertTopLevelItem().

QRect QTreeWidget::visualItemRect(const QTreeWidgetItem *item) const

Возвращает прямоугольник на области просмотра, занимаемый элементом в item.

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