QGraphicsView 类

成员函数文档

QGraphicsView::QGraphicsView(QWidget *parent = nullptr)

构建一个 QGraphicsView。 parent 传递给 QWidget 的构造函数。

QGraphicsView::QGraphicsView(QGraphicsScene *scene, QWidget *parent = nullptr)

构建一个 QGraphicsView 并将可视化的场景设置为 scene。 parent 传递给 QWidget 的构造函数。

[虚拟 noexcept] QGraphicsView::~QGraphicsView()

销毁 QGraphicsView 对象。

void QGraphicsView::centerOn(const QPointF &pos)

将视口内容滚动以确保场景坐标 pos 在视图中居中。

由于 pos 是一个浮点坐标，而滚动条操作整数坐标，居中只是一个近似值。

另请参阅 ensureVisible。

void QGraphicsView::centerOn(qreal x, qreal y)

这是一个重载函数。

此函数提供方便。它等效于调用 centerOn(QPointF(x, y))。

void QGraphicsView::centerOn(const QGraphicsItem *item)

这是一个重载函数。

将视口内容滚动以确保 item 在视图中居中。

另请参阅 ensureVisible。

[覆盖虚拟受保护] void QGraphicsView::contextMenuEvent(QContextMenuEvent *event)

重实现：QAbstractScrollArea::contextMenuEvent(QContextMenuEvent *e)。

[覆盖虚拟受保护] void QGraphicsView::dragEnterEvent(QDragEnterEvent *event)

重实现：QAbstractScrollArea::dragEnterEvent(QDragEnterEvent *event)。

[重写虚保护] void QGraphicsView::dragLeaveEvent(QDragLeaveEvent *event)

重新实现: QAbstractScrollArea::dragLeaveEvent(QDragLeaveEvent *event).

[重写虚保护] void QGraphicsView::dragMoveEvent(QDragMoveEvent *event)

重新实现: QAbstractScrollArea::dragMoveEvent(QDragMoveEvent *event).

[虚保护] void QGraphicsView::drawBackground(QPainter *painter, const QRectF &rect)

使用 painter 绘制场景的背景，在绘制任何项目和前景之前。重新实现此函数以为此视图提供自定义背景。

如果只是想要定义背景的颜色、纹理或渐变，可以调用 setBackgroundBrush() 代替。

所有绘制均在 场景 坐标系中进行。rect 是暴露的矩形。

默认实现使用视图的 backgroundBrush 填充 rect。如果没有定义此类画笔（默认），则调用场景的 drawBackground() 函数。

另请参阅drawForeground() 和 QGraphicsScene::drawBackground().

[虚保护] void QGraphicsView::drawForeground(QPainter *painter, const QRectF &rect)

使用 painter 绘制场景的前景，在绘制背景和所有项之后。重新实现此函数以为此视图提供自定义前景。

如果只是想要定义前景的颜色、纹理或渐变，可以调用 setForegroundBrush() 代替。

所有绘制均在 场景 坐标系中进行。rect 是暴露的矩形。

默认实现使用视图的 foregroundBrush 填充 rect。如果没有定义此类画笔（默认），则调用场景的 drawForeground() 函数。

另请参阅drawBackground() 和 QGraphicsScene::drawForeground().

[重写虚保护] void QGraphicsView::dropEvent(QDropEvent *event)

重新实现: QAbstractScrollArea::dropEvent(QDropEvent *event).

void QGraphicsView::ensureVisible(const QRectF &rect, int xmargin = 50, int ymargin = 50)

将视口的内容滚动，以便将场景矩形 rect 显示出来，其中 xmargin 和 ymargin 以像素为单位指定了边距。如果指定的矩形无法到达，内容将滚动到最近的合法位置。默认边距值均为 50 像素。

另请参阅centerOn().

void QGraphicsView::ensureVisible(qreal x, qreal y, qreal w, qreal h, int xmargin = 50, int ymargin = 50)

这是一个重载函数。

