Класс 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().