QWidget 深入详解

#include <QApplication>
#include <QWidget>

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    QWidget w;
    w.setWindowTitle("Hello QWidget");
    w.resize(400, 300);
    w.show();

    return app.exec();
}

// MyWidget.h
#pragma once
#include <QWidget>
#include <QPainter>

class MyWidget : public QWidget
{
    Q_OBJECT  // 启用信号槽、元对象特性
public:
    explicit MyWidget(QWidget *parent = nullptr);

protected:
    void paintEvent(QPaintEvent *event) override;
    void mousePressEvent(QMouseEvent *event) override;
};

// MyWidget.cpp
#include "MyWidget.h"
#include <QPainter>

MyWidget::MyWidget(QWidget *parent)
    : QWidget(parent)
{
    setMinimumSize(200, 150);
}

void MyWidget::paintEvent(QPaintEvent *)
{
    QPainter painter(this);
    painter.setRenderHint(QPainter::Antialiasing);
    painter.setBrush(QColor(100, 150, 255));
    painter.drawRoundedRect(rect().adjusted(5, 5, -5, -5), 10, 10);
}

void MyWidget::mousePressEvent(QMouseEvent *event)
{
    // 点击时改变颜色
    Q_UNUSED(event);
    update();
}

QWidget *parent = new QWidget();
QWidget *child  = new QWidget(parent);  // child 成为 parent 的子控件

// 常见窗口标志
w.setWindowFlags(Qt::Dialog);                // 对话框类型
w.setWindowFlags(Qt::WindowStaysOnTopHint);   // 置顶
w.setWindowFlags(Qt::FramelessWindowHint);    // 无边框
w.setWindowFlags(Qt::Tool);                   // 工具窗口
w.setWindowFlags(Qt::Popup);                  // 弹出式

w.showMinimized();          // 最小化
w.showMaximized();          // 最大化
w.showFullScreen();         // 全屏
w.showNormal();             // 恢复正常
w.setWindowState(Qt::WindowFullScreen);  // 同上，但不会触发动画

w.setWindowOpacity(0.7);    // 0.0(完全透明) ~ 1.0(不透明)
w.setAttribute(Qt::WA_TranslucentBackground);  // 支持透明背景（配合 paintEvent）

w.setEnabled(false);    // 禁用整个控件（灰显，不响应事件）
w.setVisible(true);     // 显示
w.hide();               // 隐藏（等价于 setVisible(false)）

// 子控件坐标 → 父控件坐标
QPoint globalPt = child->mapToParent(QPoint(0, 0));

// 子控件坐标 → 屏幕坐标
QPoint screenPt = child->mapToGlobal(QPoint(0, 0));

// 屏幕坐标 → 子控件坐标
QPoint localPt = child->mapFromGlobal(screenPt);

w.setMinimumSize(200, 100);
w.setMaximumSize(800, 600);
w.setFixedSize(400, 300);        // 等价于 min == max
w.setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Preferred);

void MyWidget::mousePressEvent(QMouseEvent *event)
{
    if (event->button() == Qt::LeftButton) {
        m_dragging = true;
        m_dragPos = event->pos();
        setCursor(Qt::ClosedHandCursor);
    }
}

void MyWidget::mouseMoveEvent(QMouseEvent *event)
{
    if (m_dragging) {
        QPoint delta = event->pos() - m_dragPos;
        move(pos() + delta);
    }
}

void MyWidget::mouseReleaseEvent(QMouseEvent *event)
{
    if (event->button() == Qt::LeftButton && m_dragging) {
        m_dragging = false;
        setCursor(Qt::ArrowCursor);
    }
}

void MyWidget::keyPressEvent(QKeyEvent *event)
{
    switch (event->key()) {
    case Qt::Key_Escape:
        close();
        break;
    case Qt::Key_Space:
        toggleState();
        break;
    default:
        QWidget::keyPressEvent(event);  // 转发给父类
    }
}

class Controller : public QObject
{
protected:
    bool eventFilter(QObject *obj, QEvent *event) override
    {
        if (event->type() == QEvent::MouseButtonPress) {
            auto *w = qobject_cast<QWidget *>(obj);
            if (w) {
                qDebug() << "Clicked:" << w->objectName();
            }
        }
        return false;  // false = 继续处理, true = 拦截
    }
};

// 使用
Controller *ctrl = new Controller(this);
childWidget->installEventFilter(ctrl);

// 定义自定义事件类型
static const QEvent::Type MyCustomEventType =
    static_cast<QEvent::Type>(QEvent::registerEventType());

