Detailed Description
The QAbstractScrollArea widget provides a scrolling area with on-demand scroll bars.
QAbstractScrollArea is a low-level abstraction of a scrolling area. It gives you full control of the scroll bars, at the cost of simplicity. In most cases, using a QScrollArea is preferable.
QAbstractScrollArea's central child widget is the scrolling area itself, called viewport(). The viewport widget uses all available space. Next to the viewport is a vertical scroll bar (accessible with verticalScrollBar()), and below a horizontal scroll bar (accessible with horizontalScrollBar()). Each scroll bar can be either visible or hidden, depending on the scroll bar's policy (see verticalScrollBarPolicy and horizontalScrollBarPolicy). 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.
With a scroll bar policy of Qt::ScrollBarAsNeeded (the default), QAbstractScrollArea shows scroll bars when those provide a non-zero scrolling range, and hides them otherwise. You control the range of each scroll bar with QAbstractSlider::setRange().
In order to track scroll bar movements, reimplement the virtual function scrollContentsBy(). In order to fine-tune scrolling behavior, connect to a scroll bar's QAbstractSlider::actionTriggered() signal and adjust the QAbstractSlider::sliderPosition as you wish.
It is possible to reserve a margin area around the viewport, see setViewportMargins(). The feature is mostly used to place a QHeaderView widget above or beside the scrolling area.
For convenience, QAbstractScrollArea makes all viewport events available in the virtual viewportEvent() handler. QWidget's specialised handlers are remapped to viewport events in the cases where this makes sense. The remapped specialised handlers are: paintEvent(), mousePressEvent(), mouseReleaseEvent(), mouseDoubleClickEvent(), mouseMoveEvent(), wheelEvent(), dragEnterEvent(), dragMoveEvent(), dragLeaveEvent(), dropEvent(), contextMenuEvent(). and resizeEvent().
Property Documentation
This property holds the policy for the horizontal scroll bar.
The default policy is Qt::ScrollBarAsNeeded.
Access functions:
- Qt::ScrollBarPolicy horizontalScrollBarPolicy () const
- void setHorizontalScrollBarPolicy ( Qt::ScrollBarPolicy )
See also verticalScrollBarPolicy.
This property holds the policy for the vertical scroll bar.
The default policy is Qt::ScrollBarAsNeeded.
Access functions:
- Qt::ScrollBarPolicy verticalScrollBarPolicy () const
- void setVerticalScrollBarPolicy ( Qt::ScrollBarPolicy )
See also horizontalScrollBarPolicy.
Member Function Documentation
QAbstractScrollArea::QAbstractScrollArea ( QWidget * parent = 0 )
Constructs a viewport.
The parent arguments is sent to the QWidget constructor.
QAbstractScrollArea::~QAbstractScrollArea ()
Destroys the viewport.
This event handler can be reimplemented in a subclass to receive context menu events for the viewport() widget. The event is passed in e.
Reimplemented from QWidget.
See also QWidget::contextMenuEvent().
void QAbstractScrollArea::dragEnterEvent ( QDragEnterEvent * event ) [virtual protected]
This event handler can be reimplemented in a subclass to receive drag enter events (passed in event), for the viewport() widget.
Reimplemented from QWidget.
See also QWidget::dragEnterEvent().
void QAbstractScrollArea::dragLeaveEvent ( QDragLeaveEvent * event ) [virtual protected]
This event handler can be reimplemented in a subclass to receive drag leave events (passed in event), for the viewport() widget.
Reimplemented from QWidget.
See also QWidget::dragLeaveEvent().
void QAbstractScrollArea::dragMoveEvent ( QDragMoveEvent * event ) [virtual protected]
This event handler can be reimplemented in a subclass to receive drag move events (passed in event), for the viewport() widget.
Reimplemented from QWidget.
See also QWidget::dragMoveEvent().
void QAbstractScrollArea::dropEvent ( QDropEvent * event ) [virtual protected]
This event handler can be reimplemented in a subclass to receive drop events (passed in event), for the viewport() widget.
Reimplemented from QWidget.
See also QWidget::dropEvent().
bool QAbstractScrollArea::event ( QEvent * e ) [virtual protected]
This is the main event handler for the QAbstractScrollArea widget (not the scrolling area viewport()). The event is passed in e.
Reimplemented from QObject.
QScrollBar * QAbstractScrollArea::horizontalScrollBar () const
Returns the horizontal scroll bar.
See also horizontalScrollBarPolicy and verticalScrollBar().
void QAbstractScrollArea::keyPressEvent ( QKeyEvent * e ) [virtual protected]
This function is called with key event e when key presses occur. It handles PageUp, PageDown, Up, Down, Left, and Right, and ignores all other key presses.
Reimplemented from QWidget.
QSize QAbstractScrollArea::maximumViewportSize () const
Returns the size of the viewport as if the scroll bars had no valid scrolling range.
void QAbstractScrollArea::mouseDoubleClickEvent ( QMouseEvent * e ) [virtual protected]
This event handler can be reimplemented in a subclass to receive mouse double click events for the viewport() widget. The event is passed in e.
Reimplemented from QWidget.
See also QWidget::mouseDoubleClickEvent().
void QAbstractScrollArea::mouseMoveEvent ( QMouseEvent * e ) [virtual protected]
This event handler can be reimplemented in a subclass to receive mouse move events for the viewport() widget. The event is passed in e.
Reimplemented from QWidget.
See also QWidget::mouseMoveEvent().
void QAbstractScrollArea::mousePressEvent ( QMouseEvent * e ) [virtual protected]
This event handler can be reimplemented in a subclass to receive mouse press events for the viewport() widget. The event is passed in e.
Reimplemented from QWidget.
See also QWidget::mousePressEvent().
void QAbstractScrollArea::mouseReleaseEvent ( QMouseEvent * e ) [virtual protected]
This event handler can be reimplemented in a subclass to receive mouse release events for the viewport() widget. The event is passed in e.
Reimplemented from QWidget.
See also QWidget::mouseReleaseEvent().
void QAbstractScrollArea::paintEvent ( QPaintEvent * event ) [virtual protected]
This event handler can be reimplemented in a subclass to receive paint events (passed in event), for the viewport() widget.
Note: If you open a painter, make sure to open it on the viewport().
Reimplemented from QWidget.
See also QWidget::paintEvent().
void QAbstractScrollArea::resizeEvent ( QResizeEvent * event ) [virtual protected]
This event handler can be reimplemented in a subclass to receive resize events (passed in event), for the viewport() widget.
When resizeEvent() is called, the viewport already has its new geometry: Its new size is accessible through the QResizeEvent::size() function, and the old size through QResizeEvent::oldSize().
Reimplemented from QWidget.
See also QWidget::resizeEvent().
void QAbstractScrollArea::scrollContentsBy ( int dx, int dy ) [virtual protected]
This virtual handler is called when the scroll bars are moved by dx, dy, and consequently the viewport's contents should be scrolled accordingly.
The default implementation simply calls update() on the entire viewport(), subclasses can reimplement this handler for optimization purposes, or - like QScrollArea - to move a contents widget. The paramters dx and dy 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 calling QScrollBar::setValue() directly).
void QAbstractScrollArea::setViewportMargins ( int left, int top, int right, int bottom ) [protected]
Sets the margins around the scrolling area to left, top, right and bottom. 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.
QScrollBar * QAbstractScrollArea::verticalScrollBar () const
Returns the vertical scroll bar.
See also verticalScrollBarPolicy and horizontalScrollBar().
QWidget * QAbstractScrollArea::viewport () const
Returns the viewport widget.
Use the QScrollBar::widget() function to retrieve the contents of the viewport widget.
See also QScrollArea::widget().
bool QAbstractScrollArea::viewportEvent ( QEvent * e ) [virtual protected]
The main event handler for the scrolling area (the viewport() widget). It handles event e.
You can reimplement this function in a subclass, but we recommend using one of the specialized event handlers instead.
Specialised handlers for viewport events are: paintEvent(), mousePressEvent(), mouseReleaseEvent(), mouseDoubleClickEvent(), mouseMoveEvent(), wheelEvent(), dragEnterEvent(), dragMoveEvent(), dragLeaveEvent(), dropEvent(), contextMenuEvent(), and resizeEvent().
void QAbstractScrollArea::wheelEvent ( QWheelEvent * e ) [virtual protected]
This event handler can be reimplemented in a subclass to receive wheel events for the viewport() widget. The event is passed in e.
Reimplemented from QWidget.
See also QWidget::wheelEvent().
