# GTodo

**Repository Path**: gaobooo/gtodo

## Basic Information

- **Project Name**: GTodo
- **Description**: 一个简单的todo软件
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-04
- **Last Updated**: 2026-09-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GTodo

一个 Qt6/QML 实现的桌面 TODO 清单小部件，主打"常驻桌面边缘的抽屉式待办"：

- 无边框、置顶窗口，可吸附屏幕边缘（edge snapping），悬停时抽屉滑出
- SQLite 本地持久化，数据存于 `~/.local/share/gtodo/`（Linux）
- 系统托盘图标，最小化到托盘
- 单实例：同一用户会话内重复启动会唤醒已有窗口（`QLocalServer`/`QLocalSocket`）
- X11 与 Wayland（KDE Plasma）双支持，Windows 为次要平台

如果有什么需要加入的功能或者bug，欢迎提issue或者PR。

## TODO

- 抽象 Wayland 后端，适配后续 DE （参考 QPA？）

## 未来可能有的计划

- 支持保存截图然后自动识别创建计划
- 收起不采用吸附，改成变成一个球形（类似于360,后续可能会做成球形也支持吸附

## 平台支持

| 平台 | 后端 | 说明 |
|------|------|------|
| Linux X11 | `X11Platform` | xcb + EWMH（`_NET_WM_WINDOW_TYPE` / `_NET_WM_STATE`） |
| Linux Wayland (KDE) | `WaylandPlatform` | KWayland（可选）：skip-taskbar、keep-above、真实窗口几何 |
| Linux Wayland (其他合成器) | `WaylandPlatform` | 降级：无 KWayland 时位置吸附等能力受限 |
| Windows / 其他 | `GenericPlatform` | 通用回退 |

> 目前暂时还没有对 Windows 做适配，后续应该会做 Windows 的适配
> Wayland 方面的话，由于 置顶、手动设置窗口位置等功能，原生协议不支持，需要使用 DE 的私有协议来实现。暂时只适配了 KDE 的置顶功能，详细见 Wayland 一节。
> Wayland 方面的适配暂时未计划，因为很多功能都难以适配，优先保证 X11 + Windows 平台下能正常使用。

平台后端在运行时由 `PlatformFactory` 根据 `QGuiApplication::platformName()` 选择，窗口行为统一走 `PlatformInterface` 抽象。

## 编译依赖

- CMake >= 3.16
- C++17 编译器（gcc / clang / MSVC）
- Qt6（优先）或 Qt5，模块：Core, Gui, Quick, Sql, Widgets, Qml, QuickControls2, Network, DBus
- Linux X11：xcb
- Linux KDE Wayland（可选）：KWaylandClient（`kf6-kwayland-devel`）与 `wayland-devel`

Fedora (dnf) 安装示例：

```bash
sudo dnf install cmake gcc-c++ qt6-qtbase-devel qt6-qtdeclarative-devel \
    qt6-qtwayland libxcb-devel

# 可选：KDE Wayland 完整支持
sudo dnf install kf6-kwayland-devel wayland-devel
```

## 构建

### Linux

```bash
# 配置（使用 CMakePresets.json，必要时自设 QT_DIR）
cmake --preset default

# 编译
cmake --build build

# 从构建树直接运行
./build/bin/gtodo

# 安装（默认前缀 /usr/local）
sudo cmake --install build

# 若应用菜单里没有出现 GTodo，刷新桌面数据库
sudo update-desktop-database /usr/local/share/applications
```

### Windows（MSVC）

需要本机自备 `CMakeUserPresets.json`（不入仓，参考 `CMakeUserPresets.json.example`），在其中定义 `windows-msvc-local` 预设并写入本机 Qt 路径。

```bash
cmake --preset windows-msvc-local
cmake --build build

# 部署 Qt 运行时
%QT_DIR%\bin\windeployqt6.exe --qmldir qml build\bin\gtodo.exe

build\bin\gtodo.exe
```

日常开发用下节的 VS Code 配置即可（`Ctrl+Shift+B` 构建部署、`F5` 调试）。

### VS Code（Windows）

仓库内置 `.vscode/` 配置，目标是"打开即可构建 / 运行 / 调试"：CMake Tools 会在 configure 前自动加载 Visual Studio 开发环境（预设是 Ninja + `cl`，默认的 `auto` 策略即会触发），无需事先准备编译环境。

前置条件（本机自备）：

- Visual Studio（含 MSVC C++ 工具链）+ Windows SDK，能被 `vswhere` 发现即可；
- Qt 6 的 msvc 套件（如 `msvc2022_64`）；
- VS Code 扩展：`theqtcompany.qt`（Qt 官方扩展包，含 Qt Core / CPP / QML / UI，其中 qt-cpp 已依赖 CMake Tools）与 `ms-vscode.cpptools`（提供 `cppvsdbg` 调试器与 IntelliSense）。仓库**不内置** `.vscode/extensions.json`，扩展按需自行安装。

需要按本机情况修改的地方：

