Класс QHeaderView

Класс QHeaderView предоставляет строку заголовка или столбец заголовка для представлений элементов. Подробнее...

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

Общедоступные типы

Свойства

Общедоступные функции

Реализованные общедоступные функции

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

Сигналы

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

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

Защищенные слоты

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

Класс QHeaderView отображает заголовки, используемые в представлениях элементов, таких как QTableView и QTreeView. Он заменяет класс Qt3 QHeader, ранее использовавшийся с той же целью, но использует архитектуру модели/представления Qt для согласованности с классами представлений элементов.

Класс QHeaderView является одним из классов модели/представления и входит в состав фреймворка модели/представления Qt.

Заголовок получает данные для каждого раздела из модели с помощью функции QAbstractItemModel::headerData(). Вы можете установить данные, используя QAbstractItemModel::setHeaderData().

Каждый заголовок имеет ориентацию() и определенное количество разделов, указанное функцией count(). Раздел относится к части заголовка — либо строке, либо столбцу, в зависимости от ориентации.

Разделы можно перемещать и изменять размер с помощью moveSection() и resizeSection(); их также можно скрывать и показывать с помощью hideSection() и showSection().

Каждый раздел заголовка описывается идентификатором раздела, указанным section(), и может быть расположен в определенном visualIndex() в заголовке. Для раздела можно установить индикатор сортировки с помощью setSortIndicator(); это указывает, будут ли элементы в соответствующем представлении элементов отсортированы в заданном порядке раздела.

Для горизонтального заголовка раздел эквивалентен столбцу в модели, а для вертикального заголовка раздел эквивалентен строке в модели.

Перемещение разделов заголовка

Заголовок может быть закреплен на месте или сделан перемещаемым с помощью setSectionsMovable(). Он может быть сделан нажимаемым с помощью setSectionsClickable(), и имеет поведение изменения размера в соответствии с setSectionResizeMode().

Примечание: Двойной щелчок по заголовку для изменения размера раздела применим только для видимых строк.

Заголовок будет генерировать sectionMoved() при перемещении раздела пользователем, sectionResized() при изменении размера раздела пользователем, а также sectionClicked() и sectionHandleDoubleClicked() в ответ на щелчки мыши. Заголовок также будет генерировать sectionCountChanged().

Вы можете определить раздел, используя функции logicalIndex() и logicalIndexAt(), или по его позиционному индексу, используя функции visualIndex() и visualIndexAt(). Визуальный индекс изменится, если раздел будет перемещен, но логический индекс останется неизменным.

Внешний вид

QTableWidget и QTableView создают заголовки по умолчанию. Если вы хотите отобразить заголовки, вы можете использовать setVisible().

Не все ItemDataRole будут иметь влияние на QHeaderView. Если вам нужно нарисовать другие роли, вы можете унаследовать QHeaderView и переопределить paintEvent(). QHeaderView учитывает следующие роли данных элементов, если они не противоречат стилю (что может произойти для стилей, которые следуют за темой рабочего стола):

TextAlignmentRole, DisplayRole, FontRole, DecorationRole, ForegroundRole и BackgroundRole.

Примечание: Каждый заголовок отображает данные для каждого раздела самостоятельно и не полагается на делегат. В результате вызов функции setItemDelegate() заголовка не окажет никакого эффекта.

См. также Программирование модели/представления, QListView, QTableView и QTreeView.

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

enum QHeaderView::ResizeMode

Режим изменения размера определяет поведение секций заголовка. Его можно установить для всего представления заголовка или для отдельных секций, используя setSectionResizeMode().

Следующие значения устарели:

См. также setSectionResizeMode(), stretchLastSection и minimumSectionSize.

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

QHeaderView::QHeaderView(Qt::Orientation orientation, QWidget *parent = nullptr)

Создаёт новый универсальный заголовок с заданным orientation и parent.

[signal] void QHeaderView::geometriesChanged()

Этот сигнал излучается, когда изменяются геометрии заголовка.

[slot] void QHeaderView::headerDataChanged(Qt::Orientation orientation, int logicalFirst, int logicalLast)

Обновляет изменённые разделы заголовка с заданной orientation, от logicalFirst до logicalLast включительно.

[protected slot] void QHeaderView::resizeSections()

Изменяет размер разделов в соответствии с их подсказками размера. Обычно, вызывать эту функцию не нужно.

[signal] void QHeaderView::sectionClicked(int logicalIndex)

