Contents

• Properties
• Public Functions
• Reimplemented Public Functions
• Protected Functions
• Reimplemented Protected Functions
• Protected Slots
• Detailed Description

Detailed Description

TheQAbstractScrollArea widget provides a scrolling area with on-demand scroll bars.

QAbstractScrollArea is a low-level abstraction of a scrolling area. The area provides a central widget called the viewport, in which the contents of the area is to be scrolled (i.e, the visible parts of the contents are rendered in the viewport).

Next to the viewport is a vertical scroll bar, and below is a horizontal scroll bar. When all of the area contents fits in the viewport, each scroll bar can be either visible or hidden depending on the scroll bar'sQt::ScrollBarPolicy. When a scroll bar is hidden, the viewport expands in order to cover all available space. When a scroll bar becomes visible again, the viewport shrinks in order to make room for the scroll bar.

It is possible to reserve a margin area around the viewport, seesetViewportMargins(). The feature is mostly used to place aQHeaderView widget above or beside the scrolling area. Subclasses ofQAbstractScrollArea should implement margins.

When inheritingQAbstractScrollArea, you need to do the following:

• Control the scroll bars by setting their range, value, page step, and tracking their movements.
• Draw the contents of the area in the viewport according to the values of the scroll bars.
• Handle events received by the viewport inviewportEvent() - notably resize events.
• Useviewport->update() to update the contents of the viewport instead ofupdate() as all painting operations take place on the viewport.

With a scroll bar policy ofQt::ScrollBarAsNeeded (the default),QAbstractScrollArea shows scroll bars when they provide a non-zero scrolling range, and hides them otherwise.

The scroll bars and viewport should be updated whenever the viewport receives a resize event or the size of the contents changes. The viewport also needs to be updated when the scroll bars values change. The initial values of the scroll bars are often set when the area receives new contents.

We give a simple example, in which we have implemented a scroll area that can scroll anyQWidget. We make the widget a child of the viewport; this way, we do not have to calculate which part of the widget to draw but can simply move the widget withQWidget::move(). When the area contents or the viewport size changes, we do the following:

QSize areaSize= viewport()->size();QSize  widgetSize= widget->size();    verticalScrollBar()->setPageStep(areaSize.height());    horizontalScrollBar()->setPageStep(areaSize.width());    verticalScrollBar()->setRange(0, widgetSize.height()- areaSize.height());    horizontalScrollBar()->setRange(0, widgetSize.width()- areaSize.width());    updateWidgetPosition();

When the scroll bars change value, we need to update the widget position, i.e., find the part of the widget that is to be drawn in the viewport:

int hvalue= horizontalScrollBar()->value();int vvalue= verticalScrollBar()->value();QPoint topLeft= viewport()->rect().topLeft();    widget->move(topLeft.x()- hvalue, topLeft.y()- vvalue);

In order to track scroll bar movements, reimplement the virtual functionscrollContentsBy(). In order to fine-tune scrolling behavior, connect to a scroll bar'sQAbstractSlider::actionTriggered() signal and adjust theQAbstractSlider::sliderPosition as you wish.

For convenience,QAbstractScrollArea makes all viewport events available in the virtualviewportEvent() handler.QWidget's specialized handlers are remapped to viewport events in the cases where this makes sense. The remapped specialized handlers are:paintEvent(),mousePressEvent(),mouseReleaseEvent(),mouseDoubleClickEvent(),mouseMoveEvent(),wheelEvent(),dragEnterEvent(),dragMoveEvent(),dragLeaveEvent(),dropEvent(),contextMenuEvent(), andresizeEvent().

QScrollArea, which inheritsQAbstractScrollArea, provides smooth scrolling for anyQWidget (i.e., the widget is scrolled pixel by pixel). You only need to subclassQAbstractScrollArea if you need more specialized behavior. This is, for instance, true if the entire contents of the area is not suitable for being drawn on aQWidget or if you do not want smooth scrolling.

Property Documentation

horizontalScrollBarPolicy :Qt::ScrollBarPolicy

