296 lines
6.6 KiB
Markdown
296 lines
6.6 KiB
Markdown
# ScreenLockDetector 迁移指南
|
||
|
||
## 从旧版本迁移到重构版本
|
||
|
||
本指南帮助您从旧的单一类结构迁移到新的面向对象架构。
|
||
|
||
## 好消息：无需修改代码！
|
||
|
||
如果您只使用 `ScreenLockDetector` 类的公共接口，**无需修改任何代码**。新版本完全向后兼容。
|
||
|
||
### 接口保持不变
|
||
|
||
```cpp
|
||
// 创建实例（保持不变）
|
||
ScreenLockDetector *detector = new ScreenLockDetector(parent);
|
||
|
||
// 初始化（保持不变）
|
||
detector->initialize();
|
||
|
||
// 获取状态（保持不变）
|
||
bool locked = detector->isScreenLocked();
|
||
|
||
// 连接信号（保持不变）
|
||
connect(detector, &ScreenLockDetector::screenLocked, ...);
|
||
connect(detector, &ScreenLockDetector::screenUnlocked, ...);
|
||
connect(detector, &ScreenLockDetector::lockStateChanged, ...);
|
||
```
|
||
|
||
## 架构变化
|
||
|
||
### 旧架构
|
||
```
|
||
ScreenLockDetector
|
||
├── Linux 代码 (#ifdef Q_OS_LINUX)
|
||
└── macOS 代码 (#ifdef Q_OS_MAC)
|
||
```
|
||
|
||
### 新架构
|
||
```
|
||
ScreenLockDetectorBase (抽象基类)
|
||
├── ScreenLockDetectorLinux
|
||
└── ScreenLockDetectorMacOS
|
||
|
||
ScreenLockDetector (工厂类)
|
||
```
|
||
|
||
## 文件重命名对照表
|
||
|
||
| 旧文件名 | 新文件名 | 说明 |
|
||
|---------|---------|------|
|
||
| `screenlockdetector_mac.h` | `screenlockdetector_macos.h` | 规范化命名 |
|
||
| `screenlockdetector_mac.mm` | `screenlockdetector_macos.mm` | 规范化命名 |
|
||
| N/A | `screenlockdetector_base.h` | 新增抽象基类 |
|
||
| N/A | `screenlockdetector_base.cpp` | 新增抽象基类 |
|
||
| N/A | `screenlockdetector_linux.h` | Linux 实现分离 |
|
||
| N/A | `screenlockdetector_linux.cpp` | Linux 实现分离 |
|
||
|
||
## 如果您扩展了原类
|
||
|
||
如果您继承或扩展了 `ScreenLockDetector` 类，需要做以下调整：
|
||
|
||
### 场景 1: 继承 ScreenLockDetector
|
||
|
||
**旧代码:**
|
||
```cpp
|
||
class MyDetector : public ScreenLockDetector {
|
||
// 自定义实现
|
||
};
|
||
```
|
||
|
||
**新代码 - 选项 A (推荐):**
|
||
继承抽象基类并实现自己的平台
|
||
```cpp
|
||
class MyDetector : public ScreenLockDetectorBase {
|
||
public:
|
||
bool initialize() override {
|
||
// 您的实现
|
||
return true;
|
||
}
|
||
};
|
||
```
|
||
|
||
**新代码 - 选项 B:**
|
||
继承现有的平台实现
|
||
```cpp
|
||
#ifdef Q_OS_LINUX
|
||
class MyDetector : public ScreenLockDetectorLinux {
|
||
// 扩展 Linux 实现
|
||
};
|
||
#endif
|
||
```
|
||
|
||
### 场景 2: 访问平台特定成员
|
||
|
||
**旧代码:**
|
||
```cpp
|
||
#ifdef Q_OS_LINUX
|
||
detector->m_gnomeInterface->call(...);
|
||
#endif
|
||
```
|
||
|
||
**新方法:**
|
||
平台特定成员现在是私有的。如果需要访问，应该：
|
||
|
||
1. 添加公共方法到对应的平台类
|
||
2. 或者通过信号/槽机制通信
|
||
3. 或者使用组合而非继承
|
||
|
||
```cpp
|
||
// 示例：添加新方法到平台类
|
||
class ScreenLockDetectorLinux : public ScreenLockDetectorBase {
|
||
public:
|
||
// 添加新的公共方法
|
||
bool querySpecificState() {
|
||
if (m_gnomeInterface) {
|
||
return m_gnomeInterface->call("GetActive").value();
|
||
}
|
||
return false;
|
||
}
|
||
};
|
||
```
|
||
|
||
## 构建系统变化
|
||
|
||
### CMakeLists.txt
|
||
|
||
如果您修改了 `CMakeLists.txt`，请注意源文件列表的变化：
|
||
|
||
**旧配置:**
|
||
```cmake
|
||
if(APPLE)
|
||
list(APPEND SOURCES
|
||
src/screenlockdetector.cpp
|
||
src/screenlockdetector_mac.mm
|
||
)
|
||
endif()
|
||
```
|
||
|
||
**新配置:**
|
||
```cmake
|
||
# 通用源文件（所有平台）
|
||
set(SOURCES
|
||
src/screenlockdetector.cpp
|
||
src/screenlockdetector_base.cpp
|
||
...
|
||
)
|
||
|
||
# 平台特定源文件
|
||
if(APPLE)
|
||
list(APPEND SOURCES
|
||
src/screenlockdetector_macos.mm
|
||
)
|
||
elseif(UNIX)
|
||
list(APPEND SOURCES
|
||
src/screenlockdetector_linux.cpp
|
||
)
|
||
endif()
|
||
```
|
||
|
||
## 添加新平台支持
|
||
|
||
新架构使添加平台变得更容易：
|
||
|
||
### 步骤 1: 创建平台类
|
||
|
||
```cpp
|
||
// screenlockdetector_windows.h
|
||
#ifndef SCREENLOCKDETECTOR_WINDOWS_H
|
||
#define SCREENLOCKDETECTOR_WINDOWS_H
|
||
|
||
#include "screenlockdetector_base.h"
|
||
|
||
#ifdef Q_OS_WIN
|
||
class ScreenLockDetectorWindows : public ScreenLockDetectorBase {
|
||
Q_OBJECT
|
||
public:
|
||
explicit ScreenLockDetectorWindows(QObject *parent = nullptr);
|
||
~ScreenLockDetectorWindows() override;
|
||
bool initialize() override;
|
||
};
|
||
#endif
|
||
|
||
#endif
|
||
```
|
||
|
||
### 步骤 2: 实现平台类
|
||
|
||
```cpp
|
||
// screenlockdetector_windows.cpp
|
||
#include "screenlockdetector_windows.h"
|
||
|
||
#ifdef Q_OS_WIN
|
||
ScreenLockDetectorWindows::ScreenLockDetectorWindows(QObject *parent)
|
||
: ScreenLockDetectorBase(parent) {
|
||
}
|
||
|
||
bool ScreenLockDetectorWindows::initialize() {
|
||
// Windows 特定的初始化代码
|
||
return true;
|
||
}
|
||
#endif
|
||
```
|
||
|
||
### 步骤 3: 更新工厂方法
|
||
|
||
```cpp
|
||
// screenlockdetector.cpp
|
||
ScreenLockDetectorBase* ScreenLockDetector::createPlatformDetector() {
|
||
#ifdef Q_OS_MAC
|
||
return new ScreenLockDetectorMacOS(this);
|
||
#elif defined(Q_OS_LINUX)
|
||
return new ScreenLockDetectorLinux(this);
|
||
#elif defined(Q_OS_WIN)
|
||
return new ScreenLockDetectorWindows(this); // 新增
|
||
#else
|
||
return nullptr;
|
||
#endif
|
||
}
|
||
```
|
||
|
||
### 步骤 4: 更新 CMakeLists.txt
|
||
|
||
```cmake
|
||
if(WIN32)
|
||
list(APPEND SOURCES src/screenlockdetector_windows.cpp)
|
||
list(APPEND HEADERS src/screenlockdetector_windows.h)
|
||
endif()
|
||
```
|
||
|
||
## 调试技巧
|
||
|
||
### 查看使用的平台实现
|
||
|
||
```cpp
|
||
ScreenLockDetector *detector = new ScreenLockDetector(this);
|
||
if (detector->initialize()) {
|
||
// 在调试器中检查 detector->m_detector 的实际类型
|
||
qDebug() << "Detector initialized successfully";
|
||
}
|
||
```
|
||
|
||
### 测试不同平台
|
||
|
||
在开发时，可以临时修改工厂方法来测试特定平台：
|
||
|
||
```cpp
|
||
ScreenLockDetectorBase* ScreenLockDetector::createPlatformDetector() {
|
||
// 强制使用特定平台（仅用于测试）
|
||
// return new ScreenLockDetectorLinux(this);
|
||
|
||
// 正常的平台检测
|
||
#ifdef Q_OS_MAC
|
||
return new ScreenLockDetectorMacOS(this);
|
||
// ...
|
||
}
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### Q: 为什么要重构？
|
||
|
||
A: 新架构提供：
|
||
- 更清晰的代码组织
|
||
- 更容易添加新平台
|
||
- 更好的可测试性
|
||
- 减少预处理器指令
|
||
|
||
### Q: 性能有影响吗？
|
||
|
||
A: 没有。运行时性能完全相同，只是多了一层间接调用（虚函数），但这对于事件驱动的应用影响可以忽略不计。
|
||
|
||
### Q: 旧的头文件还能用吗？
|
||
|
||
A: `screenlockdetector_mac.h/mm` 文件仍然存在但已弃用。建议在方便时更新引用。
|
||
|
||
### Q: 如何回退到旧版本？
|
||
|
||
A: 使用 git：
|
||
```bash
|
||
git checkout <old-commit-hash> src/screenlockdetector*
|
||
```
|
||
|
||
## 支持
|
||
|
||
如果遇到迁移问题，请：
|
||
1. 查看 `docs/REFACTORING.md` 了解架构详情
|
||
2. 检查示例代码在 `src/main.cpp` 和 `src/mainwindow.cpp`
|
||
3. 提交 Issue 或联系开发团队
|
||
|
||
## 总结
|
||
|
||
对于大多数用户：**无需任何修改**，直接重新编译即可。
|
||
|
||
对于高级用户：新架构提供了更好的扩展性和可维护性，值得花时间理解新的设计。
|
||
|
||
祝您使用愉快！ |