Класс 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, и он заменяет предыдущий текущий элемент.

См. также 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) или нажав специальную клавишу (например, Ввод).

Указанный 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 свёрнут, так что ни один из его дочерних элементов не отображается.

См. также 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 развернут, так что все его дочерние элементы отображаются.

См. также 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.

См. также 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, которые могут использоваться для описания списка элементов виджета дерева.

См. также 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 указанного виджета widget должно быть установлено в значение 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().