This property holds the policy for the horizontal scroll bar.

The default policy isQt::ScrollBarAsNeeded.

Access functions:

See alsoverticalScrollBarPolicy.

verticalScrollBarPolicy :Qt::ScrollBarPolicy

This property holds the policy for the vertical scroll bar.

The default policy isQt::ScrollBarAsNeeded.

Access functions:

See alsohorizontalScrollBarPolicy.

Member Function Documentation

QAbstractScrollArea::QAbstractScrollArea(QWidget * parent = 0)

Constructs a viewport.

Theparent argument is sent to theQWidget constructor.

QAbstractScrollArea::~QAbstractScrollArea()

Destroys the viewport.

void QAbstractScrollArea::addScrollBarWidget(QWidget * widget,Qt::Alignment alignment)

Addswidget as a scroll bar widget in the location specified byalignment.

Scroll bar widgets are shown next to the horizontal or vertical scroll bar, and can be placed on either side of it. If you want the scroll bar widgets to be always visible, set the scrollBarPolicy for the corresponding scroll bar toAlwaysOn.

alignment must be one of Qt::Alignleft andQt::AlignRight, which maps to the horizontal scroll bar, orQt::AlignTop andQt::AlignBottom, which maps to the vertical scroll bar.

A scroll bar widget can be removed by either re-parenting the widget or deleting it. It's also possible to hide a widget withQWidget::hide()

The scroll bar widget will be resized to fit the scroll bar geometry for the current style. The following describes the case for scroll bar widgets on the horizontal scroll bar:

The height of the widget will be set to match the height of the scroll bar. To control the width of the widget, useQWidget::setMinimumWidth andQWidget::setMaximumWidth, or implementQWidget::sizeHint() and set a horizontal size policy. If you want a square widget, callQStyle::pixelMetric(QStyle::PM_ScrollBarExtent) and set the width to this value.

This function was introduced in Qt 4.2.

See alsoscrollBarWidgets().

[virtual protected]void QAbstractScrollArea::contextMenuEvent(QContextMenuEvent * e)

Reimplemented fromQWidget::contextMenuEvent().

This event handler can be reimplemented in a subclass to receive context menu events for theviewport() widget. The event is passed ine.

See alsoQWidget::contextMenuEvent().

QWidget * QAbstractScrollArea::cornerWidget() const

Returns the widget in the corner between the two scroll bars.

By default, no corner widget is present.

This function was introduced in Qt 4.2.

See alsosetCornerWidget().

[virtual protected]void QAbstractScrollArea::dragEnterEvent(QDragEnterEvent * event)

Reimplemented fromQWidget::dragEnterEvent().

This event handler can be reimplemented in a subclass to receive drag enter events (passed inevent), for theviewport() widget.

See alsoQWidget::dragEnterEvent().

[virtual protected]void QAbstractScrollArea::dragLeaveEvent(QDragLeaveEvent * event)

Reimplemented fromQWidget::dragLeaveEvent().

This event handler can be reimplemented in a subclass to receive drag leave events (passed inevent), for theviewport() widget.

See alsoQWidget::dragLeaveEvent().

[virtual protected]void QAbstractScrollArea::dragMoveEvent(QDragMoveEvent * event)

Reimplemented fromQWidget::dragMoveEvent().

This event handler can be reimplemented in a subclass to receive drag move events (passed inevent), for theviewport() widget.

See alsoQWidget::dragMoveEvent().

[virtual protected]void QAbstractScrollArea::dropEvent(QDropEvent * event)

Reimplemented fromQWidget::dropEvent().

This event handler can be reimplemented in a subclass to receive drop events (passed inevent), for theviewport() widget.

See alsoQWidget::dropEvent().

[virtual protected]bool QAbstractScrollArea::event(QEvent * event)

Reimplemented fromQObject::event().

This is the main event handler for theQAbstractScrollArea widget (not the scrolling areaviewport()). The specifiedevent is a general event object that may need to be cast to the appropriate class depending on its type.

See alsoQEvent::type().

QScrollBar * QAbstractScrollArea::horizontalScrollBar() const

