Contents

• Public Types
• Properties
• Public Functions
• Reimplemented Public Functions
• Public Slots
• Signals
• Protected Functions
• Reimplemented Protected Functions
• Protected Slots
• Detailed Description
• Moving Header Sections
• Appearance

Detailed Description

TheQHeaderView class provides a header row or header column for item views.

AQHeaderView displays the headers used in item views such as theQTableView andQTreeView classes. It takes the place of Qt3'sQHeader class previously used for the same purpose, but uses the Qt's model/view architecture for consistency with the item view classes.

TheQHeaderView class is one of theModel/View Classes and is part of Qt'smodel/view framework.

The header gets the data for each section from the model using theQAbstractItemModel::headerData() function. You can set the data by usingQAbstractItemModel::setHeaderData().

Each header has anorientation() and a number of sections, given by thecount() function. A section refers to a part of the header - either a row or a column, depending on the orientation.

Sections can be moved and resized usingmoveSection() andresizeSection(); they can also be hidden and shown withhideSection() andshowSection().

Each section of a header is described by a section ID, specified by its section(), and can be located at a particularvisualIndex() in the header. A section can have a sort indicator set withsetSortIndicator(); this indicates whether the items in the associated item view will be sorted in the order given by the section.

For a horizontal header the section is equivalent to a column in the model, and for a vertical header the section is equivalent to a row in the model.

Moving Header Sections

A header can be fixed in place, or made movable withsetMovable(). It can be made clickable withsetClickable(), and has resizing behavior in accordance withsetResizeMode().

Note:Double-clicking on a header to resize a section only applies for visible rows.

A header will emitsectionMoved() if the user moves a section,sectionResized() if the user resizes a section, andsectionClicked() as well assectionHandleDoubleClicked() in response to mouse clicks. A header will also emitsectionCountChanged() andsectionAutoResize().

You can identify a section using thelogicalIndex() andlogicalIndexAt() functions, or by its index position, using thevisualIndex() andvisualIndexAt() functions. The visual index will change if a section is moved, but the logical index will not change.

Appearance

QTableWidget andQTableView create default headers. If you want the headers to be visible, you can usesetVisible().

Not allItemDataRoles will have an effect on aQHeaderView. If you need to draw other roles, you can subclassQHeaderView and reimplementpaintEvent().QHeaderView respects the following item data roles:TextAlignmentRole,DisplayRole,FontRole,DecorationRole,ForegroundRole, andBackgroundRole.

Note:Each header renders the data for each section itself, and does not rely on a delegate. As a result, calling a header'ssetItemDelegate() function will have no effect.

Member Type Documentation

enum QHeaderView::ResizeMode

The resize mode specifies the behavior of the header sections. It can be set on the entire header view or on individual sections usingsetResizeMode().

The following values are obsolete:

See alsosetResizeMode(),stretchLastSection, andminimumSectionSize.

Property Documentation

cascadingSectionResizes :bool

This property holds whether interactive resizing will be cascaded to the following sections once the section being resized by the user has reached its minimum size.

This property only affects sections that haveInteractive as their resize mode.

The default value is false.

This property was introduced in Qt 4.2.

Access functions:

See alsosetResizeMode().

defaultAlignment :Qt::Alignment

This property holds the default alignment of the text in each header section.

This property was introduced in Qt 4.1.

Access functions:

defaultSectionSize :int

This property holds the default size of the header sections before resizing.

This property only affects sections that haveInteractive orFixed as their resize mode.

Access functions:

See alsosetResizeMode() andminimumSectionSize.

highlightSections :bool

This property holds whether the sections containing selected items are highlighted.

By default, this property is false.

Access functions:

minimumSectionSize :int

This property holds the minimum size of the header sections.

The minimum section size is the smallest section size allowed. If the minimum section size is set to -1,QHeaderView will use the maximum of theglobal strut or thefont metrics size.

This property is honored by allresize modes.

This property was introduced in Qt 4.2.

Access functions:

See alsosetResizeMode() anddefaultSectionSize.

showSortIndicator :bool

This property holds whether the sort indicator is shown.

By default, this property is false.

Access functions:

See alsosetClickable().

stretchLastSection :bool

This property holds whether the last visible section in the header takes up all the available space.