| 文件 | 入仓 | 需要改什么 |
|------|:---:|------------|
| `CMakeUserPresets.json` | ❌ | 定义 `windows-msvc-local` 预设，写入本机 Qt 路径 |
| `.vscode/settings.json` | ✅ | `cmake.configureEnvironment` / `cmake.buildEnvironment` 的 `QT_DIR`；`qt-qml.qmlls.additionalImportPaths` |
| `.vscode/tasks.json` | ✅ | `windeployqt` 任务的绝对路径 |
| `.vscode/c_cpp_properties.json` | ✅ | `compilerPath`（`cl.exe`）与 Qt `includePath` |

> 以上文件里的路径目前写成了本机绝对路径，**换机器时按上表逐项替换**。
> `QT_DIR` 通过 `configureEnvironment` / `buildEnvironment` 注入，因此无论 CMake Tools 选中 `windows-msvc` 还是 `windows-msvc-local`，Qt 都能被定位。

用法：

- 打开工程时自动 configure（`cmake.configureOnOpen: true`）；
- `Ctrl+Shift+B` → **Build & Deploy (Windows)**：编译 + `windeployqt` 部署；
- `F5` → **Debug GTodo (MSVC / Windows)**：先构建部署，再用 `cppvsdbg` 启动 `build/bin/gtodo.exe`。

排查：

| 症状 | 检查位置 |
|------|----------|
| 找不到 `cl` | VS/SDK 是否可被 `vswhere` 发现；实在不行可把 `cmake.useVsDeveloperEnvironment` 显式设为 `"always"` |
| `CMAKE_PREFIX_PATH` 为空 / 找不到 Qt | `QT_DIR`（`settings.json` 注入项、`CMakeUserPresets.json` 内的绝对路径） |
| `F5` 起不来 | `.vscode/launch.json` 的 `program` / `preLaunchTask` |
| 补全报错但能正常编译 | `.vscode/c_cpp_properties.json`（仅影响 IntelliSense，不影响构建） |

可选回退：`windows-mingw-local` 预设走 Qt 自带的 llvm-mingw 工具链，**不需要 VS / Windows SDK**，适合 MSVC 环境不可用时使用（构建产物同在 `build/`，切换前先清理该目录）。

### QML 语言服务（qmlls）配置

`.qmlls.ini` 是 qmlls（QML Language Server）与 Qt Creator 读取的项目配置，用于声明 QML import 路径（去哪些目录找 Qt 自带的 QML 模块）。该文件**由 CMake configure 自动生成**，路径取自 Qt 自身的安装信息（Qt6 用 `QT6_INSTALL_PREFIX` / `QT6_INSTALL_QML`，Qt5 或不提供该变量的打包方式回退到 `qmake -query QT_INSTALL_QML`），因此跨平台自动正确，**无需手工维护**。

- 模板：`resources/qmlls.ini.in`（入库）
- 生成位置：源码根目录（qmlls 会从工作目录向上查找该文件）
- 生成物**不入库**（见 `.gitignore`）；请勿手工编辑，重新 configure 会覆盖

> VS Code 的 Qt 扩展读的是 `.vscode/settings.json` 里的 `qt-qml.qmlls.additionalImportPaths`，与 `.qmlls.ini` 各管一条链路，互不影响。

## 架构概览

```
QML UI (qml/)  <--->  C++ 控制器 (src/)  <--->  SQLite
                          |
                          +-- WindowController   窗口状态（位置/吸附/展开/置顶）
                          +-- TodoRepository     TODO 数据模型（QAbstractListModel）
                          +-- TodoFilterModel    未完成/已完成 过滤模型
                          +-- SettingsManager    QSettings 持久化
                          +-- SingleInstance     单实例（QLocalServer/QLocalSocket）
                          +-- PlatformInterface  平台抽象（窗口标志/置顶/拖动/吸附）
                                ├─ X11Platform      xcb EWMH
                                ├─ WaylandPlatform  KWayland（PIMPL）
                                ├─ GenericPlatform  通用回退
                                └─ PlatformFactory  运行时选择
```

QML 侧主要文件：

- `qml/DockableMainWindow.qml` — 根窗口，边缘吸附 / 抽屉逻辑
- `qml/TodoList.qml` / `qml/TodoItem.qml` — 列表与条目
- `qml/AddTodoInput.qml` — 新增输入
- `qml/TitleBar.qml` — 标题栏按钮（置顶/最小化/关闭）

## 开发约定

- Wayland 适配的过程记录保存在 `docs/wayland`（一个适配过程一个文档，含行不通的方案）；Wayland 独立知识点保存在 `docs/knowledges`（英文短横线命名、中文撰写）。
- X11 任务栏集成说明：xcb 下 `X11Platform::applyShellIntegration()` 先设 `UTILITY` 类型、窗口显示后再设 `_NET_WM_STATE_SKIP_TASKBAR`（KWin 上两者缺一不可），无需按机器配置 KWin 规则。

## Wayland 适配情况

当前适配目标为 **KDE Plasma**，其他桌面环境暂未接触。详细适配过程（含行不通的方案）见 [`docs/wayland`](docs/wayland/)。

| 功能 | KDE | GNOME |
|------|-----|-------|
| 置顶（keep-above） | ✅ 已实现 | ❌ 未适配 |
| 抽屉式移动 | 🚧 适配中 | ❌ 未适配 |
| 位置记忆 | ❌ 未实现 | ❌ 未适配 |

## 仓库

- 主仓库：<https://gitee.com/gaobooo/gtodo>