Этот сигнал излучается, когда раздел нажат. Логический индекс раздела указан в logicalIndex.

Обратите внимание, что сигнал sectionPressed также будет излучен.

См. также setSectionsClickable() и sectionPressed().

[signal] void QHeaderView::sectionCountChanged(int oldCount, int newCount)

Этот сигнал излучается, когда изменяется количество разделов, т.е. когда разделы добавляются или удаляются. Исходное количество указано в oldCount, а новое — в newCount.

См. также count(), length() и headerDataChanged().

[signal] void QHeaderView::sectionDoubleClicked(int logicalIndex)

Этот сигнал излучается, когда раздел дважды нажат. Логический индекс раздела указан в logicalIndex.

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

[signal] void QHeaderView::sectionEntered(int logicalIndex)

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

См. также setSectionsClickable() и sectionPressed().

[signal] void QHeaderView::sectionHandleDoubleClicked(int logicalIndex)

Этот сигнал излучается, когда раздел дважды нажат. Логический индекс раздела указан в logicalIndex.

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

[signal] void QHeaderView::sectionMoved(int logicalIndex, int oldVisualIndex, int newVisualIndex)

Этот сигнал излучается, когда раздел перемещён. Логический индекс раздела указан в logicalIndex, старый индекс — в oldVisualIndex, а новый индекс позиции — в newVisualIndex.

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

[signal] void QHeaderView::sectionPressed(int logicalIndex)

Этот сигнал излучается, когда раздел нажат. Логический индекс раздела указан в logicalIndex.

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

[signal] void QHeaderView::sectionResized(int logicalIndex, int oldSize, int newSize)

Этот сигнал излучается, когда раздел изменён по размеру. Логический номер раздела указан в logicalIndex, старый размер — в oldSize, а новый — в newSize.

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

[protected slot] void QHeaderView::sectionsAboutToBeRemoved(const QModelIndex &parent, int logicalFirst, int logicalLast)

Этот слот вызывается при удалении разделов из parent. logicalFirst и logicalLast обозначают, где разделы были удалены.

Если удалён только один раздел, logicalFirst и logicalLast будут одинаковыми.

[protected slot] void QHeaderView::sectionsInserted(const QModelIndex &parent, int logicalFirst, int logicalLast)

Этот слот вызывается при вставке разделов в parent. Индексы logicalFirst и logicalLast обозначают, куда были вставлены новые разделы.

Если вставлен только один раздел, logicalFirst и logicalLast будут одинаковыми.

[slot] void QHeaderView::setOffset(int offset)

Устанавливает смещение заголовка в offset.

См. также offset() и length().

[slot] void QHeaderView::setOffsetToLastSection()

Устанавливает смещение, чтобы последний раздел был виден.

См. также setOffset(), sectionPosition() и setOffsetToSectionPosition().

[slot] void QHeaderView::setOffsetToSectionPosition(int visualSectionNumber)

Устанавливает смещение до начала раздела в заданном visualSectionNumber. visualSectionNumber — это фактически видимый раздел, когда скрытые разделы не рассматриваются. Это не всегда то же самое, что visualIndex().

См. также setOffset() и sectionPosition().

[signal] void QHeaderView::sortIndicatorChanged(int logicalIndex, Qt::SortOrder order)

Этот сигнал излучается, когда изменяется раздел, содержащий индикатор сортировки, или порядок, указанный в нём. Логический индекс раздела указан в logicalIndex, а порядок сортировки — в order.

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

[virtual] QHeaderView::~QHeaderView()

Удаляет заголовок.

int QHeaderView::count() const

Возвращает количество разделов в заголовке.

См. также sectionCountChanged() и length().

[override virtual protected] void QHeaderView::currentChanged(const QModelIndex &current, const QModelIndex &old)

Переопределяет: QAbstractItemView::currentChanged(const QModelIndex &current, const QModelIndex &previous).

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

Переопределяет: QAbstractItemView::event(QEvent *event).

int QHeaderView::hiddenSectionCount() const

Возвращает количество скрытых разделов в заголовке.

См. также setSectionHidden() и isSectionHidden().

void QHeaderView::hideSection(int logicalIndex)

Скрывает раздел, указанный logicalIndex.

См. также showSection(), isSectionHidden(), hiddenSectionCount() и setSectionHidden().

[override virtual protected] int QHeaderView::horizontalOffset() const

Переопределяет: QAbstractItemView::horizontalOffset() const.