The default value is false.

Note:The horizontal headers provided byQTreeView are configured with this property set to true, ensuring that the view does not waste any of the space assigned to it for its header. If this value is set to true, this property will override the resize mode set on the last section in the header.

Access functions:

See alsosetResizeMode().

Member Function Documentation

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

Creates a new generic header with the givenorientation andparent.

[virtual]QHeaderView::~QHeaderView()

Destroys the header.

int QHeaderView::count() const

Returns the number of sections in the header.

See alsosectionCountChanged() andlength().

[virtual protected]void QHeaderView::currentChanged(constQModelIndex & current, constQModelIndex & old)

Reimplemented fromQAbstractItemView::currentChanged().

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

Reimplemented fromQObject::event().

[signal]void QHeaderView::geometriesChanged()

This signal is emitted when the header's geometries have changed.

This function was introduced in Qt 4.2.

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

Updates the changed header sections with the givenorientation, fromlogicalFirst tologicalLast inclusive.

int QHeaderView::hiddenSectionCount() const

Returns the number of sections in the header that has been hidden.

This function was introduced in Qt 4.1.

See alsosetSectionHidden() andisSectionHidden().

void QHeaderView::hideSection(int logicalIndex)

Hides the section specified bylogicalIndex.

See alsoshowSection(),isSectionHidden(),hiddenSectionCount(), andsetSectionHidden().

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

Reimplemented fromQAbstractItemView::horizontalOffset().

Returns the horizontal offset of the header. This is 0 for vertical headers.

See alsooffset().

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

Initializeoption with the values from thisQHeaderView. This method is useful for subclasses when they need aQStyleOptionHeader, but do not want to fill in all the information themselves.

See alsoQStyleOption::initFrom().

bool QHeaderView::isClickable() const

Returns true if the header is clickable; otherwise returns false. A clickable header could be set up to allow the user to change the representation of the data in the view related to the header.

See alsosetClickable().

bool QHeaderView::isMovable() const

Returns true if the header can be moved by the user; otherwise returns false.

See alsosetMovable().

bool QHeaderView::isSectionHidden(int logicalIndex) const

Returns true if the section specified bylogicalIndex is explicitly hidden from the user; otherwise returns false.

See alsohideSection(),showSection(),setSectionHidden(), andhiddenSectionCount().

int QHeaderView::length() const

Returns the length along the orientation of the header.

See alsosizeHint(),setResizeMode(), andoffset().

int QHeaderView::logicalIndex(int visualIndex) const

Returns the logicalIndex for the section at the givenvisualIndex position, or -1 ifvisualIndex < 0 orvisualIndex >=QHeaderView::count().

Note that thevisualIndex is not affected by hidden sections.

See alsovisualIndex() andsectionPosition().

int QHeaderView::logicalIndexAt(int position) const

Returns the section that covers the givenposition in the viewport.

See alsovisualIndexAt() andisSectionHidden().

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

Returns the logical index of the section at the given coordinate. If the header is horizontalx will be used, otherwisey will be used to find the logical index.

int QHeaderView::logicalIndexAt(constQPoint & pos) const

Returns the logical index of the section at the position given inpos. If the header is horizontal the x-coordinate will be used, otherwise the y-coordinate will be used to find the logical index.

See alsosectionPosition().

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

Reimplemented fromQWidget::mouseDoubleClickEvent().

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

Reimplemented fromQWidget::mouseMoveEvent().

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

Reimplemented fromQWidget::mousePressEvent().

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

Reimplemented fromQWidget::mouseReleaseEvent().

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

Moves the section at visual indexfrom to occupy visual indexto.

See alsosectionsMoved().

int QHeaderView::offset() const

Returns the offset of the header: this is the header's left-most (or top-most for vertical headers) visible pixel.

See alsosetOffset().

Qt::Orientation QHeaderView::orientation() const

Returns the orientation of the header.

See alsoQt::Orientation.

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

Reimplemented fromQWidget::paintEvent().

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

Paints the section specified by the givenlogicalIndex, using the givenpainter andrect.

Normally, you do not have to call this function.

[virtual]void QHeaderView::reset()

Reimplemented fromQAbstractItemView::reset().

ResizeMode QHeaderView::resizeMode(int logicalIndex) const