此函数提供便利。它等价于调用ensureVisible(QRectF(x, y, w, h), xmargin, ymargin)。

void QGraphicsView::ensureVisible(const QGraphicsItem *item, int xmargin = 50, int ymargin = 50)

这是一个重载函数。

将视口的内容滚动，以便项目中点中心可见，xmargin 和 ymargin 指定以像素为单位的边距。如果无法达到指定的点，窗口内容将滚动到最近的合法位置。两个边距的默认值均为 50 像素。

另请参阅centerOn().

[覆盖虚拟保护] bool QGraphicsView::event(QEvent *event)

重新实现: QAbstractScrollArea::event(QEvent *event)。

void QGraphicsView::fitInView(const QRectF &rect, Qt::AspectRatioMode aspectRatioMode = Qt::IgnoreAspectRatio)

缩放视图矩阵并滚动滚动条，以确保场景矩形 rect 落在视口中。 rect 必须位于场景矩形内；否则，fitInView() 不能保证整个 rect 都可见。

此函数保持视图的旋转、平移或倾斜。视图按 aspectRatioMode 缩放。如果 rect 不贴合，则会在视图中居中对齐。

通常在重新实现resizeEvent()内部调用fitInView()，以确保整个场景或场景的某些部分作为视图缩放时自动缩放到视图的新大小。但请注意，如果在resizeEvent()内部调用fitInView()，则可能会引起不希望的重缩放递归，如果新的变换切换了滚动条的自动状态。可以将滚动条策略切换到始终开启或始终关闭，以避免这种情况（请参阅horizontalScrollBarPolicy() 和 verticalScrollBarPolicy）。

如果 rect 为空或视口过小，则此函数不执行任何操作。

另请参阅setTransform()，ensureVisible() 和 centerOn()。

void QGraphicsView::fitInView(qreal x, qreal y, qreal w, qreal h, Qt::AspectRatioMode aspectRatioMode = Qt::IgnoreAspectRatio)

这是一个重载函数。

此便利函数等价于调用fitInView(QRectF(x, y, w, h), aspectRatioMode)。

另请参阅 ensureVisible() 和 centerOn().

void QGraphicsView::fitInView(const QGraphicsItem *item, Qt::AspectRatioMode aspectRatioMode = Qt::IgnoreAspectRatio)

这是一个重载函数。

确保 item 在视图中紧密地对应，并根据 aspectRatioMode 进行缩放。

另请参阅 ensureVisible() 和 centerOn().

[override virtual protected] void QGraphicsView::focusInEvent(QFocusEvent *event)

重实：QWidget::focusInEvent(QFocusEvent *event).

[override virtual protected] bool QGraphicsView::focusNextPrevChild(bool next)

重实：QWidget::focusNextPrevChild(bool next).

[override virtual protected] void QGraphicsView::focusOutEvent(QFocusEvent *event)

重实：QWidget::focusOutEvent(QFocusEvent *event).

[override virtual protected] void QGraphicsView::inputMethodEvent(QInputMethodEvent *event)

重实：QWidget::inputMethodEvent(QInputMethodEvent *event).

[override virtual] QVariant QGraphicsView::inputMethodQuery(Qt::InputMethodQuery query) const

重实：QWidget::inputMethodQuery(Qt::InputMethodQuery query) const.

[slot] void QGraphicsView::invalidateScene(const QRectF &rect = QRectF(), QGraphicsScene::SceneLayers layers = QGraphicsScene::AllLayers)

使 layers 在 rect 内无效并安排重新绘制。 rect 是在场景坐标中的。对 rect 内的 layers 内的任何缓存内容无条件地使无效并重新绘制。

您可以通过调用此函数来通知 QGraphicsView 场景的背景或前景发生了变化。它通常用于具有基于瓦片的背景的场景，当 QGraphicsView 启用背景缓存时通知变化。

注意，目前 QGraphicsView 只支持背景缓存（请参阅 QGraphicsView::CacheBackground）。如果传入了所有层以外的任何层，此函数等同于调用 update()。

