QFrame Class
QFrame 类是具有边框的小部件的基类。更多内容...
| 头文件： | #include <QFrame> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake： | QT += widgets |
| 继承自： | QWidget |
| 被继承者： | QAbstractScrollArea、QLabel 、QLCDNumber 、QSplitter 、QStackedWidget ，以及QToolBox |
公共类型
| enum | Shadow { Plain, Raised, Sunken } |
| enum | Shape { NoFrame, Box, Panel, StyledPanel, HLine, …, WinPanel } |
| enum | StyleMask { Shadow_Mask, Shape_Mask } |
属性
|
|
公共函数
| QFrame(QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags()) | |
| virtual | ~QFrame() |
| QRect | frameRect() const |
| QFrame::Shadow | frameShadow() const |
| QFrame::Shape | frameShape() const |
| int | frameStyle() const |
| int | frameWidth() const |
| int | lineWidth() const |
| int | midLineWidth() const |
| void | setFrameRect(const QRect &) |
| void | setFrameShadow(QFrame::Shadow) |
| void | setFrameShape(QFrame::Shape) |
| void | setFrameStyle(int style) |
| void | setLineWidth(int) |
| void | setMidLineWidth(int) |
重新实现的公共函数
| virtual QSize | sizeHint() const override |
受保护函数
| virtual void | initStyleOption(QStyleOptionFrame *option) const |
重新实现的受保护函数
| virtual void | changeEvent(QEvent *ev) override |
| virtual bool | event(QEvent *e) override |
| virtual void | paintEvent(QPaintEvent *) override |
详细说明
QMenu 使用此功能可将菜单“凸起”于周围屏幕之上。QProgressBar 采用“内凹”样式。QLabel 采用扁平化样式。此类控件的边框均可进行调整。
QLabel label(...);
label.setFrameStyle(QFrame::Panel | QFrame::Raised);
label.setLineWidth(2);
QProgressBar pbar(...);
label.setFrameStyle(QFrame::NoFrame);QFrame 类也可直接用于创建没有任何内容的简单占位框。
边框样式由frame shape 和shadow style 属性指定，用于在视觉上将边框与周围的控件区分开来。这些属性可通过setFrameStyle()函数同时设置，并通过frameStyle()函数读取。
边框样式包括NoFrame 、Box 、Panel 、StyledPanel 、HLine 和VLine ；阴影样式包括Plain 、Raised 和Sunken 。
框架控件有三个属性用于描述边框的粗细：lineWidth 、midLineWidth 和frameWidth 。
- 线宽是指边框的宽度。可以通过修改该属性来自定义边框的外观。
- 中线宽度指定了框架中间额外一条线的宽度，该线使用第三种颜色以获得特殊的3D效果。请注意，中线仅在Box 、HLine 和VLine 等具有凸起或凹陷效果的框架上绘制。
- 边框宽度由边框样式决定，可通过调用frameWidth() 函数获取所用样式中定义的数值。
可以通过QWidget::setContentsMargins() 函数自定义框架与框架内容之间的间距。
下表展示了一些样式与线宽的组合：
成员类型 文档
enum QFrame::Shadow
此枚举类型定义了用于为帧添加3D效果的阴影类型。
| 常量 | 值 | 描述 |
|---|---|---|
QFrame::Plain | 0x0010 | 框架和内容与周围环境处于同一水平；使用调色板QPalette::WindowText 的颜色进行绘制（无任何 3D 效果） |
QFrame::Raised | 0x0020 | 边框和内容看起来凸起；使用当前颜色组的浅色和深色绘制一条 3D 凸起线 |
QFrame::Sunken | 0x0030 | 边框和内容看起来凹陷；使用当前颜色组的浅色和深色绘制一条三维凹陷线 |
阴影与QFrame::Shape 、lineWidth()以及midLineWidth()相互作用。请参阅主类文档中的边框示意图。
另请参阅 QFrame::Shape 、lineWidth() 和midLineWidth()。
enum QFrame::Shape
此枚举类型定义了可用的帧形状。
| 常量 | 值 | 描述 |
|---|---|---|
QFrame::NoFrame | 0 | QFrame 不绘制任何内容 |
QFrame::Box | 0x0001 | QFrame 在内容周围绘制一个框 |
QFrame::Panel | 0x0002 | QFrame 绘制一个面板，使内容看起来凸起或凹陷 |
QFrame::StyledPanel | 0x0006 | 绘制一个矩形面板，其外观取决于当前的 GUI 样式。该面板可以是凸起的，也可以是凹陷的。 |
QFrame::HLine | 0x0004 | QFrame 绘制一条不包围任何内容的水平线（可用作分隔线） |
QFrame::VLine | 0x0005 | QFrame 绘制一条不包含任何内容的垂直线（可用作分隔符） |
QFrame::WinPanel | 0x0003 | 绘制一个矩形面板，其凸起或凹陷效果与 Windows 2000 中的类似。指定此形状会将线宽设置为 2 像素。WinPanel 是为了兼容性而提供的。为了实现与 GUI 样式的独立性，我们建议改用 StyledPanel。 |
当未调用QStyle 时，Shape会与QFrame::Shadow 、lineWidth()以及midLineWidth()协同工作以生成最终效果。请参阅主类文档中的框架示意图。
另请参阅 QFrame::Shadow 、QFrame::style() 以及QStyle::drawPrimitive()。
enum QFrame::StyleMask
该枚举定义了两个常量，可用于提取frameStyle() 的两个组成部分：
| 常量 | 值 | 描述 |
|---|---|---|
QFrame::Shadow_Mask | 0x00f0 | frameStyle() 中的Shadow 部分 |
QFrame::Shape_Mask | 0x000f | frameStyle() 中的Shape 部分 |
通常情况下，您无需使用这些，因为frameShadow() 和frameShape() 已经从frameStyle() 中提取了Shadow 和Shape 部分。
另请参阅 frameStyle() 和setFrameStyle()。
属性文档
frameRect : QRect
该属性存储了画框的矩形
框架矩形是指绘制框架所使用的矩形区域。默认情况下，该矩形即为整个小部件。设置该矩形不会触发小部件的更新。当小部件大小发生变化时，框架矩形会自动调整。
若将矩形设置为空矩形（例如，QRect(0, 0, 0, 0)），则生成的边框矩形等同于widget rectangle 。
访问函数：
| QRect | frameRect() const |
| void | setFrameRect(const QRect &) |
frameShadow : Shadow
该属性存储来自边框样式的边框阴影值
访问函数：
| QFrame::Shadow | frameShadow() const |
| void | setFrameShadow(QFrame::Shadow) |
另请参阅 frameStyle() 和frameShape()。
frameShape : Shape
该属性保存来自帧样式的帧形状值
访问函数：
| QFrame::Shape | frameShape() const |
| void | setFrameShape(QFrame::Shape) |
另请参阅 frameStyle() 和frameShadow()。
[read-only] frameWidth : int
该属性指定所绘制框架的宽度。
请注意，边框宽度取决于frame style ，而不仅仅是线宽和中线宽度。例如，由NoFrame 指定的样式其边框宽度始终为0，而Panel 指定的样式其边框宽度则等于线宽。
访问函数：
| int | frameWidth() const |
另请参阅 lineWidth()、midLineWidth() 和frameStyle()。
lineWidth : int
此属性控制线条的宽度
请注意，用作分隔符的边框（HLine 和VLine ）的总线宽由frameWidth 指定。
默认值为 1。
访问函数：
| int | lineWidth() const |
| void | setLineWidth(int) |
另请参阅 midLineWidth 和frameWidth 。
midLineWidth : int
该属性用于设置中线的宽度
默认值为 0。
访问函数：
| int | midLineWidth() const |
| void | setMidLineWidth(int) |
另请参阅 lineWidth 和frameWidth 。
成员函数文档
[explicit] QFrame::QFrame(QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags())
创建一个边框样式为NoFrame 、边框宽度为 1 像素的边框控件。
参数parent 和f 将传递给QWidget 构造函数。
[virtual noexcept] QFrame::~QFrame()
销毁该帧。
[override virtual protected] void QFrame::changeEvent(QEvent *ev)
重写了：QWidget::changeEvent(QEvent *event)。
[override virtual protected] bool QFrame::event(QEvent *e)
重写了：QWidget::event(QEvent *event)。
int QFrame::frameStyle() const
返回边框样式。
默认值为QFrame::Plain 。
另请参阅 setFrameStyle()、frameShape() 和frameShadow()。
[virtual protected] void QFrame::initStyleOption(QStyleOptionFrame *option) const
使用来自此链接QFrame 的值初始化option 。当子类需要一个QStyleOptionFrame 却不想自己填写所有信息时，此方法非常有用。
另请参阅 QStyleOption::initFrom()。
[override virtual protected] void QFrame::paintEvent(QPaintEvent *)
重写了：QWidget::paintEvent(QPaintEvent *event)。
void QFrame::setFrameStyle(int style)
将边框样式设置为style 。
style 是边框形状与边框阴影样式之间的按位或运算结果。请参阅主类文档中的边框示意图。
边框形状在QFrame::Shape 中给出，阴影样式在QFrame::Shadow 中给出。
如果指定了大于 0 的中线宽度，则对于Raised 或Sunken 中的Box 、HLine 以及VLine 边框，将绘制一条额外的中线。绘制中线时使用当前颜色组的中间色。
另请参阅 frameStyle()。
[override virtual] QSize QFrame::sizeHint() const
重新实现了属性QWidget::sizeHint 的访问函数。
© 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.
