ScreenLockDetector/README.md

# Qt Screen Lock Detection Demo

一个基于 Qt5 + CMake 的 Linux 应用程序，用于检测 Ubuntu 系统的锁屏状态，并在锁屏时自动停止所有 Paint 事件。

## 功能特性

- ✅ **自动检测锁屏状态**：通过 DBus 监听 Linux 系统的锁屏/解锁事件
- ✅ **自动停止绘制**：屏幕锁定时自动停止所有 Paint 事件，节省系统资源
- ✅ **实时动画演示**：持续的动画效果，直观展示绘制的启用/禁用状态
- ✅ **手动控制**：提供手动启用/禁用绘制的按钮
- ✅ **状态监控**：实时显示锁屏状态、绘制状态和帧数统计
- ✅ **多桌面环境支持**：支持 GNOME、KDE、XFCE、Deepin DDE 等主流桌面环境

## 技术架构

### 核心组件

1. **ScreenLockDetector** - 锁屏检测器
   - 通过 Qt DBus 监听系统锁屏信号
   - 支持 GNOME ScreenSaver、systemd-logind 和 Deepin DDE 接口
   - 发出锁屏/解锁信号供其他组件订阅

2. **CustomWidget** - 自定义绘制组件
   - 实现了动态动画效果（旋转圆圈、波浪效果等）
   - 60 FPS 刷新率
   - 可控制的绘制启用/禁用状态
   - 帧数统计功能

3. **MainWindow** - 主窗口
   - 整合各个组件
   - 提供用户界面和控制面板
   - 实时状态显示

### 技术栈

- **语言**：C++11
- **GUI 框架**：Qt 5.15.2
- **构建系统**：CMake 3.10+
- **系统接口**：Qt DBus
- **平台**：Linux Ubuntu

## 系统要求

- Linux Ubuntu 18.04 或更高版本（也支持 Deepin OS）
- Qt 5.15.2（安装在 `$HOME/sdk/qt-5.15.2`）
- CMake 3.10 或更高版本
- GCC/G++ 编译器（支持 C++11）
- DBus 系统服务

## 安装与编译

### 1. 确保 Qt5 已安装

```bash
# 检查 Qt5 目录是否存在
ls $HOME/sdk/qt-5.15.2
```

如果 Qt5 安装在其他位置，请修改 `CMakeLists.txt` 中的 Qt5_DIR 路径：

```cmake
set(Qt5_DIR "$ENV{HOME}/sdk/qt-5.15.2/lib/cmake/Qt5")
```

### 2. 赋予脚本执行权限

```bash
chmod +x build.sh run.sh
```

### 3. 编译项目

```bash
./build.sh
```

编译成功后，可执行文件将生成在 `build/bin/ScreenLockDemo`

## 运行应用

### 方法 1：使用运行脚本（推荐）

```bash
./run.sh
```

### 方法 2：直接运行可执行文件

```bash
cd build/bin
./ScreenLockDemo
```

### 方法 3：手动设置环境变量并运行

```bash
export LD_LIBRARY_PATH=$HOME/sdk/qt-5.15.2/lib:$LD_LIBRARY_PATH
./build/bin/ScreenLockDemo
```

## 使用说明

1. **启动应用**：运行应用后，会看到一个带有动态动画的窗口

2. **测试锁屏检测**：
   - 使用快捷键锁定屏幕：`Ctrl + Alt + L` 或 `Super + L`
   - 观察动画是否停止
   - 解锁后动画应自动恢复

3. **查看状态信息**：
   - **Detector Status**：检测器是否正常工作
   - **Screen Lock Status**：当前屏幕锁定状态（🔒 LOCKED / 🔓 UNLOCKED）
   - **Painting Status**：绘制是否启用（✓ ENABLED / ✗ DISABLED）
   - **Frame Count**：已绘制的总帧数

4. **手动控制**（可选）：
   - **Enable Painting**：手动启用绘制
   - **Disable Painting**：手动禁用绘制
   - **Reset Frame Count**：重置帧数计数器

## 工作原理

### DBus 监听机制

应用程序通过 Qt DBus 连接到 Linux 系统的锁屏服务：

1. **Deepin DDE 接口**（Deepin OS）
   ```
   Service: com.deepin.dde.lockFront
   Path: /com/deepin/dde/lockFront
   Interface: com.deepin.dde.lockFront
   Signals: Locked(), Unlocked()
   ```

2. **GNOME ScreenSaver 接口**
   ```
   Service: org.gnome.ScreenSaver
   Path: /org/gnome/ScreenSaver
   Interface: org.gnome.ScreenSaver
   Signal: ActiveChanged(bool)
   ```