class MyCustomEvent : public QEvent
{
public:
    MyCustomEvent(int data)
        : QEvent(MyCustomEventType), m_data(data) {}
    int data() const { return m_data; }
private:
    int m_data;
};

// 发送事件（同步）
QApplication::sendEvent(receiver, new MyCustomEvent(42));

// 投递事件（异步）
QApplication::postEvent(receiver, new MyCustomEvent(42));

void MyWidget::paintEvent(QPaintEvent *event)
{
    QPainter painter(this);
    painter.setRenderHint(QPainter::Antialiasing);

    // 背景
    painter.fillRect(rect(), QColor(240, 240, 245));

    // 绘制文本
    painter.setPen(QColor(50, 50, 50));
    painter.setFont(QFont("Arial", 14, QFont::Bold));
    painter.drawText(rect(), Qt::AlignCenter, "Hello, QWidget!");

    // 绘制矩形
    painter.setPen(QPen(QColor(100, 150, 255), 2));
    painter.setBrush(QColor(100, 150, 255, 80));
    painter.drawRoundedRect(50, 50, 200, 100, 8, 8);

    // 绘制线条
    painter.drawLine(10, 10, 300, 200);

    // 绘制椭圆
    painter.drawEllipse(QPoint(200, 150), 50, 30);

    // 绘制弧线
    painter.drawArc(QRect(50, 50, 100, 100), 0, 180 * 16);

    // 绘制多边形
    QPolygon polygon;
    polygon << QPoint(100, 10) << QPoint(150, 60) << QPoint(50, 60);
    painter.drawPolygon(polygon);
}

// 请求重绘（异步，合并多次请求为一次绘制）
widget->update();

// 请求重绘指定区域（更高效）
widget->update(10, 10, 100, 50);

// 立即重绘（同步，一般不推荐）
widget->repaint();

painter.setRenderHint(QPainter::Antialiasing, true);
painter.setRenderHint(QPainter::TextAntialiasing, true);
painter.setRenderHint(QPainter::SmoothPixmapTransform, true);

// 全局样式
qApp->setStyleSheet(R"(
    QWidget {
        background-color: #f0f0f0;
        font-family: "Microsoft YaHei";
        font-size: 13px;
    }
    QPushButton {
        background-color: #4A90D9;
        color: white;
        border: none;
        border-radius: 4px;
        padding: 6px 16px;
    }
    QPushButton:hover {
        background-color: #357ABD;
    }
    QPushButton:pressed {
        background-color: #2A5F9E;
    }
    QPushButton:disabled {
        background-color: #cccccc;
        color: #888888;
    }
)");

// 单个控件
button->setStyleSheet("background-color: red; color: white;");

// 指定对象名
label->setObjectName("titleLabel");
label->setStyleSheet("QLabel#titleLabel { font-size: 20px; font-weight: bold; }");

button->setStyleSheet(R"(
    QPushButton {
        /* 背景 */
        background-color: #4A90D9;
        background-image: url(:/icons/btn_bg.png);
        /* 边框 */
        border: 2px solid #2A5F9E;
        border-radius: 5px;
        /* 字体 */
        color: white;
        font: bold 14px "Microsoft YaHei";
        /* 内边距 */
        padding: 8px 20px;
        /* 最小宽高 */
        min-width: 80px;
        min-height: 30px;
    }
)");

QPalette pal = widget->palette();
pal.setColor(QPalette::Window, QColor(240, 240, 245));
pal.setColor(QPalette::WindowText, QColor(50, 50, 50));
pal.setColor(QPalette::Button, QColor(74, 144, 217));
pal.setColor(QPalette::ButtonText, Qt::white);
pal.setColor(QPalette::Highlight, QColor(74, 144, 217));
widget->setPalette(pal);

QWidget *panel = new QWidget();
QVBoxLayout *layout = new QVBoxLayout(panel);  // 关联到 panel

layout->addWidget(new QPushButton("Button 1"));
layout->addWidget(new QPushButton("Button 2"));
layout->addWidget(new QPushButton("Button 3"));
layout->addStretch();  // 添加弹性空间

QWidget *mainWidget = new QWidget();

// 主水平布局
QHBoxLayout *mainLayout = new QHBoxLayout(mainWidget);

// 左侧垂直面板
QVBoxLayout *leftPanel = new QVBoxLayout();
leftPanel->addWidget(new QPushButton("Open"));
leftPanel->addWidget(new QPushButton("Save"));
leftPanel->addStretch();