Возвращает горизонтальное смещение заголовка. Для вертикальных заголовков это 0.

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

[virtual protected] void QHeaderView::initStyleOption(QStyleOptionHeader *option) const

Инициализирует option значениями из этого QHeaderView. Этот метод полезен для подклассов, когда им нужен QStyleOptionHeader, но они не хотят сами заполнять всю информацию.

См. также QStyleOption::initFrom() и initStyleOptionForIndex().

[virtual protected, since 6.0] void QHeaderView::initStyleOptionForIndex(QStyleOptionHeader *option, int logicalIndex) const

Инициализирует стиль option из указанного logicalIndex. Эта функция вызывается по умолчанию в реализации paintSection после того, как была вызвана initStyleOption.

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

См. также paintSection() и initStyleOption().

bool QHeaderView::isSectionHidden(int logicalIndex) const

Возвращает true если секция, заданная logicalIndex, явно скрыта от пользователя; в противном случае возвращает false.

См. также hideSection(), showSection(), setSectionHidden() и hiddenSectionCount().

int QHeaderView::length() const

Возвращает длину по направлению заголовка.

См. также sizeHint(), setSectionResizeMode() и offset().

int QHeaderView::logicalIndex(int visualIndex) const

Возвращает logicalIndex для секции в заданной позиции visualIndex, или -1, если visualIndex < 0 или visualIndex >= QHeaderView::count().

Обратите внимание, что visualIndex не зависит от скрытых секций.

См. также visualIndex() и sectionPosition().

int QHeaderView::logicalIndexAt(int position) const

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

См. также visualIndexAt() и isSectionHidden().

int QHeaderView::logicalIndexAt(int x, int y) const

Возвращает логический индекс секции в заданных координатах. Если заголовок горизонтальный, используется x, в противном случае для поиска логического индекса используется y.

int QHeaderView::logicalIndexAt(const QPoint &pos) const

Возвращает логический индекс секции в заданной позиции pos. Если заголовок горизонтальный, используется координата x, в противном случае используется координата y для поиска логического индекса.

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

[override virtual protected] void QHeaderView::mouseDoubleClickEvent(QMouseEvent *e)

Переопределяет: QAbstractItemView::mouseDoubleClickEvent(QMouseEvent *event).

[override virtual protected] void QHeaderView::mouseMoveEvent(QMouseEvent *e)

Переопределяет: QAbstractItemView::mouseMoveEvent(QMouseEvent *event).

[override virtual protected] void QHeaderView::mousePressEvent(QMouseEvent *e)

Переопределяет: QAbstractItemView::mousePressEvent(QMouseEvent *event).

[override virtual protected] void QHeaderView::mouseReleaseEvent(QMouseEvent *e)

Переопределяет: QAbstractItemView::mouseReleaseEvent(QMouseEvent *event).

void QHeaderView::moveSection(int from, int to)

Перемещает секцию с визуальным индексом from в секцию с визуальным индексом to.

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

int QHeaderView::offset() const

Возвращает смещение заголовка: это самая левая (или верхняя для вертикальных заголовков) видимая пиксель заголовка.

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

Qt::Orientation QHeaderView::orientation() const

Возвращает направление заголовка.

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

[override virtual protected] void QHeaderView::paintEvent(QPaintEvent *e)

Переопределяет: QAbstractScrollArea::paintEvent(QPaintEvent *event).

[virtual protected] void QHeaderView::paintSection(QPainter *painter, const QRect &rect, int logicalIndex) const

Рисует секцию, указанную заданным logicalIndex, используя заданный painter и rect.

Обычно вам не нужно вызывать эту функцию.

[override virtual] void QHeaderView::reset()

Переопределяет: QAbstractItemView::reset().

[since 5.2] int QHeaderView::resizeContentsPrecision() const

Возвращает точность, с которой QHeaderView будет рассчитывать ResizeToContents.

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

См. также setResizeContentsPrecision() и setSectionResizeMode().

void QHeaderView::resizeSection(int logicalIndex, int size)

Изменяет размер секции, указанной logicalIndex, на size пикселей. Параметр size должен быть значением больше или равным нулю. Однако размер, равный нулю, не рекомендуется. В этой ситуации следует использовать hideSection.

См. также sectionResized(), sectionSize() и hideSection().

void QHeaderView::resizeSections(QHeaderView::ResizeMode mode)

Изменяет размер секций в соответствии с заданным mode, игнорируя текущий режим изменения размера.

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

