Back to Qt.io
Contact Us Blog Download Qt
本页内容

QRubberBand Class

QRubberBand 类提供了一个矩形或直线，可用于指示选区或边界。更多内容...

头文件： #include <QRubberBand>
CMake： find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake： QT += widgets
继承自： QWidget

公共类型

enum Shape { Line, Rectangle }

公共函数

QRubberBand(QRubberBand::Shape s, QWidget *p = nullptr)
virtual ~QRubberBand()
void move(int x, int y)
void move(const QPoint &p)
void resize(int width, int height)
void resize(const QSize &size)
void setGeometry(const QRect &rect)
void setGeometry(int x, int y, int width, int height)
QRubberBand::Shape shape() const

受保护函数

virtual void initStyleOption(QStyleOptionRubberBand *option) const

重新实现的受保护函数

virtual void changeEvent(QEvent *e) override
virtual bool event(QEvent *e) override
virtual void moveEvent(QMoveEvent *) override
virtual void paintEvent(QPaintEvent *) override
virtual void resizeEvent(QResizeEvent *) override
virtual void showEvent(QShowEvent *e) override

详细说明

橡皮筋常用于显示新的边界区域（例如正在解绑的QSplitter 或QDockWidget ）。历史上，这通常通过QPainter 和异或（XOR）来实现，但这种方法并不总能正常工作，因为渲染可能会发生在橡皮筋下方的窗口中，而此时橡皮筋尚未被“擦除”。

每当需要围绕特定区域（或表示单条直线）渲染橡皮筋时，您可以创建一个 QRubberBand，然后调用setGeometry()、move() 或resize() 来调整其位置和大小。一种常见的模式是将其与鼠标事件结合使用。例如：

void Widget::mousePressEvent(QMouseEvent *event)
{
    origin = event->pos();
    if (!rubberBand)
        rubberBand = new QRubberBand(QRubberBand::Rectangle, this);
    rubberBand->setGeometry(QRect(origin, QSize()));
    rubberBand->show();
}

void Widget::mouseMoveEvent(QMouseEvent *event)
{
    rubberBand->setGeometry(QRect(origin, event->pos()).normalized());
}

void Widget::mouseReleaseEvent(QMouseEvent *event)
{
    rubberBand->hide();
    // determine selection, for example using QRect::intersects()
    // and QRect::contains().
}

如果在 QRubberBand 的构造函数中传入父控件，橡皮筋将仅在其父控件内部显示，但仍位于其他子控件之上。如果未传入父控件，QRubberBand 将作为顶级控件运行。

调用show()可使弹性带可见；当弹性带不是顶级控件时，也需调用此方法。隐藏或销毁该控件将导致弹性带消失。弹性带可以是Rectangle 或Line （垂直或水平），具体取决于构造时传入的shape()参数。

成员类型文档

enum QRubberBand::Shape

此枚举指定了QRubberBand 应采用的形状。这是一个绘制提示，会传递给样式系统，并可由各个QStyle 进行解析。

常量值描述
QRubberBand::Line0QRubberBand 可以表示一条垂直线或水平线。几何形状仍通过rect() 指定，在大多数样式中，该线将填充给定的几何形状。
QRubberBand::Rectangle1QRubberBand 可以表示一条垂直或水平线。某些样式会将其解释为一个填充的（通常是半透明的）矩形，或者一个矩形轮廓。

成员函数文档

[explicit] QRubberBand::QRubberBand(QRubberBand::Shape s, QWidget *p = nullptr)

创建一个形状为s 的橡皮筋，其父对象为p 。

默认情况下，矩形橡皮筋（s 即Rectangle ）会使用蒙版，因此仅显示矩形的一小部分边框。某些样式（例如原生 macOS）会更改此行为，并调用QWidget::setWindowOpacity() 来生成一个半透明的实心选区矩形。

[virtual noexcept] QRubberBand::~QRubberBand()

析构函数。

[override virtual protected] void QRubberBand::changeEvent(QEvent *e)

重写了：QWidget::changeEvent(QEvent *event)。

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

重写了：QWidget::event(QEvent *event)。

[virtual protected] void QRubberBand::initStyleOption(QStyleOptionRubberBand *option) const

使用QRubberBand 中的值初始化option 。当子类需要QStyleOptionRubberBand ，但又不希望自己填写所有信息时，此方法非常有用。

另请参阅 QStyleOption::initFrom()。

void QRubberBand::move(int x, int y)

将橡皮筋移动到指定位置（x ，y ）。

另请参阅 resize()。

void QRubberBand::move(const QPoint &p)

将橡皮筋移动到坐标p 处。

这是一个重载函数。

另请参阅 resize()。

[override virtual protected] void QRubberBand::moveEvent(QMoveEvent *)

重写了：QWidget::moveEvent(QMoveEvent *event)。

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

重写了：QWidget::paintEvent(QPaintEvent *event)。

void QRubberBand::resize(int width, int height)

调整橡皮筋的大小，使其宽度为width ，高度为height 。

另请参阅 move()。

void QRubberBand::resize(const QSize &size)

调整橡皮筋的大小，使其新尺寸为size 。

这是一个重载函数。

另请参阅 move()。

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

重写了：QWidget::resizeEvent(QResizeEvent *event)。

void QRubberBand::setGeometry(const QRect &rect)

将橡皮筋的几何属性设置为rect ，该值以父控件的坐标系为基准。

另请参阅 QWidget::geometry 。

void QRubberBand::setGeometry(int x, int y, int width, int height)

将橡皮筋的几何形状设置为一个矩形，其左上角位于点 (x,y)，尺寸由width 和height 指定。该几何形状在父控件的坐标系中定义。

这是一个重载函数。

QRubberBand::Shape QRubberBand::shape() const

返回此橡皮筋的形状。该形状只能在创建时设置。

[override virtual protected] void QRubberBand::showEvent(QShowEvent *e)

重写了：QWidget::showEvent(QShowEvent *event)。

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.