Qt绘制残留问题排查与修复日志

问题背景

在Qt应用程序中，PMainWidget父对象包含PWaveWin子对象。当改变bottomHeight参数时，父对象的paintEvent被调用，但绘制线条时出现残留问题：上一次的线条部分像素点未被清除，直到子控件刷新后才消失。

问题现象

改变bottomHeight后，新线条正常绘制
旧线条的两个像素点出现在子控件两侧（白色像素点，周围红色背景）
子控件刷新后，残留像素点消失
后续再次改变bottomHeight，问题不再出现

排查过程

阶段1：初步验证

操作：临时修改背景色为红色，观察绘制效果

现象：

背景确实变为红色
但白色像素点仍然可见，说明fillRect未完全清除旧线条

假设1 ：fillRect未执行？

验证：在fillRect后立即绘制一个测试矩形，确认fillRect确实执行
结果：测试矩形可见，假设不成立

阶段2：排查绘制区域

操作：添加调试代码，记录实际更新区域

复制代码

void PMainWidget::paintEvent(QPaintEvent* event)
{
    qDebug() << "=================== PaintEvent Called ===================";
    qDebug() << "Widget size:" << width() << "x" << height();
    qDebug() << "Update region rects:" << event->region().rectCount();
    
    // 记录每个更新区域
    foreach(const QRect& rect, event->region().rects()) {
        qDebug() << "  Update rect:" << rect;
    }
    
    qDebug() << "Bottom height:" << bottomHeight;
    
    QPainter p(this);
    // ... 原有绘制代码
}

发现：

复制代码

第一次改变bottomHeight:
=================== PaintEvent Called ===================
Widget size: 800 x 600
Update region rects: 1
  Update rect: QRect(0,590 800x4)  // 只有新线条区域
Bottom height: 10

第二次改变bottomHeight:
=================== PaintEvent Called ===================
Widget size: 800 x 600
Update region rects: 1
  Update rect: QRect(0,585 800x4)  // 只有新线条区域
Bottom height: 15

关键发现 ：Qt只更新了新线条所在区域，旧线条区域未被标记为需要更新！

阶段3：验证Qt局部重绘机制

操作：创建测试程序验证Qt的更新行为

复制代码

// 测试代码
void PMainWidget::changeBottomHeight(int newHeight)
{
    static int lastHeight = bottomHeight;
    
    qDebug() << "Changing height from" << lastHeight << "to" << newHeight;
    
    // 记录旧线条位置
    int oldY = height() - (lastHeight + m_BotStatebar.botStatebarHeight);
    int newY = height() - (newHeight + m_BotStatebar.botStatebarHeight);
    
    qDebug() << "Old line Y:" << oldY << "New line Y:" << newY;
    
    bottomHeight = newHeight;
    update();  // 默认局部更新
    
    lastHeight = newHeight;
}

结论：Qt的update()默认使用局部重绘，只更新控件中变化的部分。

阶段4：排查子控件影响

操作：添加子控件绘制日志

复制代码

void PWaveWin::paintEvent(QPaintEvent* event)
{
    qDebug() << QTime::currentTime().toString("hh:mm:ss.zzz")<< "[PWaveWin] PaintEvent at Update region:" << event->region();
    
    QPainter painter(this);
    // ... 子控件绘制代码
}

发现的时间序列：

复制代码

14:30:25.123 [PMainWidget] PaintEvent - 更新区域: QRect(0,590 800x4)
14:30:25.125 [CWaveWin] PaintEvent at Update region: QRect(0,0 750x550)  // 稍后执行
14:30:25.127 屏幕刷新显示

关键发现 ：子控件的paintEvent在父控件之后执行，覆盖了父控件绘制的部分内容。

阶段5：深入理解问题根源

根本原因分析：

Qt局部重绘机制：默认只重绘"脏区域"，旧线条区域未被标记
子控件绘制时机：子控件在父控件后绘制，但只绘制自己的区域
线条边界问题：线条与子控件边界相交的两个像素点位于子控件外部，被子控件遮挡但又未被子控件清除

可视化解释：

复制代码

初始状态：    [父控件背景] + [子控件] + [父控件背景]
绘制新线条：  [父控件背景] + [子控件] + [父控件背景+新线条]
实际显示：    [父控件背景] + [子控件旧内容] + [父控件背景+新线条]
                            ↑ 子控件未更新，覆盖了线条中间部分

阶段6：解决方案实施

方案1：手动计算更新区域（首选方案）

复制代码

void PMainWidget::setBottomHeight(int newHeight)
{
    // 记录旧线条位置
    static int lastBottomHeight = bottomHeight;
    int oldY = height() - (lastBottomHeight + m_BotStatebar.botStatebarHeight);
    
    // 更新值
    bottomHeight = newHeight;
    
    // 计算新线条位置
    int newY = height() - (bottomHeight + m_BotStatebar.botStatebarHeight);
    
    // 创建更新区域（包含新旧线条）
    QRegion updateRegion;
    
    // 旧线条区域（上下各扩展2像素确保完全覆盖）
    int lineHeight = BORDER_WIDTH;
    updateRegion += QRect(0, oldY - 2, width(), lineHeight + 4);
    
    // 新线条区域
    updateRegion += QRect(0, newY - 2, width(), lineHeight + 4);
    
    // 请求更新
    update(updateRegion);
    
    // 同时更新子控件（避免遮挡问题）
    if (m_waveWin) {
        m_waveWin->update();
    }
    
    lastBottomHeight = newHeight;
}

方案2：强制完整重绘（简单方案）

复制代码

void PMainWidget::setBottomHeight(int newHeight)
{
    bottomHeight = newHeight;
    update(rect());  // 更新整个区域
}

方案3：优化绘制逻辑

复制代码

void PMainWidget::paintEvent(QPaintEvent* event)
{
    QPainter p(this);
    
    // 使用事件区域优化绘制性能
    if (event->region().isEmpty()) {
        p.fillRect(rect(), BACKGROUND_COLOR);
    } else {
        foreach (const QRect &rect, event->region().rects()) {
            p.fillRect(rect, BACKGROUND_COLOR);
        }
    }
    
    // 绘制线条
    // ... 原有线条绘制代码
}

阶段7：测试验证

测试用例：

快速连续改变bottomHeight
改变窗口大小后改变bottomHeight
最小化/恢复窗口后测试
多显示器环境下测试

测试结果：

方案1：完美解决，无残留，性能最优
方案2：完美解决，无残留，但性能稍差（重绘整个窗口）
方案3：需要配合方案1或2使用

最终解决方案

选择方案1（手动计算更新区域），原因：

精确控制：只更新需要的区域，性能最佳
彻底解决：确保新旧线条区域都被更新
预防性：同时更新子控件，避免遮挡问题

经验总结

Qt绘制优化 ：理解update()的局部重绘机制，默认只更新变化区域
脏区域管理：需要显式管理所有需要更新的区域
控件层级：注意父控件和子控件的绘制顺序和覆盖关系
调试技巧 ：使用qDebug()输出更新区域，可视化理解绘制过程

预防措施

代码规范：改变影响绘制的参数时，显式计算所有受影响区域
文档注释：在相关代码处添加注释，说明Qt绘制特性
单元测试：添加绘制相关的单元测试，确保无残留
性能监控 ：监控paintEvent调用频率和区域大小，避免过度绘制

扩展思考

这个问题揭示了Qt绘制系统的一个重要设计选择：性能与正确性的平衡。默认情况下，Qt选择性能优先（局部重绘），但要求开发者理解并正确管理更新区域。这种设计在复杂UI中尤为重要，能显著提升性能，但也增加了正确处理的复杂度。