Класс QTreeWidget

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

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

Свойства

• columnCount : int
• topLevelItemCount : const int

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

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

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

Сигналы

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

Переопределённые защищённые функции

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

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

Разработчики, которым не нужна гибкость архитектуры модели/представления, могут использовать этот класс для создания простых иерархических списков очень легко. Более гибкий подход включает в себя сочетание 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, Программирование модели/представления и Пример редактора настроек.

Документация по методам

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

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

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

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

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

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

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