3. **systemd-logind 接口**
   ```
   Service: org.freedesktop.login1
   Path: /org/freedesktop/login1/session/auto
   Interface: org.freedesktop.login1.Session
   Signals: Lock(), Unlock()
   ```

### Paint 事件控制

当检测到锁屏时：
1. `ScreenLockDetector` 发出 `screenLocked()` 信号
2. `MainWindow` 接收信号并调用 `CustomWidget::setPaintingEnabled(false)`
3. `CustomWidget` 停止动画定时器
4. `paintEvent()` 检查启用状态，不再绘制动画内容

当检测到解锁时：
1. `ScreenLockDetector` 发出 `screenUnlocked()` 信号
2. `MainWindow` 调用 `CustomWidget::setPaintingEnabled(true)`
3. `CustomWidget` 重启动画定时器
4. 动画恢复正常绘制

## 项目结构

```
qt_screan_lock/
├── CMakeLists.txt              # CMake 构建配置
├── README.md                   # 项目文档
├── build.sh                    # 编译脚本
├── run.sh                      # 运行脚本
└── src/
    ├── main.cpp                # 程序入口
    ├── mainwindow.h            # 主窗口头文件
    ├── mainwindow.cpp          # 主窗口实现
    ├── screenlockdetector.h    # 锁屏检测器头文件
    ├── screenlockdetector.cpp  # 锁屏检测器实现
    ├── customwidget.h          # 自定义组件头文件
    └── customwidget.cpp        # 自定义组件实现
```

## 故障排除

### 问题 1：锁屏检测不工作

**可能原因**：
- DBus 服务未运行
- 桌面环境不支持标准 DBus 接口
- 权限不足

**解决方案**：
```bash
# 检查 DBus 服务
ps aux | grep dbus

# 检查 GNOME ScreenSaver 是否可用
qdbus org.gnome.ScreenSaver

# 查看应用日志输出，确认连接状态
```

### 问题 2：编译错误 - Qt5 not found

**解决方案**：
1. 确认 Qt5 安装路径：`ls $HOME/sdk/qt-5.15.2`
2. 修改 `CMakeLists.txt` 中的 Qt5_DIR 路径
3. 或设置环境变量：`export Qt5_DIR=$HOME/sdk/qt-5.15.2/lib/cmake/Qt5`

### 问题 3：运行时找不到 Qt 库

**解决方案**：
```bash
# 设置 LD_LIBRARY_PATH
export LD_LIBRARY_PATH=$HOME/sdk/qt-5.15.2/lib:$LD_LIBRARY_PATH

# 或使用 run.sh 脚本（已包含此配置）
./run.sh
```

### 问题 4：警告 - Failed to connect to screen lock detection service

**说明**：这是正常的，表示某些 DBus 接口在当前桌面环境中不可用。只要至少有一个接口连接成功，应用就能正常工作。

## 调试模式

应用程序会在控制台输出详细的调试信息：

```bash
# 运行并查看详细日志
./run.sh 2>&1 | tee app.log

# 查看特定类别的日志
./run.sh 2>&1 | grep "ScreenLockDetector"
```

## 扩展与定制

### 添加更多动画效果

在 `customwidget.cpp` 中的 `drawBackground()`, `drawRotatingCircles()`, `drawWaveEffect()` 等方法中添加自定义绘制代码。

### 支持其他桌面环境

在 `screenlockdetector.cpp` 中添加更多 DBus 接口连接：

```cpp
bool ScreenLockDetector::connectToKDEScreenSaver()
{
    // 添加 KDE Plasma 锁屏检测支持
    // Service: org.kde.screensaver
    // ...
}
```

### 性能优化

调整动画刷新率（当前为 60 FPS）：

```cpp
// 在 customwidget.cpp 构造函数中
m_animationTimer->start(33);  // 30 FPS (1000/30 ≈ 33ms)
```

## 许可证

本项目仅用于学习和演示目的。

## 作者

Qt Screen Lock Detection Demo

## 更新日志

### v1.1.0 (2024)
- ✅ 新增 Deepin OS (DDE) 锁屏检测支持
- ✅ 优化多桌面环境兼容性

### v1.0.0 (2024)
- ✅ 初始版本发布
- ✅ 支持 GNOME 和 systemd-logind 锁屏检测
- ✅ 实现自动 Paint 事件控制
- ✅ 提供丰富的动画演示效果
- ✅ 完整的状态监控和手动控制界面

## 反馈与贡献

如有问题或建议，欢迎提出！