// 右侧网格
QGridLayout *rightGrid = new QGridLayout();
rightGrid->addWidget(new QLabel("Name:"), 0, 0);
rightGrid->addWidget(new QLineEdit(), 0, 1);
rightGrid->addWidget(new QLabel("Age:"), 1, 0);
rightGrid->addWidget(new QSpinBox(), 1, 1);

mainLayout->addLayout(leftPanel);
mainLayout->addLayout(rightGrid);

// 边距
layout->setContentsMargins(10, 10, 10, 10);  // left, top, right, bottom

// 间距
layout->setSpacing(8);

// 伸缩因子
layout->addWidget(button1, 1);  // stretch factor = 1
layout->addWidget(button2, 3);  // stretch factor = 3（占 3 倍空间）

// 对齐
layout->addWidget(button, 0, Qt::AlignCenter);

// QGridLayout 控制
grid->addWidget(widget, row, col, rowSpan, colSpan, alignment);

widget->setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Preferred);
widget->setMinimumSize(100, 50);
widget->setMaximumSize(500, 200);

// 按类型和对象名查找
QPushButton *btn = parent->findChild<QPushButton *>("myButton");

// 查找所有匹配的子控件
QList<QPushButton *> allBtns = parent->findChildren<QPushButton *>();

// 递归查找
QWidget *child = parent->findChild<QWidget *>("deepChild", Qt::FindChildrenRecursively);

const auto children = parentWidget->children();  // QObjectList
for (QObject *obj : children) {
    if (obj->isWidgetType()) {
        auto *w = static_cast<QWidget *>(obj);
        // 处理 w
    }
}

// 提升到最前
widget->raise();

// 降到最低
widget->lower();

// 放到指定兄弟之前
widget->stackUnder(sibling);

// 设置焦点策略
widget->setFocusPolicy(Qt::StrongFocus);    // Tab + 点击
widget->setFocusPolicy(Qt::ClickFocus);     // 仅点击
widget->setFocusPolicy(Qt::TabFocus);       // 仅 Tab
widget->setFocusPolicy(Qt::NoFocus);        // 不接受焦点

// 设置焦点
widget->setFocus();
widget->setFocus(Qt::TabFocusReason);       // 带原因

// 焦点切换
widget->focusNextChild();
widget->focusPreviousChild();

// Tab 顺序
QWidget::setTabOrder(first, second);        // Tab 从 first 到 second

// CircleProgress.h
#pragma once
#include <QWidget>

class CircleProgress : public QWidget
{
    Q_OBJECT
    Q_PROPERTY(int value READ value WRITE setValue NOTIFY valueChanged)
public:
    explicit CircleProgress(QWidget *parent = nullptr);

    int value() const { return m_value; }
    void setValue(int value);
    void setRange(int min, int max);
    void setLineWidth(int width);

signals:
    void valueChanged(int value);

protected:
    void paintEvent(QPaintEvent *event) override;

private:
    int m_min = 0;
    int m_max = 100;
    int m_value = 0;
    int m_lineWidth = 8;
};

// CircleProgress.cpp
#include "CircleProgress.h"
#include <QPainter>
#include <QConicalGradient>

CircleProgress::CircleProgress(QWidget *parent)
    : QWidget(parent)
{
    setMinimumSize(80, 80);
}

void CircleProgress::setValue(int value)
{
    m_value = qBound(m_min, value, m_max);
    update();
    emit valueChanged(m_value);
}

void CircleProgress::setRange(int min, int max)
{
    m_min = min;
    m_max = max;
    update();
}

void CircleProgress::setLineWidth(int width)
{
    m_lineWidth = width;
    update();
}

void CircleProgress::paintEvent(QPaintEvent *)
{
    QPainter p(this);
    p.setRenderHint(QPainter::Antialiasing);

    int side = qMin(width(), height());
    int offset = m_lineWidth / 2 + 4;
    QRectF arcRect(offset, offset, side - 2 * offset, side - 2 * offset);

    // 背景圆环
    p.setPen(QPen(QColor(220, 220, 220), m_lineWidth, Qt::SolidLine, Qt::RoundCap));
    p.drawArc(arcRect, 0, 360 * 16);

    // 前景进度
    double progress = double(m_value - m_min) / (m_max - m_min);
    int spanAngle = static_cast<int>(progress * 360 * 16);

    QConicalGradient gradient(arcRect.center(), 90);
    gradient.setColorAt(0.0, QColor(74, 144, 217));
    gradient.setColorAt(0.5, QColor(100, 200, 255));
    gradient.setColorAt(1.0, QColor(74, 144, 217));

    p.setPen(QPen(QBrush(gradient), m_lineWidth, Qt::SolidLine, Qt::RoundCap));
    p.drawArc(arcRect, 90 * 16, -spanAngle);

    // 中心文字
    p.setPen(QColor(50, 50, 50));
    p.setFont(QFont("Arial", 14, QFont::Bold));
    p.drawText(rect(), Qt::AlignCenter, QString("%1%").arg(int(progress * 100)));
}