Returns the resize mode that applies to the section specified by the givenlogicalIndex.

See alsosetResizeMode().

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

Resizes the section specified bylogicalIndex tosize measured in pixels.

See alsosectionResized(),resizeMode(), andsectionSize().

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

Resizes the sections according to the givenmode, ignoring the current resize mode.

See alsoresizeMode() andsectionResized().

[protected slot]void QHeaderView::resizeSections()

Resizes the sections according to their size hints. Normally, you do not have to call this function.

bool QHeaderView::restoreState(constQByteArray & state)

Restores thestate of this header view. This function returnstrue if the state was restored; otherwise returns false.

This function was introduced in Qt 4.3.

See alsosaveState().

QByteArray QHeaderView::saveState() const

Saves the current state of this header view.

To restore the saved state, pass the return value torestoreState().

This function was introduced in Qt 4.3.

See alsorestoreState().

[signal]void QHeaderView::sectionAutoResize(int logicalIndex,QHeaderView::ResizeMode mode)

This signal is emitted when a section is automatically resized. The section's logical index is specified bylogicalIndex, and the resize mode bymode.

See alsosetResizeMode() andstretchLastSection().

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

This signal is emitted when a section is clicked. The section's logical index is specified bylogicalIndex.

Note that thesectionPressed signal will also be emitted.

See alsosetClickable() andsectionPressed().

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

This signal is emitted when the number of sections changes, i.e., when sections are added or deleted. The original count is specified byoldCount, and the new count bynewCount.

See alsocount(),length(), andheaderDataChanged().

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

This signal is emitted when a section is double-clicked. The section's logical index is specified bylogicalIndex.

See alsosetClickable().

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

This signal is emitted when the cursor moves over the section and the left mouse button is pressed. The section's logical index is specified bylogicalIndex.

This function was introduced in Qt 4.3.

See alsosetClickable() andsectionPressed().

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

This signal is emitted when a section is double-clicked. The section's logical index is specified bylogicalIndex.

See alsosetClickable().

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

This signal is emitted when a section is moved. The section's logical index is specified bylogicalIndex, the old index byoldVisualIndex, and the new index position bynewVisualIndex.

See alsomoveSection().

int QHeaderView::sectionPosition(int logicalIndex) const

Returns the section position of the givenlogicalIndex, or -1 if the section is hidden. The position is measured in pixels from the first visible item's top-left corner to the top-left corner of the item withlogicalIndex. The measurement is along the x-axis for horizontal headers and along the y-axis for vertical headers.

See alsosectionViewportPosition().

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

This signal is emitted when a section is pressed. The section's logical index is specified bylogicalIndex.

See alsosetClickable().

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

This signal is emitted when a section is resized. The section's logical number is specified bylogicalIndex, the old size byoldSize, and the new size bynewSize.

See alsoresizeSection().

int QHeaderView::sectionSize(int logicalIndex) const

Returns the width (or height for vertical headers) of the givenlogicalIndex.

See alsolength(),setResizeMode(), anddefaultSectionSize().

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

Returns the size of the contents of the section specified by the givenlogicalIndex.

See alsodefaultSectionSize().

int QHeaderView::sectionSizeHint(int logicalIndex) const

Returns a suitable size hint for the section specified bylogicalIndex.

See alsosizeHint(),defaultSectionSize(),minimumSectionSize(), andQt::SizeHintRole.

int QHeaderView::sectionViewportPosition(int logicalIndex) const

Returns the section viewport position of the givenlogicalIndex.

If the section is hidden, the return value is undefined.

See alsosectionPosition() andisSectionHidden().

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

This slot is called when sections are removed from theparent.logicalFirst andlogicalLast signify where the sections were removed.

If only one section is removed,logicalFirst andlogicalLast will be the same.

bool QHeaderView::sectionsHidden() const

Returns true if sections in the header has been hidden; otherwise returns false;

This function was introduced in Qt 4.1.

See alsosetSectionHidden().

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

This slot is called when sections are inserted into theparent.logicalFirst andlogicalLast indices signify where the new sections were inserted.

If only one section is inserted,logicalFirst andlogicalLast will be the same.

bool QHeaderView::sectionsMoved() const

Returns true if sections in the header has been moved; otherwise returns false;