bool QHeaderView::restoreState(const QByteArray &state)

Восстанавливает state этого виджета заголовка. Эта функция возвращает true если состояние было восстановлено; в противном случае возвращает false.

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

QByteArray QHeaderView::saveState() const

Сохраняет текущее состояние этого виджета заголовка.

Для восстановления сохранённого состояния передайте возвращаемое значение в restoreState().

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

int QHeaderView::sectionPosition(int logicalIndex) const

Возвращает позицию секции заданного logicalIndex, или -1, если секция скрыта. Позиция измеряется в пикселях от левого верхнего угла первой видимой позиции к левому верхнему углу позиции с logicalIndex. Измерение выполняется по оси x для горизонтальных заголовков и по оси y для вертикальных заголовков.

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

[since 5.0] QHeaderView::ResizeMode QHeaderView::sectionResizeMode(int logicalIndex) const

Возвращает режим изменения размера, применяемый к секции, заданной указанным logicalIndex.

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

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

int QHeaderView::sectionSize(int logicalIndex) const

Возвращает ширину (или высоту для вертикальных заголовков) заданного logicalIndex.

См. также length(), setSectionResizeMode() и defaultSectionSize().

[virtual protected] QSize QHeaderView::sectionSizeFromContents(int logicalIndex) const

Возвращает размер содержимого секции, заданной указанным logicalIndex.

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

int QHeaderView::sectionSizeHint(int logicalIndex) const

Возвращает подходящий размер подсказки для секции, указанной logicalIndex.

Qt::SizeHintRole

См. также sizeHint(), defaultSectionSize(), minimumSectionSize(), и maximumSectionSize().

int QHeaderView::sectionViewportPosition(int logicalIndex) const

Возвращает позицию области просмотра секции с заданным logicalIndex.

Если секция скрыта, значение возврата не определено.

См. также sectionPosition() и isSectionHidden().

[since 5.0] bool QHeaderView::sectionsClickable() const

Возвращает true значение, если заголовок нажимаем; в противном случае возвращает false. Нажимаемый заголовок может быть настроен так, чтобы позволять пользователю изменять представление данных в представлении, связанном с заголовком.

Данная функция была введена в Qt 5.0.

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

bool QHeaderView::sectionsHidden() const

Возвращает true значение, если секции в заголовке скрыты; в противном случае возвращает false.

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

[since 5.0] bool QHeaderView::sectionsMovable() const

Возвращает true значение, если заголовок может быть перемещен пользователем; в противном случае возвращает false.

По умолчанию секции перемещаемы в QTreeView (кроме первой), и не перемещаемы в QTableView.

Данная функция была введена в Qt 5.0.

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

bool QHeaderView::sectionsMoved() const

Возвращает true значение, если секции в заголовке были перемещены; в противном случае возвращает false.

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

[override virtual] void QHeaderView::setModel(QAbstractItemModel *model)

Реализует: QAbstractItemView::setModel(QAbstractItemModel *model).

[since 5.2] void QHeaderView::setResizeContentsPrecision(int precision)

Устанавливает точность расчёта размера QHeaderView при использовании ResizeToContents. Малое значение обеспечит менее точный, но быстрый автомасштаб, а большее значение обеспечит более точный масштаб, но он может быть медленным.

Число precision указывает, сколько секций необходимо учитывать при расчёте предпочтительного размера.

Значение по умолчанию равно 1000, что означает, что горизонтальная колонка с автоматическим масштабированием будет учитывать максимум 1000 строк при расчёте автомасштаба.

Специальное значение 0 означает, что будет рассматриваться только видимая область. Специальное значение -1 означает, что будут рассматриваться все элементы.

Это значение используется в QTableView::sizeHintForColumn(), QTableView::sizeHintForRow() и QTreeView::sizeHintForColumn(). Переопределение этих функций может привести к тому, что эта функция не будет иметь эффекта.

Данная функция была введена в Qt 5.2.

См. также resizeContentsPrecision(), setSectionResizeMode(), resizeSections(), QTableView::sizeHintForColumn(), QTableView::sizeHintForRow(), и QTreeView::sizeHintForColumn().

void QHeaderView::setSectionHidden(int logicalIndex, bool hide)

Если hide равно true, секция, указанная logicalIndex, скрывается; в противном случае секция отображается.

См. также isSectionHidden() и hiddenSectionCount().

[since 5.0] void QHeaderView::setSectionResizeMode(QHeaderView::ResizeMode mode)

