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

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

См. также setItemExpanded(), 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 как элемент верхнего уровня в виджете.

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

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

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

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

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

[protected] 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 на верхнем уровне в представлении.

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

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

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

QTreeWidgetItem *QTreeWidget::invisibleRootItem() const

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

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

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

bool QTreeWidget::isPersistentEditorOpen(QTreeWidgetItem *item, int column = 0) const

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

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

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

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

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

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

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.

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

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

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

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

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

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

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

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

QMimeData *QTreeWidget::mimeData(const QList<QTreeWidgetItem *> items) const

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

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

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.

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

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

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

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

void QTreeWidget::setCurrentItem(QTreeWidgetItem *item)

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

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

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

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

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

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

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

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

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

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

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

void QTreeWidget::setHeaderItem(QTreeWidgetItem *item)

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

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

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

void QTreeWidget::setHeaderLabel(const QString &label)

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

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

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.

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

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

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

void QTreeWidget::setSelectionModel(QItemSelectionModel *selectionModel)

Реализует: QTreeView::setSelectionModel(QItemSelectionModel *selectionModel).

int QTreeWidget::sortColumn() const

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

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

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