See alsomoveSection().

void QHeaderView::setClickable(bool clickable)

Ifclickable is true, the header will respond to single clicks.

See alsoisClickable(),sectionClicked(),sectionPressed(), andsetSortIndicatorShown().

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

Reimplemented fromQAbstractItemView::setModel().

void QHeaderView::setMovable(bool movable)

Ifmovable is true, the header may be moved by the user; otherwise it is fixed in place.

See alsoisMovable() andsectionMoved().

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

Sets the header's offset tooffset.

See alsooffset() andlength().

[slot]void QHeaderView::setOffsetToLastSection()

Sets the offset to make the last section visible.

This function was introduced in Qt 4.2.

See alsosetOffset(),sectionPosition(), andsetOffsetToSectionPosition().

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

Sets the offset to the start of the section at the givenvisualIndex.

This function was introduced in Qt 4.2.

See alsosetOffset() andsectionPosition().

void QHeaderView::setResizeMode(ResizeMode mode)

Sets the constraints on how the header can be resized to those described by the givenmode.

See alsoresizeMode(),length(),sectionResized(), andsectionAutoResize().

void QHeaderView::setResizeMode(int logicalIndex,ResizeMode mode)

This is an overloaded function.

Sets the constraints on how the section specified bylogicalIndex in the header can be resized to those described by the givenmode. The logical index should exist at the time this function is called.

Note:This setting will be ignored for the last section if thestretchLastSection property is set to true. This is the default for the horizontal headers provided byQTreeView.

See alsosetStretchLastSection().

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

Ifhide is true the section specified bylogicalIndex is hidden; otherwise the section is shown.

See alsoisSectionHidden() andhiddenSectionCount().

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

Reimplemented fromQAbstractItemView::setSelection().

Selects the items in the givenrect according to the specifiedflags.

The base class implementation does nothing.

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

Sets the sort indicator for the section specified by the givenlogicalIndex in the direction specified byorder, and removes the sort indicator from any other section that was showing it.

logicalIndex may be -1, in which case no sort indicator will be shown and the model will return to its natural, unsorted order. Note that not all models support this and may even crash in this case.

See alsosortIndicatorSection() andsortIndicatorOrder().

void QHeaderView::showSection(int logicalIndex)

Shows the section specified bylogicalIndex.

See alsohideSection(),isSectionHidden(),hiddenSectionCount(), andsetSectionHidden().

[virtual]QSize QHeaderView::sizeHint() const

Reimplemented fromQWidget::sizeHint().

Returns a suitable size hint for this header.

See alsosectionSizeHint().

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

This signal is emitted when the section containing the sort indicator or the order indicated is changed. The section's logical index is specified bylogicalIndex and the sort order is specified byorder.

This function was introduced in Qt 4.3.

See alsosetSortIndicator().

Qt::SortOrder QHeaderView::sortIndicatorOrder() const

Returns the order for the sort indicator. If no section has a sort indicator the return value of this function is undefined.

See alsosetSortIndicator() andsortIndicatorSection().

int QHeaderView::sortIndicatorSection() const

Returns the logical index of the section that has a sort indicator. By default this is section 0.

See alsosetSortIndicator(),sortIndicatorOrder(), andsetSortIndicatorShown().

int QHeaderView::stretchSectionCount() const

Returns the number of sections that are set to resize mode stretch. In views, this can be used to see if the headerview needs to resize the sections when the view's geometry changes.

This function was introduced in Qt 4.1.

See alsostretchLastSection andresizeMode().

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

Swaps the section at visual indexfirst with the section at visual indexsecond.

This function was introduced in Qt 4.2.

See alsomoveSection().

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

Reimplemented fromQAbstractItemView::verticalOffset().

Returns the vertical offset of the header. This is 0 for horizontal headers.

See alsooffset().

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

Reimplemented fromQAbstractScrollArea::viewportEvent().

int QHeaderView::visualIndex(int logicalIndex) const

Returns the visual index position of the section specified by the givenlogicalIndex, or -1 otherwise.

Hidden sections still have valid visual indexes.

See alsologicalIndex().

int QHeaderView::visualIndexAt(int position) const

Returns the visual index of the section that covers the givenposition in the viewport.

See alsologicalIndexAt().