Устанавливает ограничения на изменение размера заголовка, описанные в заданном mode.

Данная функция была введена в Qt 5.0.

См. также sectionResizeMode(), length(), и sectionResized().

[since 5.0] void QHeaderView::setSectionResizeMode(int logicalIndex, QHeaderView::ResizeMode mode)

Устанавливает ограничения на изменение размера секции, указанной logicalIndex в заголовке, описанные в заданном mode. Логический индекс должен существовать в момент вызова данной функции.

Примечание: Это настройка будет проигнорирована для последней секции, если свойство stretchLastSection установлено в true. Это значение по умолчанию для горизонтальных заголовков, предоставляемых QTreeView.

Данная функция была введена в Qt 5.0.

См. также setStretchLastSection() и resizeContentsPrecision().

[since 5.0] void QHeaderView::setSectionsClickable(bool clickable)

Если clickable равно true, заголовок будет реагировать на одиночные щелчки.

Данная функция была введена в Qt 5.0.

См. также sectionsClickable(), sectionClicked(), sectionPressed(), и setSortIndicatorShown().

[since 5.0] void QHeaderView::setSectionsMovable(bool movable)

Если movable равно true, секции заголовка могут быть перемещены пользователем; в противном случае они фиксируются на месте.

При использовании в сочетании с QTreeView, первая колонка по умолчанию не может быть перемещена (поскольку она содержит структуру дерева). Вы можете сделать её перемещаемой с помощью setFirstSectionMovable(true).

Данная функция была введена в Qt 5.0.

См. также sectionsMovable(), sectionMoved(), и setFirstSectionMovable().

[override virtual protected] void QHeaderView::setSelection(const QRect &rect, QItemSelectionModel::SelectionFlags flags)

Реализует: QAbstractItemView::setSelection(const QRect &rect, QItemSelectionModel::SelectionFlags flags).

Выбирает элементы в заданной rect в соответствии с заданными flags.

Реализация базового класса ничего не делает.

void QHeaderView::setSortIndicator(int logicalIndex, Qt::SortOrder order)

Устанавливает индикатор сортировки для секции, заданной заданным logicalIndex, в направлении, заданном order, и удаляет индикатор сортировки из любой другой секции, которая его показывала.

logicalIndex может быть -1, в этом случае индикатор сортировки не будет отображаться, и модель вернётся к своему естественному, несортированному порядку. Обратите внимание, что не все модели поддерживают это и могут даже упасть в этом случае.

См. также sortIndicatorSection() и sortIndicatorOrder().

[override virtual] void QHeaderView::setVisible(bool v)

Реализует функцию доступа к свойству: QWidget::visible.

void QHeaderView::showSection(int logicalIndex)

Отображает секцию, указанную logicalIndex.

См. также hideSection(), isSectionHidden(), hiddenSectionCount(), и setSectionHidden().

[override virtual] QSize QHeaderView::sizeHint() const

Реализует: QAbstractScrollArea::sizeHint() const.

Возвращает подходящий размер для данного заголовка.

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

Qt::SortOrder QHeaderView::sortIndicatorOrder() const

Возвращает порядок индикатора сортировки. Если ни одна секция не имеет индикатора сортировки, значение возврата этой функции не определено.

См. также setSortIndicator() и sortIndicatorSection().

int QHeaderView::sortIndicatorSection() const

Возвращает логический индекс секции, которая имеет индикатор сортировки. По умолчанию это секция 0.

См. также setSortIndicator(), sortIndicatorOrder(), и setSortIndicatorShown().

int QHeaderView::stretchSectionCount() const

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

См. также stretchLastSection.

void QHeaderView::swapSections(int first, int second)

Меняет местами секцию с визуальным индексом first и секцию с визуальным индексом second.

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

[override virtual protected] int QHeaderView::verticalOffset() const

Переопределяет: QAbstractItemView::verticalOffset() const.

Возвращает вертикальное смещение заголовка. Для горизонтальных заголовков это 0.

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

[override virtual protected] bool QHeaderView::viewportEvent(QEvent *e)

Переопределяет: QAbstractItemView::viewportEvent(QEvent *event).

int QHeaderView::visualIndex(int logicalIndex) const

Возвращает позицию визуального индекса секции, заданной данным logicalIndex, или -1 в противном случае.

Скрытые секции по-прежнему имеют допустимые визуальные индексы.

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

int QHeaderView::visualIndexAt(int position) const

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

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