/*
 * 模块名称：UI Standby (待机显示页)
 * 模块功能：长时间无按键操作时自动切入的默认界面（6 路电流值 + 分隔线 + 底部时钟）；
 *           屏幕覆盖层模式——进入保存前屏与焦点、ENTER（确认键）还原，其余键忽略；
 *           空闲检测 = lv_timer（1s 周期），活动通知由菜单/内容页键事件挂钩
 * 适用平台：STM32F407ZGTx / PC 模拟器（两端共用）
 * 作者：王建锋
 * 创建日期：2026-09-14
 * 修改记录：
 *     v1.0  2026-09-14  王建锋  创建初始版本（设计见 docs/子系统设计/运行与自检记录设计说明.md §5.2）
 */

#ifndef UI_STANDBY_H
#define UI_STANDBY_H

#ifdef __cplusplus
extern "C" {
#endif

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

/*
 * 时间字符串提供回调（平台差异：MCU = sys_clock_get_str，模拟器 = 宿主 time()）
 */
typedef void (*ui_standby_time_cb)(char *buf, size_t len);

/*
 * 函数功能：初始化待机模块（建常驻屏/容器 + 空闲检测定时器）
 * 入口参数：idle_timeout_ms - 无操作超时阈值（ms；0 = 拒绝初始化）  uint32_t
 *           time_cb         - 底部时钟字符串提供回调（不可为 NULL）  ui_standby_time_cb
 * 返回值：0 - 成功；-1 - 失败（已初始化/参数无效/LVGL 池耗尽）  int
 * 限定条件：ui_menu_init() 已完成（默认输入组存在）；lv_tick_inc/lv_timer_handler 已被驱动
 */
int ui_standby_init(uint32_t idle_timeout_ms, ui_standby_time_cb time_cb);

/*
 * 函数功能：通知用户活动（重置空闲计时）
 * 入口参数：无
 * 返回值：无
 * 限定条件：ui_standby_init() 已成功；任意任务上下文（仅写一个时间戳）
 * 函数说明：菜单/内容页每收到一个键调用一次；待机屏上的按键同样经此重置
 */
void ui_standby_notify_activity(void);

/*
 * 函数功能：查询是否处于待机屏
 * 入口参数：无
 * 返回值：true - 待机中；false - 否
 * 限定条件：无
 */
bool ui_standby_is_active(void);

/*
 * 函数功能：强制进入待机屏（测试钩子，绕过空闲计时）
 * 入口参数：无
 * 返回值：无
 * 限定条件：ui_standby_init() 已成功；UI 任务上下文（模拟器无头回归用）
 */
void ui_standby_force_enter(void);

#ifdef __cplusplus
}
#endif

#endif /* UI_STANDBY_H */