【QT】QWidget控件详解 || 常用的API

1. 控件概述

控件体系的发展阶段

Qt 提供了多代控件体系：

阶段	控件库	特点
第一代	QWidgets	基于 C++ 的传统 GUI 控件，性能好，适合桌面应用开发
第二代	QML/QtQuick	声明式语言，用于构建动态 UI，适合移动端和动画效果
第三代	Qt Quick Controls 2	QML 扩展控件集，跨平台支持更好

2. QWidget 核心属性

2.1 核心属性概览

属性名	类型	功能
enabled	bool	是否可用
geometry	QRect	控件在父窗口中的位置和大小
windowTitle	QString	窗口标题
windowIcon	QIcon	窗口图标
windowOpacity	qreal (0~1)	窗口透明度
cursor	QCursor	鼠标悬停时显示的光标样式
font	QFont	字体设置
toolTip	QString	鼠标悬停提示
focusPolicy	Qt::FocusPolicy	获取焦点的方式
styleSheet	QString	自定义样式表（QSS）

---

2.2 控件可用性（Enabled）

• API ：

  widget->setEnabled(bool); // 设置是否可用
  bool isEnabled();         // 判断是否可用

• 说明 ：

  • 若为 false，控件变灰且不能响应用户操作。
  • 常用于防止用户误操作或验证输入后启用按钮。

• ---

  2.3 坐标系（Geometry）

  实例 1: 控制按钮的位置

QPushButton *btn = new QPushButton("Click Me", this);
btn->move(100, 50);  // 设置按钮在父窗口中的坐标

实例 2: 表白程序（界面布局）

QPushButton *yesBtn = new QPushButton("我愿意", this);
QPushButton *noBtn = new QPushButton("算了", this);yesBtn->move(100, 100);
noBtn->move(200, 100);

API 说明：

方法	描述
void move(int x, int y)	移动控件到指定坐标
QPoint pos()	获取当前坐标
QRect geometry()	获取几何信息（x, y, width, height）
void setGeometry(int x, int y, int w, int h)	同时设置位置和大小

---

2.4 窗口标题（windowTitle）

this->setWindowTitle("我的第一个 Qt 程序");
QString title = this->windowTitle();

2.5 窗口图标（windowIcon）

this->setWindowIcon(QIcon(":/images/icon.png"));
QIcon icon = this->windowIcon();

路径可使用绝对路径、相对路径或资源系统（.qrc）路径。

2.6 窗口透明度（windowOpacity）

this->setWindowOpacity(0.5); // 50% 透明度
qreal opacity = this->windowOpacity();

2.7 光标属性（cursor）

this->setCursor(Qt::WaitCursor); // 显示等待光标
this->setCursor(QCursor(Qt::CrossCursor)); // 十字光标

常用光标类型：

枚举值	效果
Qt::ArrowCursor	默认箭头
Qt::IBeamCursor	文本输入光标
Qt::WaitCursor	等待光标
Qt::CrossCursor	十字光标
Qt::SizeAllCursor	四向箭头

---

2.8 字体属性（QFont）

QFont font("微软雅黑", 12, QFont::Bold);
font.setItalic(true);
label->setFont(font);

QFont 常用方法：

方法	作用
QFont(QString family, int pointSize, int weight, bool italic)	构造字体
void setFamily(const QString &family)	设置字体家族
void setPointSize(int size)	设置字号
void setBold(bool bold)	设置加粗
void setItalic(bool italic)	设置斜体

---

3. Window Frame 的影响

Geometry 和 FrameGeometry 的区别

方法	返回值	说明
geometry()	包含控件自身区域	不包括窗口边框
frameGeometry()	包括窗口边框	适用于获取整个窗口的大小和位置

qDebug() << "geometry:" << this->geometry();
qDebug() << "frameGeometry:" << this->frameGeometry();

4. API 设计理念

Qt 的 API 设计具有以下特点：

• 面向对象 ：所有控件继承自 QWidget
• 信号与槽机制 ：事件驱动编程
• 一致性命名 ：如 setXXX() / getXXX() / isXXX()
• 模块化设计 ：按功能划分模块（如 QtCore、QtGui、QtWidgets）
• 跨平台兼容性 ：一次编写，到处运行

---

5. 资源管理与路径使用

1. 图片路径的选择

路径类型	示例	说明
绝对路径	"C:/images/icon.png"	不推荐，跨平台问题大
相对路径	"images/icon.png"	推荐，需注意构建路径
qrc 资源路径	":/images/icon.png"	推荐，资源打包进程序

2. 路径类型说明

• 相对路径 ：相对于 .pro 文件所在目录
• 构建目录 ：编译时生成的临时目录，默认为 build-* 开头的文件夹
• 资源路径 ：通过 .qrc 文件统一管理资源

3. 构建目录的作用

• 存放编译过程中产生的中间文件（如 .o、moc_*.cpp）
• 输出最终可执行文件（如 main.exe）
• 构建目录中应包含资源文件（如图片）以便程序运行时访问

---

6. qrc 文件

6.1 qrc 文件的特点

• 使用 XML 格式描述资源
• 将资源嵌入到应用程序中
• 支持多种资源类型：图片、文本、二进制文件等
• 编译后自动转为 C++ 代码（qrc_*.cpp）

6.2 通过 qrc 管理图片作为图标

步骤：

1. 创建 resources.qrc 文件
2. 添加资源路径和文件：

<RCC><qresource prefix="/images"><file>icon.png</file></qresource>
</RCC>

1. 在项目 .pro 中添加：

RESOURCES += resources.qrc

1. 使用资源：

QIcon(":/images/icon.png");

7. 其他常用属性

7.1 ToolTip 设置

button->setToolTip("点击发送表白信息");
鼠标悬停时显示提示信息。 

7.2 Focus Policy 设置

button->setFocusPolicy(Qt::StrongFocus); // 支持键盘聚焦

常见枚举值：

枚举值	说明
Qt::NoFocus	不接受焦点
Qt::TabFocus	仅通过 Tab 键获得焦点
Qt::ClickFocus	点击获得焦点
Qt::StrongFocus	支持 Tab 和 Click 聚焦

---

7.3 Style Sheet (QSS)

QSS 是 Qt 的 CSS 式样式表系统，用于美化控件。

示例：

button->setStyleSheet("QPushButton { background-color: red; color: white; border-radius: 5px; }");

常用选择器：

选择器	说明
QPushButton	所有 QPushButton
QPushButton#myButton	ID 为 myButton 的按钮
QPushButton:hover	鼠标悬停时
QPushButton:pressed	按下时状态

---

✅ 总结：重要 API 汇总表

功能	API 方法
设置控件可用性	setEnabled(bool)
设置控件位置	move(x, y)
设置窗口标题	setWindowTitle()
设置窗口图标	setWindowIcon()
设置窗口透明度	setWindowOpacity()
设置光标样式	setCursor(QCursor)
设置字体	setFont(QFont)
获取窗口几何信息	geometry(), frameGeometry()
设置工具提示	setToolTip()
设置焦点策略	setFocusPolicy(Qt::FocusPolicy)
设置样式表	setStyleSheet(QString)
使用资源路径	":/images/icon.png"