Returns the horizontal scroll bar.

See alsosetHorizontalScrollBar(),horizontalScrollBarPolicy, andverticalScrollBar().

[virtual protected]void QAbstractScrollArea::keyPressEvent(QKeyEvent * e)

Reimplemented fromQWidget::keyPressEvent().

This function is called with key evente when key presses occur. It handles PageUp, PageDown, Up, Down, Left, and Right, and ignores all other key presses.

QSize QAbstractScrollArea::maximumViewportSize() const

Returns the size of the viewport as if the scroll bars had no valid scrolling range.

[virtual]QSize QAbstractScrollArea::minimumSizeHint() const

Reimplemented fromQWidget::minimumSizeHint().

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

Reimplemented fromQWidget::mouseDoubleClickEvent().

This event handler can be reimplemented in a subclass to receive mouse double click events for theviewport() widget. The event is passed ine.

See alsoQWidget::mouseDoubleClickEvent().

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

Reimplemented fromQWidget::mouseMoveEvent().

This event handler can be reimplemented in a subclass to receive mouse move events for theviewport() widget. The event is passed ine.

See alsoQWidget::mouseMoveEvent().

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

Reimplemented fromQWidget::mousePressEvent().

This event handler can be reimplemented in a subclass to receive mouse press events for theviewport() widget. The event is passed ine.

See alsoQWidget::mousePressEvent().

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

Reimplemented fromQWidget::mouseReleaseEvent().

This event handler can be reimplemented in a subclass to receive mouse release events for theviewport() widget. The event is passed ine.

See alsoQWidget::mouseReleaseEvent().

[virtual protected]void QAbstractScrollArea::paintEvent(QPaintEvent * event)

Reimplemented fromQWidget::paintEvent().

This event handler can be reimplemented in a subclass to receive paint events (passed inevent), for theviewport() widget.

Note:If you open a painter, make sure to open it on theviewport().

See alsoQWidget::paintEvent().

[virtual protected]void QAbstractScrollArea::resizeEvent(QResizeEvent * event)

Reimplemented fromQWidget::resizeEvent().

This event handler can be reimplemented in a subclass to receive resize events (passed inevent), for theviewport() widget.

When resizeEvent() is called, the viewport already has its new geometry: Its new size is accessible through theQResizeEvent::size() function, and the old size throughQResizeEvent::oldSize().

See alsoQWidget::resizeEvent().

QWidgetList QAbstractScrollArea::scrollBarWidgets(Qt::Alignment alignment)

Returns a list of the currently set scroll bar widgets.alignment can be any combination of the four location flags.

This function was introduced in Qt 4.2.

See alsoaddScrollBarWidget().

[virtual protected]void QAbstractScrollArea::scrollContentsBy(int dx,int dy)

This virtual handler is called when the scroll bars are moved bydx,dy, and consequently the viewport's contents should be scrolled accordingly.

The default implementation simply callsupdate() on the entireviewport(), subclasses can reimplement this handler for optimization purposes, or - likeQScrollArea - to move a contents widget. The parametersdx anddy are there for convenience, so that the class knows how much should be scrolled (useful e.g. when doing pixel-shifts). You may just as well ignore these values and scroll directly to the position the scroll bars indicate.

Calling this function in order to scroll programmatically is an error, use the scroll bars instead (e.g. by callingQScrollBar::setValue() directly).

void QAbstractScrollArea::setCornerWidget(QWidget * widget)

Sets the widget in the corner between the two scroll bars to bewidget.

You will probably also want to set at least one of the scroll bar modes toAlwaysOn.

Passing 0 shows no widget in the corner.

Any previous corner widget is hidden.

You may call setCornerWidget() with the same widget at different times.

All widgets set here will be deleted by the scroll area when it is destroyed unless you separately reparent the widget after setting some other corner widget (or 0).

Anynewly set widget should have no current parent.

By default, no corner widget is present.

This function was introduced in Qt 4.2.

See alsocornerWidget(),horizontalScrollBarPolicy, andhorizontalScrollBarPolicy.

