119 lines
4.3 KiB
C
119 lines
4.3 KiB
C
/**
|
||
****************************************************************************************************
|
||
* @file app.h
|
||
* @author HiFi Player Project
|
||
* @version V1.2
|
||
* @date 2026-01-01
|
||
* @brief 应用管理器：主界面（应用启动器）/ 各 App 切换 + 全局按键服务
|
||
*
|
||
* 设计目的：
|
||
* 把“哪个界面在运行”和“按键归谁处理”从各 App 里抽出来。
|
||
* 新增应用（设置、相册、录音等）只需要：
|
||
* 1) 在 app_mode_t 里加一个模式；
|
||
* 2) 在 app.c 的 s_apps[] 表里加一条记录；
|
||
* 3) 新建自己的文件夹（如 APP/clock/），实现 ui_clock_create/show/tick/handle_key，
|
||
* 并在 ui.c 的路由表里挂上。
|
||
*
|
||
* 按键语义（由 ui.c 统一实现）：
|
||
* K0 短按 = 返回主界面（主界面时为切换下一个应用）
|
||
* K0 长按 = 直接切换到下一个应用
|
||
* K1/K2/K3 = 由各 App 自己定义
|
||
*
|
||
* 例外：实现了 ui_xxx_back() 的 App（如文件管理器）可以先用 K0 短按
|
||
* 完成“就地返回”（返回上一级目录），只有到顶层时才回主界面。
|
||
****************************************************************************************************
|
||
*/
|
||
|
||
#ifndef __APP_H
|
||
#define __APP_H
|
||
|
||
#include <stdbool.h>
|
||
#include <stdint.h>
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
/* ---------------- 应用（界面）模式 ---------------- */
|
||
typedef enum {
|
||
APP_MODE_HOME = 0, /* 主界面：应用启动器 */
|
||
APP_MODE_PLAYER, /* 音乐播放器 */
|
||
APP_MODE_FILES, /* 文件管理器：浏览 SD 卡目录 */
|
||
APP_MODE_NUM, /* 模式总数（新增应用请加在这之前） */
|
||
} app_mode_t;
|
||
|
||
#define APP_MODE_NONE APP_MODE_NUM /* “无对应界面”（禁用的表项使用） */
|
||
|
||
/* ---------------- 4 个物理按键（XL9555 的 KEY0~KEY3） ---------------- */
|
||
typedef enum {
|
||
APP_KEY_0 = 0, /* KEY0 */
|
||
APP_KEY_1, /* KEY1 */
|
||
APP_KEY_2, /* KEY2 */
|
||
APP_KEY_3, /* KEY3 */
|
||
APP_KEY_NUM
|
||
} app_key_t;
|
||
|
||
/* ---------------- 按键事件类型 ---------------- */
|
||
typedef enum {
|
||
APP_KEY_SHORT = 0, /* 短按（松开时上报） */
|
||
APP_KEY_LONG, /* 长按（按住达到阈值立即上报，松开不再上报短按） */
|
||
} app_key_event_t;
|
||
|
||
typedef struct {
|
||
uint8_t key; /* app_key_t */
|
||
uint8_t type; /* app_key_event_t */
|
||
} app_event_t;
|
||
|
||
/* ---------------- 主界面应用表项 ---------------- */
|
||
typedef struct {
|
||
const char *icon; /* 图标字形（LV_SYMBOL_xxx） */
|
||
const char *title; /* 图标下方名称 */
|
||
const char *subtitle; /* 选中时显示的说明（可选，NULL 表示不显示） */
|
||
app_mode_t mode; /* 进入后切到的模式（APP_MODE_NONE 表示尚未实现） */
|
||
bool enabled; /* 是否可进入 */
|
||
uint32_t color_from; /* 图标渐变起始色（顶部） */
|
||
uint32_t color_to; /* 图标渐变结束色（底部） */
|
||
} app_entry_t;
|
||
|
||
/**
|
||
* @brief 初始化应用管理器（创建按键服务任务与事件队列）
|
||
* @note 必须在 xl9555_init() 之后调用
|
||
*/
|
||
void app_start(void);
|
||
|
||
/* ---------------- 模式 ---------------- */
|
||
app_mode_t app_get_mode(void);
|
||
|
||
/**
|
||
* @brief 切换应用模式
|
||
* @note 切换时会清空按键事件队列，避免上一次界面的按键“漏”到新界面
|
||
*/
|
||
void app_set_mode(app_mode_t mode);
|
||
|
||
/** 返回主界面（已在主界面时无动作） */
|
||
void app_back(void);
|
||
|
||
/**
|
||
* @brief 切换到“下一个可用的应用"
|
||
* @retval true 切换成功；false 没有其它可切换的应用
|
||
* @note 主界面 K0、以及在任意 App 内长按 K0 都会调用它
|
||
*/
|
||
bool app_switch_next(void);
|
||
|
||
/* ---------------- 主界面应用表 ---------------- */
|
||
const app_entry_t *app_get_entries(int *count);
|
||
|
||
int app_get_selection(void);
|
||
void app_select_move(int delta); /* 在当前应用表中循环移动选择项 */
|
||
|
||
/* ---------------- 按键事件 ---------------- */
|
||
bool app_event_poll(app_event_t *ev); /* 非阻塞 */
|
||
bool app_event_wait(app_event_t *ev, uint32_t timeout_ms); /* 阻塞等待 */
|
||
void app_event_flush(void); /* 清空队列 */
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
|
||
#endif /* __APP_H */
|