// ToggleSwitch.h
class ToggleSwitch : public QWidget
{
    Q_OBJECT
    // handlePos 必须注册为属性,QPropertyAnimation("handlePos") 才能驱动它
    Q_PROPERTY(qreal handlePos READ handlePos WRITE setHandlePos NOTIFY handlePosChanged)
public:
    explicit ToggleSwitch(QWidget *parent = nullptr);
    bool isOn() const { return m_on; }
    qreal handlePos() const { return m_handlePos; }
    void setHandlePos(qreal pos)
    {
        if (qFuzzyCompare(pos, m_handlePos)) return;
        m_handlePos = pos;
        emit handlePosChanged(pos);
        update();   // 属性变化 → 重绘滑块
    }

public slots:
    void setOn(bool on);

signals:
    void toggled(bool on);
    void handlePosChanged(qreal);

protected:
    void paintEvent(QPaintEvent *event) override;
    void mousePressEvent(QMouseEvent *event) override;
    QSize sizeHint() const override;

private:
    bool m_on = false;
    QPropertyAnimation *m_animation = nullptr;
    qreal m_handlePos = 0.0;  // 0.0 ~ 1.0
};

// ToggleSwitch.cpp
ToggleSwitch::ToggleSwitch(QWidget *parent)
    : QWidget(parent)
{
    setFixedSize(60, 30);
    setCursor(Qt::PointingHandCursor);
    m_animation = new QPropertyAnimation(this, "handlePos", this);
    m_animation->setDuration(150);
}

void ToggleSwitch::setOn(bool on)
{
    m_on = on;
    m_animation->setStartValue(m_handlePos);
    m_animation->setEndValue(on ? 1.0 : 0.0);
    m_animation->start();
    emit toggled(m_on);
}

void ToggleSwitch::mousePressEvent(QMouseEvent *)
{
    setOn(!m_on);
}

void ToggleSwitch::paintEvent(QPaintEvent *)
{
    QPainter p(this);
    p.setRenderHint(QPainter::Antialiasing);

    int h = height();
    int trackW = width() - h / 2;
    int handleSize = h - 6;
    int handleX = 3 + m_handlePos * (width() - handleSize - 6);

    // 轨道
    QColor trackColor = m_on ? QColor(74, 144, 217) : QColor(200, 200, 200);
    p.setPen(Qt::NoPen);
    p.setBrush(trackColor);
    p.drawRoundedRect(3, 3, width() - 6, height() - 6, h / 2 - 3, h / 2 - 3);

    // 滑块
    p.setBrush(Qt::white);
    p.setPen(QPen(QColor(180, 180, 180), 1));
    p.drawEllipse(handleX, 3, handleSize, handleSize);
}

QSize ToggleSwitch::sizeHint() const
{
    return QSize(60, 30);
}

// 只更新变化区域
void MyWidget::setValue(int v)
{
    if (m_value == v) return;
    int oldValue = m_value;
    m_value = v;
    // 只更新值显示区域
    update(valueRect());
}

QRect MyWidget::valueRect() const
{
    return QRect(width() - 80, 0, 80, height());
}

// 缓存复杂绘制结果
QPixmap cache;

void MyWidget::paintEvent(QPaintEvent *)
{
    if (cache.isNull()) {
        cache = QPixmap(size());
        cache.fill(Qt::transparent);
        QPainter cachePainter(&cache);
        renderComplexContent(cachePainter);
        cachePainter.end();
    }

    QPainter p(this);
    p.drawPixmap(0, 0, cache);
}

void MyWidget::resizeEvent(QResizeEvent *e)
{
    cache = QPixmap();  // 清除缓存
    QWidget::resizeEvent(e);
}

// ❌ 不推荐
void MyWidget::paintEvent(QPaintEvent *)
{
    for (int i = 0; i < 1000; ++i) {
        QPainter p(this);   // 每次都创建/销毁 QPainter
        p.drawLine(...);
    }
}

