Linux下QMainWindow分离的QDockWidget失焦后无法重获焦点问题

问题描述 #

在Linux平台进行Qt开发时遇到异常：创建包含单个QDockWidget的QMainWindow，将停靠控件从主窗口分离为浮动窗口后，一旦该停靠控件失去焦点，就无法再次获取焦点，该问题如何排查解决？

问题复现代码 #

#include <QApplication>
#include <QDockWidget>
#include <QMainWindow>
#include <QLineEdit>
#include <QWidget>
#include <QLayout>

int main(int argc, char** argv) {
  QApplication application(argc, argv);
  QMainWindow *mainWindow = new QMainWindow;
  QDockWidget *dockWidget = new QDockWidget;

  mainWindow->addDockWidget(Qt::LeftDockWidgetArea, dockWidget);
  dockWidget->setWidget(new QWidget);
  dockWidget->setAllowedAreas(Qt::AllDockWidgetAreas);
  dockWidget->widget()->setLayout(new QHBoxLayout);
  dockWidget->widget()->layout()->addWidget(new QLineEdit);
  mainWindow->show();

  application.exec();
}

复现步骤 #

• 运行上述代码生成的程序，将QDockWidget从主窗口分离为独立浮动窗口。
• 按下Alt + Tab切换窗口（执行任意会导致浮动停靠窗口失去焦点的操作均可）。
• 尝试点击浮动停靠窗口内的QLineEdit输入框，验证是否能重新获取输入焦点。

多环境测试结果

排查思路 #

• 从多环境测试结果可直接定位：问题仅出现在KDE的KWin窗口管理器下，GNOME系WM无异常，属于Qt窗口标志与KWin焦点策略的适配问题，和业务控件逻辑无关。
• 可通过Linux下xprop命令点击浮动状态的QDockWidget查看窗口属性，会发现其_NET_WM_WINDOW_TYPE值为_NET_WM_WINDOW_TYPE_UTILITY，对应Qt的Qt::Tool窗口标志。KWin默认对Utility类型的工具窗口做了焦点限制：仅在父窗口激活时允许工具窗口获取焦点，一旦工具窗口失焦，点击无法主动激活窗口，这就是问题的根因。
• GNOME系的Mutter、Metacity等WM没有该焦点限制，因此不会复现问题。

解决方案 #

方案1：修改浮动QDockWidget的窗口标志（推荐） #

监听QDockWidget的topLevelChanged信号，当控件变为浮动状态时，移除Qt::Tool窗口标志，替换为Qt::Dialog即可适配KWin的焦点规则，代码如下：

// 在dockWidget创建完成后添加以下信号连接
QObject::connect(dockWidget, &QDockWidget::topLevelChanged, [dockWidget](bool floating) {
    if (floating) {
        // 保留原有窗口标志，仅移除Qt::Tool、追加Qt::Dialog
        dockWidget->setWindowFlags(dockWidget->windowFlags() & ~Qt::Tool | Qt::Dialog);
        // 修改窗口标志后控件会自动隐藏，需要手动调用show重新显示
        dockWidget->show();
    }
});

该方案不会破坏QDockWidget的原有停靠、拖动逻辑，兼容性最好。

方案2：手动处理点击激活逻辑 #

如果需要保留Utility窗口类型，可以给浮动的QDockWidget安装事件过滤器，检测到鼠标点击事件时手动激活窗口：

// 自定义事件过滤器
class DockEventFilter : public QObject {
protected:
    bool eventFilter(QObject* watched, QEvent* event) override {
        if (event->type() == QEvent::MouseButtonPress) {
            QDockWidget* dock = qobject_cast<QDockWidget*>(watched);
            if (dock && dock->isFloating()) {
                dock->activateWindow();
                dock->setFocus();
            }
        }
        return QObject::eventFilter(watched, event);
    }
};

// 给dockWidget安装事件过滤器
dockWidget->installEventFilter(new DockEventFilter);

内容的提问来源于stack exchange，提问作者Ghasem Ramezani