另请参阅 QGraphicsScene::invalidate() 和 update()。

bool QGraphicsView::isTransformed() const

如果视图中已应用了转换（即被分配了非单位转换，或已调整滚动条），则返回 true。

另请参阅 setTransform()，horizontalScrollBar() 和 verticalScrollBar().

QGraphicsItem *QGraphicsView::itemAt(const QPoint &pos) const

返回位置 pos 的项，该位置在视图坐标系中。如果有多个项在该位置，此函数返回最顶部的项。

示例

void CustomView::mousePressEvent(QMouseEvent *event)
{
    if (QGraphicsItem *item = itemAt(event->pos())) {
        qDebug() << "You clicked on item" << item;
    } else {
        qDebug("You didn't click on an item.");
    }
}

请参阅 items() 和 排序。

QGraphicsItem *QGraphicsView::itemAt(int x, int y) const

这是一个重载函数。

此函数提供方便。相当于调用 itemAt(QPoint(x, y))。

QList<QGraphicsItem *> QGraphicsView::items() const

返回与关联场景中所有项的列表，按降序堆叠顺序（即返回列表中的第一个项是最顶部的项）。

请参阅 QGraphicsScene::items() 和 排序。

QList<QGraphicsItem *> QGraphicsView::items(const QPoint &pos) const

返回在视图中位置 pos 的所有项的列表。这些项按降序堆叠顺序列出（即列表中的第一个项是最顶部的项，最后一个项是最底部的项）。pos 在视口坐标系中。

此函数通常从在 QGraphicsView 的子类中处理的鼠标事件处理程序内部调用。pos 在未变换的视口坐标系中，就像 QMouseEvent::pos()。

void CustomView::mousePressEvent(QMouseEvent *event)
{
    qDebug() << "There are" << items(event->pos()).size()
             << "items at position" << mapToScene(event->pos());
}

请参阅 QGraphicsScene::items() 和 排序。

QList<QGraphicsItem *> QGraphicsView::items(int x, int y) const

此函数提供方便。相当于调用 items(QPoint(x, y))。

QList<QGraphicsItem *> QGraphicsView::items(const QRect &rect, Qt::ItemSelectionMode mode = Qt::IntersectsItemShape) const

这是一个重载函数。

根据 mode，返回包含或与 rect 相交的所有项的列表。rect 在视口坐标系中。

mode 的默认值是 Qt::IntersectsItemShape；返回所有与或包含 rect 的形状相交的项。

这些项按降序堆叠顺序排序（即返回列表中的第一个项是最顶部的项）。

请参阅 itemAt()，items()，mapToScene()，以及 排序。

QList<QGraphicsItem *> QGraphicsView::items(int x, int y, int w, int h, Qt::ItemSelectionMode mode = Qt::IntersectsItemShape) const

此便捷函数等价于调用 items(QRectF(x, y, w, h), mode)。

QList<QGraphicsItem *> QGraphicsView::items(const QPolygon &polygon, Qt::ItemSelectionMode mode = Qt::IntersectsItemShape) const

这是一个重载函数。

返回一个项目列表，这些项目根据 mode 的设置，可能包含或与 polygon 交叉。 polygon 以视口坐标表示。

mode 的默认值是 Qt::IntersectsItemShape；所有与 polygon 精确形状相交或包含 polygon 的项目均返回。

项目按降序堆叠顺序进行排序（即，返回列表中的第一个项目是最上面的项目）。

请参阅 itemAt()，items()，mapToScene()，以及 排序。

QList<QGraphicsItem *> QGraphicsView::items(const QPainterPath &path, Qt::ItemSelectionMode mode = Qt::IntersectsItemShape) const

这是一个重载函数。

返回一个项目列表，这些项目根据 mode 的设置，可能包含或与 path 交叉。 path 以视口坐标表示。

mode 的默认值是 Qt::IntersectsItemShape；所有与 path 精确形状相交或包含 path 的项目均返回。

请参阅 itemAt()，items()，mapToScene()，以及 排序。