void QAbstractScrollArea::setHorizontalScrollBar(QScrollBar * scrollBar)

Replaces the existing horizontal scroll bar withscrollBar, and sets all the former scroll bar's slider properties on the new scroll bar. The former scroll bar is then deleted.

QAbstractScrollArea already provides horizontal and vertical scroll bars by default. You can call this function to replace the default horizontal scroll bar with your own custom scroll bar.

This function was introduced in Qt 4.2.

See alsohorizontalScrollBar() andsetVerticalScrollBar().

void QAbstractScrollArea::setVerticalScrollBar(QScrollBar * scrollBar)

Replaces the existing vertical scroll bar withscrollBar, and sets all the former scroll bar's slider properties on the new scroll bar. The former scroll bar is then deleted.

QAbstractScrollArea already provides vertical and horizontal scroll bars by default. You can call this function to replace the default vertical scroll bar with your own custom scroll bar.

This function was introduced in Qt 4.2.

See alsoverticalScrollBar() andsetHorizontalScrollBar().

void QAbstractScrollArea::setViewport(QWidget * widget)

Sets the viewport to be the givenwidget. TheQAbstractScrollArea will take ownership of the givenwidget.

Ifwidget is 0,QAbstractScrollArea will assign a newQWidget instance for the viewport.

This function was introduced in Qt 4.2.

See alsoviewport().

[protected]void QAbstractScrollArea::setViewportMargins(int left,int top,int right,int bottom)

Sets the margins around the scrolling area toleft,top,right andbottom. This is useful for applications such as spreadsheets with "locked" rows and columns. The marginal space is is left blank; put widgets in the unused area.

Note that this function is frequently called byQTreeView andQTableView, so margins must be implemented byQAbstractScrollArea subclasses. Also, if the subclasses are to be used in item views, they should not call this function.

By default all margins are zero.

[protected]void QAbstractScrollArea::setViewportMargins(constQMargins & margins)

Setsmargins around the scrolling area. This is useful for applications such as spreadsheets with "locked" rows and columns. The marginal space is is left blank; put widgets in the unused area.

By default all margins are zero.

This function was introduced in Qt 4.6.

[protected slot]void QAbstractScrollArea::setupViewport(QWidget * viewport)

This slot is called byQAbstractScrollArea aftersetViewport(viewport) has been called. Reimplement this function in a subclass ofQAbstractScrollArea to initialize the newviewport before it is used.

See alsosetViewport().

[virtual]QSize QAbstractScrollArea::sizeHint() const

Reimplemented fromQWidget::sizeHint().

QScrollBar * QAbstractScrollArea::verticalScrollBar() const

Returns the vertical scroll bar.

See alsosetVerticalScrollBar(),verticalScrollBarPolicy, andhorizontalScrollBar().

QWidget * QAbstractScrollArea::viewport() const

Returns the viewport widget.

Use theQScrollArea::widget() function to retrieve the contents of the viewport widget.

See alsosetViewport() andQScrollArea::widget().

[virtual protected]bool QAbstractScrollArea::viewportEvent(QEvent * event)

The main event handler for the scrolling area (theviewport() widget). It handles theevent specified, and can be called by subclasses to provide reasonable default behavior.

Returns true to indicate to the event system that the event has been handled, and needs no further processing; otherwise returns false to indicate that the event should be propagated further.

You can reimplement this function in a subclass, but we recommend using one of the specialized event handlers instead.

Specialized handlers for viewport events are:paintEvent(),mousePressEvent(),mouseReleaseEvent(),mouseDoubleClickEvent(),mouseMoveEvent(),wheelEvent(),dragEnterEvent(),dragMoveEvent(),dragLeaveEvent(),dropEvent(),contextMenuEvent(), andresizeEvent().

[virtual protected]void QAbstractScrollArea::wheelEvent(QWheelEvent * e)

Reimplemented fromQWidget::wheelEvent().

This event handler can be reimplemented in a subclass to receive wheel events for theviewport() widget. The event is passed ine.

See alsoQWidget::wheelEvent().