就业培训     下载中心     Wiki     联络 登录   注册
  1. 首页
  2. Qt 6.2.1
  3. Qt Widgets
  4. C++ 类
  5. QAbstractScrollArea

内容

QAbstractScrollArea 类

QAbstractScrollArea 小部件提供带按需滚动条的卷动区域。 更多...

头： #include <QAbstractScrollArea>
CMake: find_package(Qt6 COMPONENTS Widgets REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
继承： QFrame
继承者： QAbstractItemView , QGraphicsView , QMdiArea , QPlainTextEdit , QScrollArea ，和 QTextEdit

公共类型

enum SizeAdjustPolicy { AdjustIgnored, AdjustToContents, AdjustToContentsOnFirstShow }

特性

公共函数

  QAbstractScrollArea (QWidget * parent = nullptr)
virtual ~QAbstractScrollArea ()
void addScrollBarWidget (QWidget * widget , Qt::Alignment alignment )
QWidget * cornerWidget () const
QScrollBar * horizontalScrollBar () const
Qt::ScrollBarPolicy horizontalScrollBarPolicy () const
QSize maximumViewportSize () const
QWidgetList scrollBarWidgets (Qt::Alignment alignment )
void setCornerWidget (QWidget * widget )
void setHorizontalScrollBar (QScrollBar * scrollBar )
void setHorizontalScrollBarPolicy (Qt::ScrollBarPolicy)
void setSizeAdjustPolicy (QAbstractScrollArea::SizeAdjustPolicy policy )
void setVerticalScrollBar (QScrollBar * scrollBar )
void setVerticalScrollBarPolicy (Qt::ScrollBarPolicy)
void setViewport (QWidget * widget )
virtual void setupViewport (QWidget * viewport )
QAbstractScrollArea::SizeAdjustPolicy sizeAdjustPolicy () const
QScrollBar * verticalScrollBar () const
Qt::ScrollBarPolicy verticalScrollBarPolicy () const
QWidget * viewport () const

重实现公共函数

virtual QSize minimumSizeHint () const override
virtual QSize sizeHint () const override

保护函数

virtual void scrollContentsBy (int dx , int dy )
void setViewportMargins (int left , int top , int right , int bottom )
void setViewportMargins (const QMargins & margins )
virtual bool viewportEvent (QEvent * event )
QMargins viewportMargins () const
virtual QSize viewportSizeHint () const

重实现保护函数

virtual void contextMenuEvent (QContextMenuEvent * e ) override
virtual void dragEnterEvent (QDragEnterEvent * event ) override
virtual void dragLeaveEvent (QDragLeaveEvent * event ) override
virtual void dragMoveEvent (QDragMoveEvent * event ) override
virtual void dropEvent (QDropEvent * event ) override
virtual bool event (QEvent * event ) override
virtual void keyPressEvent (QKeyEvent * e ) override
virtual void mouseDoubleClickEvent (QMouseEvent * e ) override
virtual void mouseMoveEvent (QMouseEvent * e ) override
virtual void mousePressEvent (QMouseEvent * e ) override
virtual void mouseReleaseEvent (QMouseEvent * e ) override
virtual void paintEvent (QPaintEvent * event ) override
virtual void resizeEvent (QResizeEvent * event ) override
virtual void wheelEvent (QWheelEvent * e ) override

详细描述

QAbstractScrollArea 是卷动区域的低级抽象。区域提供称为视口的中心 Widget，在其中卷动区域内容 (即：内容可见部分在视口渲染)。

视口旁边是垂直滚动条，和下方是水平滚动条。当所有区域内容拟合视口时，各滚动条可以是可见的 (或被隐藏) 从属滚动条的 Qt::ScrollBarPolicy 。当滚动条隐藏时，视口展开以覆盖所有可用空间。当滚动条再次变为可见时，视口收缩为滚动条腾出空间。

在视口周围预留边距区域是可能的，见 setViewportMargins ()。特征主要用于放置 QHeaderView 小部件在滚动区域上方或旁边。QAbstractScrollArea 子类应该实现边距。

当继承 QAbstractScrollArea 时，需要做以下：

  • 控制滚动条通过设置其范围、值、页面步长和跟踪其移动。
  • 绘制视口区域内容根据滚动条值。
  • 处理接收事件通过视口在 viewportEvent () - 显而易见的是重置大小事件。
  • 使用 viewport->update() 更新视口内容而不是 update() 因为所有描绘操作都发生在视口中。

采用滚动条策略 Qt::ScrollBarAsNeeded (默认)，QAbstractScrollArea 展示滚动条当提供非 0 卷动范围时，否则隐藏它们。

应该更新滚动条和视口，每当视口收到重置大小事件或内容大小变化时。还需更新视口当滚动条值改变时。经常设置滚动条初始值当区域收到新内容时。

简单范例，实现的卷动区域可以卷动任何 QWidget 。使 Widget 成为视口子级；这样，不必计算要绘制 Widget 的哪部分，而只需移动小部件采用 QWidget::move ()。当区域内容或视口大小变化时，做以下： 

    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();

当滚动条值变化时，需要更新 Widget 位置 (即：在视口中找到要绘制的小部件部分)： 

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

为跟踪滚动条移动，重实现虚函数 scrollContentsBy ()。为微调卷动行为，连接到滚动条的 QAbstractSlider::actionTriggered () 信号和调节 QAbstractSlider::sliderPosition 如希望。

为方便起见，QAbstractScrollArea 使所有视口事件可用于虚拟 viewportEvent () 处理程序。 QWidget 的专用处理程序会被重映射到视口事件，在这种情况下，这是有意义的。重映射的专用处理程序是： paintEvent (), mousePressEvent (), mouseReleaseEvent (), mouseDoubleClickEvent (), mouseMoveEvent (), wheelEvent (), dragEnterEvent (), dragMoveEvent (), dragLeaveEvent (), dropEvent (), contextMenuEvent ()，和 resizeEvent ().

QScrollArea 继承 QAbstractScrollArea，提供平滑卷动为任何 QWidget (即：Widget 逐像素卷动)。只需子类化 QAbstractScrollArea 若需要更专用行为。这为 true，例如整个区域的内容不适于绘制在 QWidget 或者若不想要平滑卷动。

另请参阅 QScrollArea .

成员类型文档编制

[since 5.2] enum QAbstractScrollArea:: SizeAdjustPolicy

此枚举指定大小提示如何 QAbstractScrollArea 调节当视口大小变化时。

常量 值 描述
QAbstractScrollArea::AdjustIgnored 0 卷动区域行为像之前 - 和不做任何调节。
QAbstractScrollArea::AdjustToContents 2 卷动区域将始终调整到视口
QAbstractScrollArea::AdjustToContentsOnFirstShow 1 卷动区域将在首次展示时调节到其视口。

该枚举在 Qt 5.2 引入或被修改。

特性文档编制

horizontalScrollBarPolicy : Qt::ScrollBarPolicy

此特性保持水平滚动条的策略

默认策略为 Qt::ScrollBarAsNeeded .

访问函数：

Qt::ScrollBarPolicy horizontalScrollBarPolicy () const
void setHorizontalScrollBarPolicy (Qt::ScrollBarPolicy)

另请参阅 verticalScrollBarPolicy .

[since 5.2] sizeAdjustPolicy : SizeAdjustPolicy

此特性保持卷动区域大小如何变化的描述策略，当视口大小变化时。

默认策略为 QAbstractScrollArea::AdjustIgnored 。改变此特性可能实际重置滚动区域大小。

该特性在 Qt 5.2 引入。

访问函数：

QAbstractScrollArea::SizeAdjustPolicy sizeAdjustPolicy () const
void setSizeAdjustPolicy (QAbstractScrollArea::SizeAdjustPolicy policy )

verticalScrollBarPolicy : Qt::ScrollBarPolicy

此特性保持垂直滚动条的策略

默认策略为 Qt::ScrollBarAsNeeded .

访问函数：

Qt::ScrollBarPolicy verticalScrollBarPolicy () const
void setVerticalScrollBarPolicy (Qt::ScrollBarPolicy)

另请参阅 horizontalScrollBarPolicy .

成员函数文档编制

QAbstractScrollArea:: QAbstractScrollArea ( QWidget * parent = nullptr)

构造视口。

parent 自变量被发送给 QWidget 构造函数。

[虚拟] QAbstractScrollArea:: ~QAbstractScrollArea ()

销毁视口。

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

添加 widget 作为滚动条 Widget 在指定位置按 alignment .

滚动条 Widget 紧邻水平滚动条 (或垂直滚动条) 展示，且可以放置在其任一侧。若想要滚动条 Widget 始终可见，将相应滚动条的 scrollBarPolicy 设为 AlwaysOn .

alignment 必须是某一 Qt::Alignleft 和 Qt::AlignRight ，映射到水平滚动条，或 Qt::AlignTop and Qt::AlignBottom ，映射到垂直滚动条。

通过重新父级小部件可以移除滚动条 Widget 或删除它。也是可能的隐藏小部件采用 QWidget::hide ()

滚动条 Widget 将重置大小以拟合当前样式的滚动条几何体。以下描述在水平滚动条中的滚动条 Widget 情况：

Widget 的高度设为匹配滚动条的高度。要控制 Widget 的宽度，使用 QWidget::setMinimumWidth and QWidget::setMaximumWidth ，或实现 QWidget::sizeHint () 和设置水平尺寸策略。若想要方形 Widget，调用 QStyle::pixelMetric ( QStyle::PM_ScrollBarExtent ) 并将宽度设为此值。

另请参阅 scrollBarWidgets ().

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

重实现： QWidget::contextMenuEvent (QContextMenuEvent *event).

可以在子类中重实现此事件处理程序，以接收上下文菜单事件对于 viewport () 小部件。事件被传入 e .

另请参阅 QWidget::contextMenuEvent ().

QWidget *QAbstractScrollArea:: cornerWidget () const

返回 2 滚动条之间的角落 Widget。

默认情况下，不存在角落 Widget。

另请参阅 setCornerWidget ().

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

重实现： QWidget::dragEnterEvent (QDragEnterEvent *event).

可在子类中重实现此事件处理程序以接收拖拽进入事件 (传入 event )，对于 viewport () 小部件。

另请参阅 QWidget::dragEnterEvent ().

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

重实现： QWidget::dragLeaveEvent (QDragLeaveEvent *event).

可在子类中重实现此事件处理程序以接收拖拽离开事件 (传入 event )，对于 viewport () 小部件。

另请参阅 QWidget::dragLeaveEvent ().

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

重实现： QWidget::dragMoveEvent (QDragMoveEvent *event).

可在子类中重实现此事件处理程序以接收拖拽移动事件 (传入 event )，对于 viewport () 小部件。

另请参阅 QWidget::dragMoveEvent ().

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

重实现： QWidget::dropEvent (QDropEvent *event).

可以在子类中重实现此事件处理程序以接收掉落事件 (传入 event )，对于 viewport () 小部件。

另请参阅 QWidget::dropEvent ().

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

重实现： QFrame::event (QEvent *e).

这是主事件处理程序对于 QAbstractScrollArea 小部件 ( not 卷动区域 viewport ())。指定 event 是可能需要根据其类型被铸造成适当类的一般事件对象。

另请参阅 QEvent::type ().

QScrollBar *QAbstractScrollArea:: horizontalScrollBar () const

返回水平滚动条。

另请参阅 setHorizontalScrollBar (), horizontalScrollBarPolicy ，和 verticalScrollBar ().

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

重实现： QWidget::keyPressEvent (QKeyEvent *event).

此函数被调用采用键事件 e 当发生键按下时。它处理 PageUp、PageDown、向上、向下、向左和向右，并忽略所有其它键按下。

QSize QAbstractScrollArea:: maximumViewportSize () const

返回视口大小，就像滚动条没有有效卷动范围。

[override virtual] QSize QAbstractScrollArea:: minimumSizeHint () const

重实现访问函数为特性： QWidget::minimumSizeHint .

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

重实现： QWidget::mouseDoubleClickEvent (QMouseEvent *event).

可以在子类中重实现此事件处理程序以接收鼠标双击事件对于 viewport () 小部件。事件被传入 e .

另请参阅 QWidget::mouseDoubleClickEvent ().

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

重实现： QWidget::mouseMoveEvent (QMouseEvent *event).

可以在子类中重实现此事件处理程序以接收鼠标移动事件对于 viewport () 小部件。事件被传入 e .

另请参阅 QWidget::mouseMoveEvent ().

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

重实现： QWidget::mousePressEvent (QMouseEvent *event).

可以在子类中重实现此事件处理程序以接收鼠标按下事件对于 viewport () 小部件。事件被传入 e .

默认实现调用 QWidget::mousePressEvent () 为默认弹出处理。

另请参阅 QWidget::mousePressEvent ().

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

重实现： QWidget::mouseReleaseEvent (QMouseEvent *event).

可以在子类中重实现此事件处理程序以接收鼠标释放事件对于 viewport () 小部件。事件被传入 e .

另请参阅 QWidget::mouseReleaseEvent ().

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

重实现： QFrame::paintEvent (QPaintEvent *).

可以在子类中重实现此事件处理程序以接收描绘事件 (传入 event )，对于 viewport () 小部件。

注意： 若打开描绘器，确保打开它是在 viewport ().

另请参阅 QWidget::paintEvent ().

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

重实现： QWidget::resizeEvent (QResizeEvent *event).

可以在子类中重实现此事件处理程序以接收重置大小事件 (传入 event )，对于 viewport () 小部件。

当调用 resizeEvent() 时，视口已经拥有新的几何体：可以访问它的新尺寸透过 QResizeEvent::size () 函数，和旧尺寸透过 QResizeEvent::oldSize ().

另请参阅 QWidget::resizeEvent ().

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

返回目前设置的滚动条 Widget 列表。 alignment 可以是 4 个位置标志的任意组合。

另请参阅 addScrollBarWidget ().

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

调用此虚拟处理程序当滚动条被移动按 dx , dy ，因此，应相应卷动视口内容。

默认实现只需调用 update () 在整个 viewport ()，子类可以为优化目的重实现此处理程序，或者 - 像 QScrollArea - 移动内容 Widget。参数 dx and dy 是为了方便，以便类知道应该卷动多少 (这很有用，如做像素偏移时)。还可以忽略这些值，并直接卷动到滚动条指示位置。

调用此函数以编程方式卷动是错误的，用滚动条代替 (如，通过调用 QScrollBar::setValue () 直接)。

void QAbstractScrollArea:: setCornerWidget ( QWidget * widget )

将 2 滚动条之间的角落 Widget 设为 widget .

您可能还想将至少一滚动条模式设为 AlwaysOn .

传递 nullptr 不展示角落 Widget。

隐藏先前的任何角落 Widget。

可以调用 SetCornerWidget() 在不同时间采用相同 Widget。

在此设置的所有 Widget 都会被卷动区域删除当销毁卷动区域时，除非在设置某些其它角落 Widget 后单独重设 Widget 父级 (或 nullptr ).

任何 newly 设置的 Widget 不应拥有当前父级。

默认情况下，不存在角落 Widget。

另请参阅 cornerWidget (), horizontalScrollBarPolicy ，和 horizontalScrollBarPolicy .

void QAbstractScrollArea:: setHorizontalScrollBar ( QScrollBar * scrollBar )

替换现有水平滚动条采用 scrollBar ，并在新滚动条中设置之前滚动条的所有滑块特性。然后删除之前的滚动条。

QAbstractScrollArea 默认情况下，已提供水平滚动条和垂直滚动条。可以调用此函数将默认水平滚动条替换为自己的自定义滚动条。

另请参阅 horizontalScrollBar () 和 setVerticalScrollBar ().

void QAbstractScrollArea:: setVerticalScrollBar ( QScrollBar * scrollBar )

替换现有垂直滚动条采用 scrollBar ，并在新滚动条中设置之前滚动条的所有滑块特性。然后删除之前的滚动条。

QAbstractScrollArea 默认情况下，已提供垂直滚动条和水平滚动条。可以调用此函数将默认垂直滚动条替换为自己的自定义滚动条。

另请参阅 verticalScrollBar () 和 setHorizontalScrollBar ().

void QAbstractScrollArea:: setViewport ( QWidget * widget )

将视口设为给定 widget 。 QAbstractScrollArea 将拥有所有权对于给定 widget .

若 widget is nullptr , QAbstractScrollArea 将赋值新的 QWidget 实例为视口。

另请参阅 viewport ().

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

将卷动区域周围边距设为 left , top , right and bottom 。这对应用程序 (譬如：具有 "锁定" 行和列的电子表格) 很有用。边缘空间留白；将 Widget 放入未使用区域。

注意，此函数经常被频繁调用由 QTreeView and QTableView ，因此边距的实现必须通过 QAbstractScrollArea 子类。此外，若要在项视图中使用子类，它们不应调用此函数。

默认情况下，所有边距为 0。

另请参阅 viewportMargins ().

[protected] void QAbstractScrollArea:: setViewportMargins (const QMargins & margins )

设置 margins 围绕卷动区域。这对于 (具有如锁定行和列的电子表格) 应用程序很有用。边缘空间留白；将 Widget 放在未使用区域。

默认情况下，所有边距为 0。

另请参阅 viewportMargins ().

[虚拟] void QAbstractScrollArea:: setupViewport ( QWidget * viewport )

此槽被调用通过 QAbstractScrollArea after setViewport ( viewport ) 被调用。重实现此函数在子类化的 QAbstractScrollArea 以初始化新的 viewport 在使用它之前。

另请参阅 setViewport ().

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

重实现： QFrame::sizeHint () const.

返回卷动区域 sizeHint 特性。大小的确定通过使用 viewportSizeHint () 加一些额外滚动条空间，若需要。

QScrollBar *QAbstractScrollArea:: verticalScrollBar () const

返回垂直滚动条。

另请参阅 setVerticalScrollBar (), verticalScrollBarPolicy ，和 horizontalScrollBar ().

QWidget *QAbstractScrollArea:: viewport () const

返回视口 Widget。

使用 QScrollArea::widget () 函数检索视口 Widget 内容。

另请参阅 setViewport () 和 QScrollArea::widget ().

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

用于卷动区域的主要事件处理程序 ( viewport () 小部件)。它处理 event 指定，且可以被子类调用以提供合理默认行为。

返回 true 指示事件系统已处理该事件，不需要进一步处理；否则返回 false 指示应进一步传播该事件。

可以在子类中重实现此函数，但推荐使用某一专用事件处理程序代替。

专用视口事件处理程序是： paintEvent (), mousePressEvent (), mouseReleaseEvent (), mouseDoubleClickEvent (), mouseMoveEvent (), wheelEvent (), dragEnterEvent (), dragMoveEvent (), dragLeaveEvent (), dropEvent (), contextMenuEvent ()，和 resizeEvent ().

[protected, since 5.5] QMargins QAbstractScrollArea:: viewportMargins () const

返回在卷动区域周围的边距。默认情况下，所有边距为 0。

该函数在 Qt 5.5 引入。

另请参阅 setViewportMargins ().

[virtual protected, since 5.2] QSize QAbstractScrollArea:: viewportSizeHint () const

返回推荐视口大小。默认实现返回 viewport ()-> sizeHint ()。注意，大小仅仅是视口大小，不包括任何可见滚动条。

该函数在 Qt 5.2 引入。

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

重实现： QWidget::wheelEvent (QWheelEvent *event).

可以在子类中重实现此事件处理程序以接收滚轮事件对于 viewport () 小部件。事件被传入 e .

另请参阅 QWidget::wheelEvent ().