[覆盖虚保护] void QGraphicsView::keyPressEvent(QKeyEvent *event)

重实现: QAbstractScrollArea::keyPressEvent(QKeyEvent *e)。

[覆盖虚保护] void QGraphicsView::keyReleaseEvent(QKeyEvent *event)

重实现: QWidget::keyReleaseEvent(QKeyEvent *event)。

QPoint QGraphicsView::mapFromScene(const QPointF &point) const

将场景坐标 point 转换为视口坐标。

另请参阅mapToScene。

QPolygon QGraphicsView::mapFromScene(const QRectF &rect) const

将场景矩形 rect 转换为一个视口坐标多边形。

另请参阅mapToScene。

QPolygon QGraphicsView::mapFromScene(const QPolygonF &polygon) const

将场景坐标多边形 polygon 转换为一个视口坐标多边形。

另请参阅mapToScene。

QPainterPath QGraphicsView::mapFromScene(const QPainterPath &path) const

返回场景坐标画家路径（path）到视口坐标画家路径。

另请参阅mapToScene。

QPoint QGraphicsView::mapFromScene(qreal x, qreal y) const

此函数提供方便。它与调用 mapFromScene(QPointF(x, y))) 等价。

QPolygon QGraphicsView::mapFromScene(qreal x, qreal y, qreal w, qreal h) const

此函数提供方便。它与调用 mapFromScene(QRectF(x, y, w, h))) 等价。

QPointF QGraphicsView::mapToScene(const QPoint &point) const

返回被映射到场景坐标的点（point）的视口坐标。

注意：将点（point）所在的像素覆盖的整个矩形映射到场景坐标可能很有用，而不是点本身。为此，您可以调用 mapToScene(QRect(point, QSize(2, 2))))。

另请参阅mapFromScene。

QPolygonF QGraphicsView::mapToScene(const QRect &rect) const

返回被映射到场景坐标多边形的视口矩形（rect）。

另请参阅mapFromScene。

QPolygonF QGraphicsView::mapToScene(const QPolygon &polygon) const

返回被映射到场景坐标多边形的视口多边形（polygon）。

另请参阅mapFromScene。

QPainterPath QGraphicsView::mapToScene(const QPainterPath &path) const

返回被映射到场景坐标画家路径的视口画家路径（path）。

另请参阅mapFromScene。

QPointF QGraphicsView::mapToScene(int x, int y) const

此函数提供方便。它与调用 mapToScene(QPoint(x, y))) 等价。

QPolygonF QGraphicsView::mapToScene(int x, int y, int w, int h) const

此函数提供方便。它与调用 mapToScene(QRect(x, y, w, h))) 等价。

[重写虚受保护] void QGraphicsView::mouseDoubleClickEvent(QMouseEvent *event)

重新实现： QAbstractScrollArea::mouseDoubleClickEvent(QMouseEvent *e)

[覆盖虚受保护] void QGraphicsView::mouseMoveEvent(QMouseEvent *event)

重新实现： QAbstractScrollArea::mouseMoveEvent(QMouseEvent *e)

[覆盖虚受保护] void QGraphicsView::mousePressEvent(QMouseEvent *event)

重新实现： QAbstractScrollArea::mousePressEvent(QMouseEvent *e)

[覆盖虚受保护] void QGraphicsView::mouseReleaseEvent(QMouseEvent *event)

重新实现： QAbstractScrollArea::mouseReleaseEvent(QMouseEvent *e)

[覆盖虚受保护] void QGraphicsView::paintEvent(QPaintEvent *event)

重新实现： QAbstractScrollArea::paintEvent(QPaintEvent *event)

void QGraphicsView::render(QPainter *painter, const QRectF &target = QRectF(), const QRect &source = QRect(), Qt::AspectRatioMode aspectRatioMode = Qt::KeepAspectRatio)

将场景中的源矩形（以视图坐标表示）渲染到目标矩形，该目标矩形以绘图设备坐标表示，使用painter。此函数对于将视图的内容捕获到绘图设备，例如 QImage（例如，进行屏幕截图），或用于打印到 QPrinter 非常有用。例如：