// ✅ 推荐
void MyWidget::paintEvent(QPaintEvent *)
{
    QPainter p(this);       // 创建一次
    for (int i = 0; i < 1000; ++i) {
        p.drawLine(...);
    }
}

void MyWidget::paintEvent(QPaintEvent *event)
{
    QPainter p(this);
    // event->rect() 仅包含需要重绘的裁剪区域
    const QRect dirty = event->rect();
    p.setClipRect(dirty);

    // 只在 dirty 区域内绘制
    if (dirty.intersects(m_valueRect)) {
        drawValue(&p);
    }
}

// ✅ 正确：使用 QPainter(this)
void MyWidget::paintEvent(QPaintEvent *)
{
    QPainter painter(this);
    // ...
}

// ⚠️ 能工作但不推荐：QPainter::begin()/end() 是合法的低层 API，效果与上面相同；
// 只是默认构造的 painter 此时尚未激活，必须显式 begin()，且要记得 end()，
// 异常或提前 return 时容易漏掉收尾（少一层 RAII 保障）
void MyWidget::paintEvent(QPaintEvent *)
{
    QPainter painter;
    if (!painter.begin(this))
        return;        // 激活失败时 begin() 返回 false
    // ...
    painter.end();
}

// ❌ 错误：在 paintEvent 外绘制
void MyWidget::updateDisplay()
{
    QPainter painter(this);  // 运行时警告，绘制不生效
}

// ✅ 正确：如果你需要保留父类行为
void MyWidget::resizeEvent(QResizeEvent *event)
{
    // 自定义处理
    adjustChildWidgets();
    QWidget::resizeEvent(event);  // 调用父类
}

// ✅ 正确：指定 parent，自动管理生命周期
auto *label = new QLabel("Hello", parentWidget);

// ✅ 正确：没有 parent 时手动管理
auto *dialog = new QDialog();
dialog->setAttribute(Qt::WA_DeleteOnClose);  // 关闭时自动删除

// ✅ 正确：在布局中设置
layout->addWidget(new QPushButton("OK"));  // 布局不负责内存，parent widget 负责

// ❌ 错误：在非 GUI 线程操作 UI
void Worker::run()
{
    m_label->setText("Done");  // 崩溃或未定义行为
}

// ✅ 正确：使用信号槽跨线程
connect(worker, &Worker::finished, this, [this]() {
    m_label->setText("Done");
});

// ✅ 正确：使用 QMetaObject::invokeMethod
QMetaObject::invokeMethod(m_label, "setText",
    Qt::QueuedConnection, Q_ARG(QString, "Done"));

// ✅ 正确：QTimer::singleShot
QTimer::singleShot(0, m_label, [m_label]() {
    m_label->setText("Done");
});

// ❌ 性能最差:全局通配选择器遍历所有控件(13.7 表明确反对)
qApp->setStyleSheet("* { font-size: 13px; }");

// ⚠️ 仍不理想:整个应用套用 QWidget 选择器,所有 QWidget 后代都参与样式级联重算
qApp->setStyleSheet("QWidget { font-size: 13px; }");

// ✅ 推荐:限定到具体类型/具体对象,只在启动时设置一次
ui->titleLabel->setStyleSheet("QLabel#titleLabel { font-size: 13px; }");

// ❌ 属性变化触发布局重算
widget->setStyleSheet("font-size: 13px;");
// ... 反复调用
widget->setStyleSheet("font-size: 14px;");  // 每次都会触发 recalc

// ✅ 推荐：尽量减少样式表动态变化

// main.cpp 中启用(顺序关键:AA_EnableHighDpiScaling 必须在 QApplication 构造之前设置才生效;
// Qt6 起高 DPI 缩放默认开启,此调用可省略且属性已被弃用)
int main(int argc, char *argv[])
{
#if QT_VERSION >= QT_VERSION_CHECK(5, 6, 0) && QT_VERSION < QT_VERSION_CHECK(6, 0, 0)
    QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling);  // 构造 app 之前!
#endif
    QApplication app(argc, argv);
    // ...
}

// 自定义绘制中使用 devicePixelRatio —— 成员函数定义在类外,绝不能写在 main() 体内
void MyWidget::paintEvent(QPaintEvent *)
{
    QPainter p(this);   // this 是 MyWidget 实例,只在成员函数里有意义
    qreal dpr = devicePixelRatioF();
    // 使用 dpr 缩放像素图等资源
}