QC++ / Qt 学习之路

常用基础控件

认识十一个基础控件并写一个综合示例串联它们

入门第 21 / 48 章第三篇 · Qt 入门

#控件的三要素

Qt Widgets 提供了上百个控件,但它们的用法高度一致。拿到任何一个陌生控件,你只需要查三件事:

  1. 常用属性(property):如 text、enabled、visible、value,通过 setXxx() / xxx() 读写。
  2. 常用信号(signal):用户交互时发出什么,你该 connect 哪个。
  3. 常用槽(slot):你可以主动调用它做什么,如 clear()、setValue()。

这和你学 HTML 元素的方式很像——<input> 有 value 属性、onchange 事件、focus() 方法。区别在于 Qt 的控件是 C++ 对象,属性是类型安全的成员函数而不是字符串。

另外一个重要概念:所有控件都继承自 QWidget,因此拥有共同的"基础能力",学会一次即可通吃:

C++
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) 后标题栏出现复选框,勾选状态会自动启用/禁用内部所有子控件,非常适合"高级选项"区域。

#控件速查表

控件关键属性关键信号常用槽/方法
QLabeltext, pixmap, alignment, wordWraplinkActivatedsetText, setPixmap, setBuddy
QPushButtontext, icon, checkable, defaultclicked(bool), pressed, released, toggled(bool)click(), setIcon, setShortcut
QLineEdittext, placeholderText, echoMode, maxLengthtextChanged, textEdited, returnPressed, editingFinishedsetText, clear, setValidator
QTextEditplainText, html, readOnly, lineWrapModetextChanged(无参), cursorPositionChangedappend, setPlainText, clear, undo
QComboBoxcurrentIndex, currentText, currentData, editablecurrentIndexChanged(int), currentTextChangedaddItem, addItems, clear, setCurrentIndex
QCheckBoxtext, checked, tristatecheckStateChanged, clicked(bool), toggledsetChecked, setCheckState
QRadioButtontext, checked(组内自动互斥)toggled(bool), clickedsetChecked, isChecked
QSpinBoxvalue, range, suffix, prefix, singleStepvalueChanged(int), textChangedsetValue, setRange, setSuffix
QSlidervalue, minimum, maximum, orientation, trackingvalueChanged, sliderMoved, sliderReleasedsetValue, setRange
QProgressBarvalue, minimum, maximum, format, textVisiblevalueChangedsetValue, reset, setRange(0,0)=忙碌
QGroupBoxtitle, checkable, checked, flatclicked(bool), toggledsetTitle, 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) 之外的一些旧重载,遇到编译错误时检查信号是否带参数。

#综合示例:个人信息表单

下面把控件串起来,做成一个有实际交互的小程序。它演示了:输入 → 校验 → 更新显示、控件联动、进度反馈。

C++
// 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
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 章布局所有权)。

#几个实用技巧

下面这段代码集中演示了对话框、禁用与隐藏、以及校验器的用法,可以直接贴进示例窗口的槽函数里试验:

C++
// 确认对话框:同步返回用户选择(内部启动嵌套事件循环)
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 做提示与确认。

#练习

  1. 在综合示例基础上,增加"学历"四个 QRadioButton(与性别分开互斥),并在结果里输出所选学历;用 QButtonGroup 的 id 或 checkedButton() 实现。
  2. 把"满意度"滑块改成"忙碌模式"进度条演示:加一个按钮,点击后进度条 setRange(0,0) 显示动画,2 秒后(QTimer::singleShot)恢复并显示完成。
  3. 用 QRegularExpressionValidator 给姓名输入框加校验(例如只允许中英文与空格,长度 2–20),并在输入非法时把输入框边框变红(提示:setStyleSheet("QLineEdit{border:1px solid red;}") 或 QPalette)。
  4. 对照本章速查表,任选两个未在示例中出现的 Qt 控件(如 QDateEdit、QDial、QLCDNumber),查文档写出它们的三要素,并加进示例窗口中。
我的学习笔记笔记总览
笔记保存在本机浏览器(localStorage),换设备或清理缓存会丢失;重要内容请点「导出全部笔记」存成 .md 文件。