QGraphicsScene scene;
scene.addItem(...
...

QGraphicsView view(&scene);
view.show();
...

QPrinter printer(QPrinter::HighResolution);
printer.setPageSize(QPrinter::A4);
QPainter painter(&printer);

// print, fitting the viewport contents into a full page
view.render(&painter);

// print the upper half of the viewport into the lower.
// half of the page.
QRect viewport = view.viewport()->rect();
view.render(&painter,
            QRectF(0, printer.height() / 2,
                   printer.width(), printer.height() / 2),
            viewport.adjusted(0, 0, 0, -viewport.height() / 2));

如果 source 是空矩形，则此函数将使用 viewport()->rect() 来确定要绘制的内容。如果 target 是空矩形，则将使用 painter 的绘图设备全尺寸（例如，对于 QPrinter，页大小）。

将根据aspectRatioMode将源矩形内容进行转换，以适应目标矩形。默认情况下，保持宽高比，并将source 缩放以适应target。

另请参阅QGraphicsScene::render。

void QGraphicsView::resetCachedContent()

重置任何缓存内容。调用此函数将清除 QGraphicsView 的缓存。如果当前缓存模式是 CacheNone，则此函数不执行任何操作。

当 backgroundBrush 或 QGraphicsScene::backgroundBrush 属性改变时，会自动为您调用此函数；只有当您已重新实现了 QGraphicsScene::drawBackground() 或 QGraphicsView::drawBackground() 以绘制自定义背景，并且需要触发完整重绘时，才需要调用此函数。

另请参阅cacheMode。

void QGraphicsView::resetTransform()

将视图转换重置为单位矩阵。

另请参阅transform() 和 setTransform().

[重载虚保护] void QGraphicsView::resizeEvent(QResizeEvent *event)

重新实现: QAbstractScrollArea::resizeEvent(QResizeEvent *event).

void QGraphicsView::rotate(qreal angle)

按顺时针方向旋转当前视图转换 angle 度。

另请参阅setTransform(), transform(), scale(), shear(), 和 translate().

[信号] void QGraphicsView::rubberBandChanged(QRect rubberBandRect, QPointF fromScenePoint, QPointF toScenePoint)

当橡皮筋矩形发生变化时，会发出此信号。视口矩形由 rubberBandRect 指定。拖动开始位置和拖动结束位置通过 fromScenePoint 和 toScenePoint 提供的场景点提供。

当橡皮筋选择结束时，此信号将使用空值发出。

另请参阅rubberBandRect().

QRect QGraphicsView::rubberBandRect() const

当用户正在使用橡皮筋进行项选择时，此函数将返回当前橡皮筋区域（在视口坐标中）。当用户不使用橡皮筋时，此函数返回（一个空）QRectF()。

请注意，此 QRect 的部分可能位于可视视口之外。例如，它可以包含负值。

另请参阅rubberBandSelectionMode 和 rubberBandChanged().

void QGraphicsView::scale(qreal sx, qreal sy)

按 (sx, sy) 缩放当前视图转换。

另请参阅setTransform(), transform(), rotate(), shear(), 和 translate().

QGraphicsScene *QGraphicsView::scene() const

返回指向在视图中可视化场景的指针。如果没有场景正在可视化中，返回 nullptr。

另请参阅setScene().

[重载虚保护] void QGraphicsView::scrollContentsBy(int dx, int dy)

重新实现：QAbstractScrollArea::scrollContentsBy(int dx, int dy).

void QGraphicsView::setOptimizationFlag(QGraphicsView::OptimizationFlag flag, bool enabled = true)

如果 enabled 为真，则启用 flag；否则禁用 flag。

另请参阅 optimizationFlags.

void QGraphicsView::setRenderHint(QPainter::RenderHint hint, bool enabled = true)

如果 enabled 为真，则启用渲染提示 hint；否则禁用 hint。

另请参阅 renderHints.

void QGraphicsView::setScene(QGraphicsScene *scene)

将当前场景设置为 scene。如果 scene 已被查看，则此函数不会执行任何操作。

当在一个视图中设置场景时，QGraphicsScene::changed() 信号将自动连接到此视图的 updateScene() 插槽，并且视图的滚动条将调整以适应场景的大小。

视图不拥有 scene 的所有权。

另请参阅 scene。

void QGraphicsView::setTransform(const QTransform &matrix, bool combine = false)

将视图当前变换矩阵设置为 matrix。

如果 combine 为真，那么 matrix 将与当前矩阵结合；否则，matrix 将替换当前矩阵。默认情况下，combine 为假。

变换矩阵将场景转换为视图坐标。使用默认的变换（单位矩阵提供），视图中的一个像素代表场景中的一个单位（例如，一个 10x10 的矩形项目在视图中使用 10x10 像素绘制）。如果应用了 2x2 的缩放矩阵，则场景将以 1:2 的比例绘制（例如，一个 10x10 的矩形项目将使用 20x20 个像素在视图中绘制）。

示例

QGraphicsScene scene;
scene.addText("GraphicsView rotated clockwise");

QGraphicsView view(&scene);
view.rotate(90); // the text is rendered with a 90 degree clockwise rotation
view.show();

为了简化与变换视图中的项目交互，QGraphicsView 提供了 mapTo... 和 mapFrom... 函数，可以将场景和视图坐标之间进行转换。例如，您可以调用 mapToScene() 将视图坐标映射为一个浮点场景坐标，或者调用 mapFromScene() 将浮点场景坐标映射到视图坐标。

另请参阅 transform(), resetTransform(), rotate(), scale(), shear() 和 translate().

[重载虚保护槽] void QGraphicsView::setupViewport(QWidget *widget)

重载：QAbstractScrollArea::setupViewport(QWidget *viewport).

该槽在调用QAbstractScrollArea后由setViewport()调用。在QGraphicsView的子类中重新实现此函数，以便在之前使用之前初始化新的视图窗口。

另请参阅 setViewport().

void QGraphicsView::shear(qreal sh, qreal sv)

通过( sh, sv )剪切当前视图变换。

另请参阅 setTransform(), transform(), rotate(), scale() 和 translate().

[重写虚保护] void QGraphicsView::showEvent(QShowEvent *event)

重写: QWidget::showEvent(QShowEvent *event).

[重写虚] QSize QGraphicsView::sizeHint() const

重写: QAbstractScrollArea::sizeHint() const.

QTransform QGraphicsView::transform() const

返回视图当前变换矩阵。如果没有设置当前变换，返回单位矩阵。

另请参阅 setTransform(), rotate(), scale(), shear() 和 translate().

void QGraphicsView::translate(qreal dx, qreal dy)

通过( dx, dy )转换当前视图变换。

另请参阅 setTransformtransformrotate() 和 shear().

[插槽] void QGraphicsView::updateScene(const QList<QRectF> &rects)

计划更新场景矩形 rects。

另请参阅 QGraphicsScene::changed().

[插槽] void QGraphicsView::updateSceneRect(const QRectF &rect)

通知 QGraphicsView 场景的视图矩形已改变。 rect 是新的视图矩形。如果视图已经设置了一个显式的视图矩形，则此函数不执行任何操作。

另请参阅 sceneRect 和 QGraphicsScene::sceneRectChanged().

[重写虚保护] bool QGraphicsView::viewportEvent(QEvent *event)

重写: QAbstractScrollArea::viewportEvent(QEvent *event).

QTransform QGraphicsView::viewportTransform() const

返回一个将场景坐标映射到视口坐标的矩阵。

另请参阅 mapToScene() 和 mapFromScene().

[覆盖 虚拟 受保护的] void QGraphicsView::wheelEvent(QWheelEvent *事件)

重新实现了：QAbstractScrollArea::wheelEvent(QWheelEvent *e).