MeowOS
e6f0b665e3
- 14 模块 .c + meow_launcher_internal.h(642): util/font_theme/fb_compositor/settings_page/power_menu/notif_center/app_launcher/main_menu/audio/backlight/net/keys/about/statusbar; meow_launcherd.c 已删 - 按行逐字搬移(0-diff), 118函数提升非static+47组extern(内部头), #if0退役区不编入(源码留.pre_split.bak) - 关于本机小改: 作者 AskaEth/17 + info/item[13]防越界 + s_dd_modal 超高滚动(clamp/触摸滚动/音量键跟随/裁剪, 仅超高启用) - build_launcher.sh 编译列表→模块; 文档/注释引用 meow_launcherd.c→模块/目录 - 编译0warning/-Wall -Wextra告警集与原文一致(77条无新增)/qemu-mipsel冒烟一致(--scan/--sysdump); launcher=c0799357(505KB; md5因多文件重编译与原文异,非回归依据) - 备份 meow_launcherd.c.pre_split.bak/meow_launcherd.pre_split.bak; M2.69(0.7.64)已推卡并用户验证OK
116 lines
9.7 KiB
Markdown
116 lines
9.7 KiB
Markdown
# MeowOS 应用返回手势与物理按键语义 —— 专项方案
|
||
|
||
> 状态：设计稿（2026-08-29）。目标：修三件事——① 去掉 APP 内的虚拟返回键（watchdog 顶部 48×48）；② 左滑返回**抬手才触发**；③ 左滑过程加**视觉反馈条**（顶部横条，长度=手指距左边缘）。并落实「物理按键语义系统统一管理、APP 禁映射」规范（见 APPS.md §3.4.1）。
|
||
|
||
---
|
||
|
||
## 0. 背景与问题定位
|
||
|
||
用户实测 SDK 版 hello（B1）反馈 3 个问题：
|
||
|
||
1. **左上角返回键太丑**——由 `meow_watchdog` 的 `paint_button()`（`meow_watchdog.c`）绘制，仅在 **非沉浸模式**（`/tmp/meowapp_state != "1"`）时每 100ms 重画。
|
||
2. **左滑返回"没松手就触发"**——实际看代码，watchdog 手势（`handle_touch` release edge 判 `SWIPE_DX`）与 SDK 手势（`meow_ui_input.c` `touch_release` 判 `SWIPE_THRESH`）**都是抬手触发**。但 hello 的 `on_swipe(LEFT)→request_exit()` 无条件处理左滑，加上 SDK 的 `SWIPE_THRESH=60px` 偏小 → 用户在"准备滑动"时 SDK 提前判成 swipe 发出 → 显得没抬手就返回。
|
||
3. **左滑无视觉反馈**——手势过程中没有任何可视化。
|
||
|
||
**根因链**：当前 hello 走「watchdog 非沉浸模式」（画返回键、watchdog 管手势）；但应用现在用 **SDK**（B1），SDK 有自己的手势。**两套手势/返回键并存**是乱象来源。**正确方向：应用返回/手势统一由 SDK 负责，watchdog 只留安全退出兜底，虚拟返回键删除。**
|
||
|
||
---
|
||
|
||
## 1. 核心设计：返回手势统一收到 SDK
|
||
|
||
**明确分工**：
|
||
|
||
| 组件 | 职责 | 改什么 |
|
||
|---|---|---|
|
||
| **SDK（meow_ui）** | APP 内返回手势（左滑）、视觉反馈条、触摸语义事件 | 手势抬手判定、新增 `on_swipe_progress` 回调、画顶部反馈条 |
|
||
| **watchdog（meow_watchdog）** | 仅安全兜底（卡死强杀）、沉浸前后台切换 | 删除返回键绘制（或仅保留"无返回键"）；APP 手势不再走 SIGUSR1 |
|
||
| **launcher** | app.json `immersive` → 写 `/tmp/meowapp_state` | 解析 `immersive` 字段写入状态文件 |
|
||
| **hello（示例）** | 删除 `on_key(KEY_POWER)→request_exit()` | 遵守 §3.4.1：物理键不映射 |
|
||
|
||
**沉浸模式**：APP 声明 `immersive:1` → launcher 写 `/tmp/meowapp_state=1` → watchdog 不画返回键 → 手势归 SDK。
|
||
|
||
---
|
||
|
||
## 2. 具体改动
|
||
|
||
### 2.1 虚拟返回键：删除（watchdog）
|
||
- `meow_watchdog.c`：**删除 `paint_button()` 的调用与返回键绘制逻辑**（顶部 48×48 按钮、`draw_arrow`、按钮区命中逻辑——211-217 行）。
|
||
- watchdog 保留：**app 卡死兜底强杀**（音量减×3 已存在）、app 存活检测（`kill(pid,0)`）。
|
||
- 删除后 watchdog 不再画任何 UI；APP 返回 100% 由 SDK 负责。**注意**：非沉浸模式下也从"画返回键+SIGTERM"退化为"无按钮"，仅触摸左滑返回（与沉浸统一）。若担心某些 APP 不用 SDK，它们仍走原 SIGUSR1/SIGTERM 兜底，但**helloS DK 版走 SDK 手势**。
|
||
|
||
### 2.2 左滑返回：抬手触发（SDK）
|
||
- `meow_ui_input.c` 的 `touch_release()`：**手势判定逻辑保持抬手触发**，但调优阈值与判定：
|
||
- `SWIPE_THRESH` 从 60 → **80~100**（更大容错，防止"摸索滑动"被误判）。
|
||
- 增加**方向限定**：左滑返回只认「**以左边 24px 边缘为起点**」（`t_dx < 24` 且 `mdx < -SWIPE_THRESH`），避免屏幕任意处左滑都退出。
|
||
- **抬手才 push_ev(MEOW_EV_SWIPE)**（已是）；补注释明确"release edge 才触发，按下/移动过程不触发"。
|
||
- `hello.c`：`on_swipe(LEFT)` 保留 `request_exit()`（这是 SDK 语义，不违反规范）；但判定由 SDK 收紧（左缘起点+大阈值）。
|
||
- **删除 `on_key(KEY_POWER)→request_exit()`**（违反 §3.4.1）：hello 不再因电源键退出；电源键在 APP 内=纯息屏（系统处理）。APP 退出走左滑/SDK 返回。
|
||
|
||
### 2.3 视觉反馈条（SDK 新增）
|
||
- 新增 SDK API：`void (*on_swipe_progress)(int x_start, int dx);`（触摸**按下后移动过程**实时回调，x_start=按下 X，dx=当前相对位移）。
|
||
- 输入线程在 `BTN_TOUCH` 按下后、且 `ABS_X` 更新时，若满足"`t_dx < EDGE_W(24)` 且当前 `t_cx < t_dx`（右滑/左滑方向）"→ 实时 `push_ev(MEOW_EV_SWIPE_PROGRESS, t_dx, t_cx)`。
|
||
- SDK 绘制层新增 `meow_ui_swipe_hint(int x)`：在**屏幕顶部**画一个「N 像素高的横条，从最左边缘向内延伸，长度 = 手指当前 X」：
|
||
- 形状：`fill_rect(0, 0, x, several_px, accent_color)`，高约 4~6px，用主题 accent 色（夜间高对比）。
|
||
- **实时联动**：每次 `on_swipe_progress` 更新画条（`flush_region` 只刷顶部条区域），抬手达标触发返回时条消失（触发行消失，回到 APP）。
|
||
- **视觉约束**：条仅"滑动过程中"可见；手指回到原点/抬手未达标 → 条消失。不做复杂动画（CPU 软渲），就是实时长度的横条。
|
||
|
||
### 2.4 app.json immersive 传递（launcher）
|
||
- launcher 解析 `app.json` 的 `immersive` 字段（布尔），应用启动时写 `/tmp/meowapp_state` = `1`/`0`；退出时清理。
|
||
- 当前 launcher 源码 grep `immersive` 无实现 → **新增**。SDK 应用默认声明 `immersive:1`（hello）。
|
||
|
||
---
|
||
|
||
## 3. 验收（宿主已验证项 + 真机待验证项）
|
||
|
||
> 本次为宿主验证（2026-08-29），未重启/刷真机。宿主验证通过项打 ✅；需真机确认的标「待真机」。
|
||
|
||
**已实现（宿主验证 ✅）**：SDK `meow_ui.a` 重编译通过；hello 链 `meow_ui.a` 重编译通过（MIPS32r2 静态）；launcher 编译+链接通过。
|
||
宿主 demo（`device_test/gesture_host_test.c`）验证：
|
||
|
||
- ✅ **视觉条**：`meow_ui_swipe_hint(x)` 在屏幕顶部画 5px、从 0 到 x 的 accent 横条；左滑过程 `MEOW_EV_SWIPE_PROGRESS` 实时上报 → SDK 自动画条（长度=当前 X），抬手达标清条。
|
||
- ✅ **抬手才返回**：`MEOW_EV_SWIPE`（release 边沿才 push）才触发 `on_swipe(LEFT)`；`MEOW_EV_SWIPE_PROGRESS` 只报进度不触发返回。
|
||
- ✅ **hello 不再因电源键退出**：`on_key(KEY_POWER)` 不再映射 `request_exit()`；宿主注入 POWER 键 → 仅 `on_key` 被调、app 未退出（随后注入左滑才退出）。
|
||
|
||
**待真机确认**：
|
||
1. **无返回键**：SDK hello（`app.json immersive:1`）左上角不再有 48×48 返回按钮 —— 待真机。
|
||
2. **抬手才返回**（真机手感）：左縁向内滑 ≥90px、松手后退出 —— 待真机。
|
||
3. **视觉条**（真机观感）：左滑过程中顶部横条随手指增长、抬手达标消失 —— 待真机。
|
||
4. **电源键息屏**：SDK hello 内按电源键=息屏（不退出 APP、不触发 OK）；再按=亮屏 —— 待真机。
|
||
5. **音量键**：SDK hello 内音量键=调音量（不选中/不返回）—— 待真机。
|
||
6. 触摸点按钮计数正常（回归）—— 待真机。
|
||
|
||
### ⚠️ 实现期定案（与设计稿 §2.2 的偏差，需知悉）
|
||
|
||
设计稿 §2.2 写「`t_dx < 24` 且 `mdx < -SWIPE_THRESH`（左滑）」。**该组合物理上不可达**：手指若从 ≤24px 的左缘启动，向左最多再走 ~24px 就到 x=0 边缘，位移永远达不到 90px。故实际采用 **「左縁起点 + 向右(向内)划 ≥90px」**（与 `meow_watchdog.c` immersive 兜底——左縁 rightward movement >50px——方向一致，二者才判定一致）：
|
||
|
||
- 事件上报：该左缘返回手势由 SDK 统一报为 **`MEOW_SWIPE_LEFT`**（`on_swipe` 的 dir=LEFT，hello 用 `on_swipe(LEFT)` 退出；「左滑=返回」契约保持）。
|
||
- 进度回调：`on_swipe_progress(x_start, dx)`，`dx = 当前X - 按下X`（dx>0=向内划，为返回手势方向）；SDK 自动画条长度=当前 X。
|
||
- 屏幕中部左/右滑**不是**返回手势（中部右滑→`MEOW_SWIPE_RIGHT`，中部左滑→落 TAP），避免任意处滑动误退出。
|
||
|
||
若真机实测发现手势方向相反（应为向左划），只需翻转 `touch_release()` 的 `mdx` 符号并同步 `on_swipe_progress` 说明即可，其余逻辑不变。
|
||
|
||
---
|
||
|
||
## 4. 关键约束（代理必读）
|
||
|
||
- **绝不**把 APP 内的物理键（电源/音量/播放）映射成任何"确认/exit/返回/翻页"。物理键语义看 APPS.md §3.4.1：电源=息屏/亮屏、音量=调音量、播放=媒体。**只有 MeowOS 界面（launcher 菜单）允许处理物理键语义。**
|
||
- 渲染走 `back_buf + meow_present`（SDK 现有机制），无闪烁；视觉条用 `fill_rect` + `flush_region` 刷顶部一小条即可，不做全屏重绘。
|
||
- 不碰 launcher 主循环的物理键处理（那是 MeowOS 界面，允许）；只改 SDK 的手势 + watchdog 返回键绘制 + launcher 的 app.json immersive 解析。
|
||
- `meow_watchdog` 是独立进程，**改它不影响 SDK**；但确认删除返回键后它仍能兜底（app 卡死强杀）。
|
||
|
||
---
|
||
|
||
## 5. 涉及文件
|
||
|
||
| 文件 | 改动 |
|
||
|---|---|
|
||
| `patch_v2/sdk/meow_ui_input.c` | 抬手触发收紧（左缘起点+阈值 80-100）、新增 `on_swipe_progress` 上报 |
|
||
| `patch_v2/sdk/meow_ui.h` | 新增 `MEOW_SWIPE_PROGRESS` 事件 + `on_swipe_progress` 回调签名 |
|
||
| `patch_v2/sdk/meow_ui_gfx.c` | 新增 `meow_ui_swipe_hint(x)` 顶部横条绘制 |
|
||
| `patch_v2/sdk/meow_ui_widget.c`（如有输入/绘制分发） | 分发 `on_swipe_progress` |
|
||
| `patch_v2/meow_watchdog/meow_watchdog.c` | 删除 `paint_button()` 返回键绘制/按钮命中；保留兜底 |
|
||
| `patch_v2/meow_launcherd/app_launcher.c`（`meow_write_app_state`/`launch_app`） | 解析 app.json `immersive` → 写 `/tmp/meowapp_state` |
|
||
| `patch_v2/hello_app/hello.c` | 删 `on_key(KEY_POWER)→exit`；声明 immersive；处理 `on_swipe_progress` 画条 |
|
||
| `patch_v2/apps_assets/apps/os.meow.hello/app.json` | 加 `"immersive":1` |
|
||
| `APPS.md` / `MEOW_APP_SDK.md` | 已写 §3.4.1 规范；SDK 文档补 `on_swipe_progress`/`meow_ui_swipe_hint` |
|