常用基础控件
认识十一个基础控件并写一个综合示例串联它们
#控件的三要素
Qt Widgets 提供了上百个控件,但它们的用法高度一致。拿到任何一个陌生控件,你只需要查三件事:
- 常用属性(property):如
text、enabled、visible、value,通过setXxx()/xxx()读写。 - 常用信号(signal):用户交互时发出什么,你该
connect哪个。 - 常用槽(slot):你可以主动调用它做什么,如
clear()、setValue()。
这和你学 HTML 元素的方式很像——<input> 有 value 属性、onchange 事件、focus() 方法。区别在于 Qt 的控件是 C++ 对象,属性是类型安全的成员函数而不是字符串。
另外一个重要概念:所有控件都继承自 QWidget,因此拥有共同的"基础能力",学会一次即可通吃:
QWidget *w = anyWidget;
w->setEnabled(false); // 变灰且不可交互
w->setVisible(true); // 显示/隐藏(等价于 show/hide)
w->setToolTip(tr("鼠标悬停时会显示这行字")); // 悬停提示
w->setStyleSheet("color: red; font-weight: bold;"); // 类 CSS 的外观定制
w->setFocus(); // 抢焦点
qDebug() << w->isEnabled() << w->isVisible(); // 布尔 getter 用 is 前缀对比:Java Swing 里组件继承自
JComponent,Python Tkinter 里控件的配置靠widget.config(text=...)或字典下标widget["text"](字符串键,拼错不报错)。Qt 的setText()是编译期检查的普通成员函数,既安全又能被 IDE 自动补全——这是静态语言的优势。
#逐个认识
#QLabel —— 标签
显示文本或图片,不可编辑。它是唯一能通过 setBuddy() 给别的控件提供助记符(mnemonic) 的控件:QLabel *l = new QLabel("&姓名") 配合 l->setBuddy(lineEdit),用户按 Alt+姓 就能跳到输入框。
#QPushButton —— 按钮
最常用的交互控件。setCheckable(true) 可把它变成"开关按钮"(按下保持,再按弹起,配合 toggled(bool) 信号);setDefault(true) 设为对话框默认按钮(回车触发);setAutoDefault、setIcon()、setShortcut(QKeySequence("Ctrl+S")) 也常用。
#QLineEdit —— 单行输入框
text() / setText() 读写内容,setPlaceholderText() 灰字提示,setEchoMode(QLineEdit::Password) 变密码框,setValidator() 限制输入(配合 QIntValidator / QRegularExpressionValidator),setClearButtonEnabled(true) 显示一键清空的小叉。
信号有两个要分清:textChanged(const QString &) 是任何改动(包括代码设置)都触发;textEdited(const QString &) 只在用户编辑时触发。想监听"用户输入"通常用后者,避免程序回写时死循环。
#QTextEdit —— 多行富文本编辑器
toPlainText() / setPlainText() 处理纯文本,toHtml() / setHtml() 处理富文本,append() 追加一行。它是完整的编辑器(支持撤销、粘贴图片),若只需要只读的多行文本展示或纯文本编辑,用轻量级的 QPlainTextEdit 更好(它专为代码编辑器设计,性能高得多)。
两者的 textChanged() 信号没有参数(因为文本量大,传值代价高),需要内容时调用 toPlainText()。
#QComboBox —— 下拉框
addItem(text, userData) 添加项,第二个参数是 QVariant 类型的附加数据(常见于"显示名称、存 ID");currentIndex() 当前序号(-1 表示未选),currentData() 取出附加数据,currentText() 取显示文本。setEditable(true) 允许用户输入。
信号必须用 currentIndexChanged(int) 而非 activated(int) 吗?不,取决于场景:currentIndexChanged 在代码设置也算,而 activated 只在你不想要代码触发时用。Qt 6 中 currentTextChanged(const QString &) 通常最顺手。
#QCheckBox —— 复选框
三态支持:setTristate(true) 后 checkState() 返回 Qt::Checked / Unchecked / PartiallyChecked(半选,常见于"全选"逻辑)。信号用 checkStateChanged(Qt::CheckState)(Qt 6)或 stateChanged(int)(Qt 5/6 通用)。
#QRadioButton —— 单选按钮
同在一个父容器内的 QRadioButton 自动互斥,不需要额外设置。若要把它们分成多组(比如"性别"一组、"学历"一组),用 QButtonGroup(它是逻辑分组,不是界面容器)。
#QSpinBox / QDoubleSpinBox —— 数字微调框
setRange(min,max)、setSuffix(" 元")、setPrefix("¥")、setSingleStep(5)。信号 valueChanged(int)(Qt 6 有重载版本带 QString 后缀文本)。
#QSlider —— 滑块
setRange、setOrientation(Qt::Horizontal)、setTickPosition(QSlider::TicksBelow)。信号 valueChanged(int);拖动过程中的实时值用 sliderMoved(int),松手时用 sliderReleased()。
#QProgressBar —— 进度条
setRange(0,100)、setValue(50)。若把 range 设为 (0, 0),进度条进入"忙碌(busy)模式",显示来回滚动的动画,用于"不知道要多久"的场景。setFormat("%p%") 可自定义显示文本。
#QGroupBox —— 分组框
带标题和边框的容器,常配合布局使用。setCheckable(true) 后标题栏出现复选框,勾选状态会自动启用/禁用内部所有子控件,非常适合"高级选项"区域。
#控件速查表
| 控件 | 关键属性 | 关键信号 | 常用槽/方法 |
|---|---|---|---|
| QLabel | text, pixmap, alignment, wordWrap | linkActivated | setText, setPixmap, setBuddy |
| QPushButton | text, icon, checkable, default | clicked(bool), pressed, released, toggled(bool) | click(), setIcon, setShortcut |
| QLineEdit | text, placeholderText, echoMode, maxLength | textChanged, textEdited, returnPressed, editingFinished | setText, clear, setValidator |
| QTextEdit | plainText, html, readOnly, lineWrapMode | textChanged(无参), cursorPositionChanged | append, setPlainText, clear, undo |
| QComboBox | currentIndex, currentText, currentData, editable | currentIndexChanged(int), currentTextChanged | addItem, addItems, clear, setCurrentIndex |
| QCheckBox | text, checked, tristate | checkStateChanged, clicked(bool), toggled | setChecked, setCheckState |
| QRadioButton | text, checked(组内自动互斥) | toggled(bool), clicked | setChecked, isChecked |
| QSpinBox | value, range, suffix, prefix, singleStep | valueChanged(int), textChanged | setValue, setRange, setSuffix |
| QSlider | value, minimum, maximum, orientation, tracking | valueChanged, sliderMoved, sliderReleased | setValue, setRange |
| QProgressBar | value, minimum, maximum, format, textVisible | valueChanged | setValue, reset, setRange(0,0)=忙碌 |
| QGroupBox | title, checkable, checked, flat | clicked(bool), toggled | setTitle, setChecked |
| QWidget(通用) | enabled, visible, toolTip, styleSheet, sizePolicy | — | setEnabled, setToolTip, setFocus, setStyleSheet |
Qt 5 提示:
QCheckBox的stateChanged(int)在 Qt 6 依然可用,但 Qt 6 新增了类型更安全的checkStateChanged(Qt::CheckState),新代码优先用后者。另外 Qt 6 移除了QComboBox::currentTextChanged(QString)之外的一些旧重载,遇到编译错误时检查信号是否带参数。
#综合示例:个人信息表单
下面把控件串起来,做成一个有实际交互的小程序。它演示了:输入 → 校验 → 更新显示、控件联动、进度反馈。
// main.cpp
#include <QApplication>
#include <QWidget>
#include <QLabel>
#include <QLineEdit>
#include <QPushButton>
#include <QComboBox>
#include <QCheckBox>
#include <QRadioButton>
#include <QButtonGroup>
#include <QSpinBox>
#include <QSlider>
#include <QProgressBar>
#include <QGroupBox>
#include <QTextEdit>
#include <QHBoxLayout>
#include <QVBoxLayout>
#include <QFormLayout>
#include <QMessageBox>
#include <QDebug>
class FormWindow : public QWidget
{
public:
explicit FormWindow(QWidget *parent = nullptr) : QWidget(parent)
{
setWindowTitle(tr("个人信息登记"));
// ---- 基本信息区 ----
m_nameEdit = new QLineEdit;
m_nameEdit->setPlaceholderText(tr("请输入姓名"));
m_nameEdit->setClearButtonEnabled(true);
m_cityCombo = new QComboBox;
m_cityCombo->addItem(tr("北京"), "BJ");
m_cityCombo->addItem(tr("上海"), "SH");
m_cityCombo->addItem(tr("广州"), "GZ");
m_ageSpin = new QSpinBox;
m_ageSpin->setRange(0, 150);
m_ageSpin->setSuffix(tr(" 岁"));
m_ageSpin->setValue(18);
auto *basicGroup = new QGroupBox(tr("基本信息"));
auto *form = new QFormLayout(basicGroup);
form->addRow(tr("姓名:"), m_nameEdit);
form->addRow(tr("城市:"), m_cityCombo);
form->addRow(tr("年龄:"), m_ageSpin);
// ---- 选项区 ----
m_male = new QRadioButton(tr("男"));
m_female = new QRadioButton(tr("女"));
m_male->setChecked(true);
auto *genderGroup = new QButtonGroup(this); // 逻辑分组,非界面
genderGroup->addButton(m_male, 1);
genderGroup->addButton(m_female, 2);
m_agree = new QCheckBox(tr("我已阅读并同意条款"));
m_agree->setTristate(false);
auto *optLayout = new QHBoxLayout;
optLayout->addWidget(m_male);
optLayout->addWidget(m_female);
optLayout->addStretch();
optLayout->addWidget(m_agree);
// ---- 满意度滑块 + 进度条 ----
m_slider = new QSlider(Qt::Horizontal);
m_slider->setRange(0, 100);
m_slider->setValue(60);
m_progress = new QProgressBar;
m_progress->setRange(0, 100);
m_percentLabel = new QLabel(tr("60%"));
auto *scoreLayout = new QHBoxLayout;
scoreLayout->addWidget(new QLabel(tr("满意度:")));
scoreLayout->addWidget(m_slider);
scoreLayout->addWidget(m_percentLabel);
// ---- 结果区 ----
m_result = new QTextEdit;
m_result->setReadOnly(true);
m_result->setPlaceholderText(tr("点击“提交”后显示结果"));
m_submit = new QPushButton(tr("提交"));
m_submit->setDefault(true);
// ---- 总布局(第 7 章详述)----
auto *main = new QVBoxLayout(this);
main->addWidget(basicGroup);
main->addLayout(optLayout);
main->addLayout(scoreLayout);
main->addWidget(m_progress);
main->addWidget(m_result);
main->addWidget(m_submit);
// ---- 信号槽连接 ----
connect(m_slider, &QSlider::valueChanged, this, [this](int v) {
m_percentLabel->setText(QString("%1%").arg(v));
m_progress->setValue(v);
});
connect(m_nameEdit, &QLineEdit::textEdited, this, [this](const QString &t) {
m_submit->setEnabled(!t.trimmed().isEmpty() && m_agree->isChecked());
});
connect(m_agree, &QCheckBox::checkStateChanged, this, [this](Qt::CheckState) {
m_submit->setEnabled(!m_nameEdit->text().trimmed().isEmpty()
&& m_agree->isChecked());
});
connect(m_submit, &QPushButton::clicked, this, &FormWindow::onSubmit);
}
private slots:
void onSubmit()
{
const QString name = m_nameEdit->text().trimmed();
if (name.isEmpty()) {
QMessageBox::warning(this, tr("提示"), tr("姓名不能为空"));
return;
}
const QString gender = m_male->isChecked() ? tr("男") : tr("女");
const QString code = m_cityCombo->currentData().toString();
m_result->setPlainText(
tr("姓名:%1\n性别:%2\n城市:%3(代码 %4)\n年龄:%5\n满意度:%6%")
.arg(name)
.arg(gender)
.arg(m_cityCombo->currentText(), code)
.arg(m_ageSpin->value())
.arg(m_slider->value()));
qDebug() << "提交数据:" << name << gender << code << m_ageSpin->value();
}
private:
QLineEdit *m_nameEdit;
QComboBox *m_cityCombo;
QSpinBox *m_ageSpin;
QRadioButton *m_male;
QRadioButton *m_female;
QCheckBox *m_agree;
QSlider *m_slider;
QLabel *m_percentLabel;
QProgressBar *m_progress;
QTextEdit *m_result;
QPushButton *m_submit;
};
int main(int argc, char *argv[])
{
QApplication app(argc, argv);
FormWindow w;
w.resize(420, 480);
w.show();
return app.exec();
}配套的 CMakeLists.txt(与第 1 章模板相同,仅改目标名):
cmake_minimum_required(VERSION 3.16)
project(WidgetDemo LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTOUIC ON)
set(CMAKE_AUTORCC ON)
find_package(Qt6 REQUIRED COMPONENTS Core Gui Widgets)
add_executable(WidgetDemo main.cpp)
target_link_libraries(WidgetDemo PRIVATE Qt6::Core Qt6::Gui Qt6::Widgets)注意这个类里用了 private slots: 声明 onSubmit——加上 slots 标签只是为了表明意图(也便于将来用字符串连接方式),用函数指针 connect 时它其实可以是普通成员函数。另外所有控件都是 new 出来并传了 this 或在布局中被接管,因此无需手动释放(第 4 章对象树 + 第 7 章布局所有权)。
#几个实用技巧
下面这段代码集中演示了对话框、禁用与隐藏、以及校验器的用法,可以直接贴进示例窗口的槽函数里试验:
// 确认对话框:同步返回用户选择(内部启动嵌套事件循环)
if (QMessageBox::question(this, tr("确认"), tr("确定提交?"))
== QMessageBox::Yes) {
qDebug() << "用户点了是";
}
// 禁用 vs 隐藏:前者变灰不可点,后者完全消失且布局重排
m_submit->setEnabled(false);
m_result->setVisible(false);
// 只读而非禁用:用户仍能选中并复制文本
m_result->setReadOnly(true);
// 输入校验:只允许中英文与空格
m_nameEdit->setValidator(new QRegularExpressionValidator(
QRegularExpression("^[\\u4e00-\\u9fa5 A-Za-z]{2,20}$"), m_nameEdit));
// 非法输入时把边框变红
m_nameEdit->setStyleSheet("QLineEdit{border:1px solid red;}");其余要点:
QMessageBox是现成的对话框:information()/warning()/critical()/question()(返回QMessageBox::Yes或No)。它内部会启动一个嵌套事件循环,因此question()是同步返回用户选择的,写法像input()一样自然。- 禁用 vs 隐藏:
setEnabled(false)变灰不可点,setVisible(false)完全消失(布局会重排),setHidden(true)等价。 - 只读 ≠ 禁用:展示结果用
setReadOnly(true)而不是setEnabled(false),后者会让用户无法选中复制文本。 - 助记符与快捷键:文本里的
&会把后一个字母变成Alt+字母快捷键(&Name→Alt+N)。要显示字面的&需写成&&。
#小结
- 掌握任何控件只需查三件事:属性(setXxx/getXxx)、信号(connect 什么)、槽(主动调用什么)。
- 区分
textChanged(含代码改动)与textEdited(仅用户输入);区分currentIndexChanged(含代码改动)与activated(仅用户操作)。 QProgressBar的setRange(0,0)进入忙碌动画;QSlider的sliderMoved是拖动实时值、valueChanged是最终值。QGroupBox的checkable能一键启停整组控件;QButtonGroup是纯逻辑分组,用于多组单选互斥。- 控件创建后交给布局管理,不要手动
delete;用QMessageBox做提示与确认。
#练习
- 在综合示例基础上,增加"学历"四个
QRadioButton(与性别分开互斥),并在结果里输出所选学历;用QButtonGroup的id或checkedButton()实现。 - 把"满意度"滑块改成"忙碌模式"进度条演示:加一个按钮,点击后进度条
setRange(0,0)显示动画,2 秒后(QTimer::singleShot)恢复并显示完成。 - 用
QRegularExpressionValidator给姓名输入框加校验(例如只允许中英文与空格,长度 2–20),并在输入非法时把输入框边框变红(提示:setStyleSheet("QLineEdit{border:1px solid red;}")或QPalette)。 - 对照本章速查表,任选两个未在示例中出现的 Qt 控件(如
QDateEdit、QDial、QLCDNumber),查文档写出它们的三要素,并加进示例窗口中。