/*
 * meow_ui_statusbar.h — SDK 全局状态栏 / 全屏（§3.1，A-0，系统级组件）。
 *
 * 原 meow_ui.h 拆分的一部分（statusbar 模块）。状态栏是 SDK 内置全局组件：默认显示（时钟/电量/
 * WiFi/蓝牙/音量），数据由 SDK 内置 meow_ui_sys 读取器 1s 轻刷（与 launcher 同源单点一致）。
 * z 顺序最顶：meow_ui_flush() 上屏前自动把状态栏画进 back_buf 顶部行，覆盖非全屏内容；
 * 非全屏 APP 需用 meow_ui_statusbar_height() 把内容下移（inset），否则被状态栏盖住。
 * 注：状态栏的**渲染**仅系统进程（launcher）执行；App 进程只按本头声明控制显隐/全屏/inset。
 */
#ifndef MEOW_UI_STATUSBAR_H
#define MEOW_UI_STATUSBAR_H

#include "meow_ui_types.h"

#ifdef __cplusplus
extern "C" {
#endif

/* ============================================================ */
/* §3.1 全局状态栏 / 全屏（A-0，SDK 系统级组件） */
/* ============================================================ */
/* 状态栏是 SDK 内置全局组件：所有界面默认显示（时钟/电量/WiFi/蓝牙/音量，slim ~40px），
 * 数据由 SDK 内置 meow_ui_sys 读取器 1s 轻刷（与 launcher 同源单点一致）。
 * z 顺序最顶：meow_ui_flush() 上屏前自动把状态栏画进 back_buf 顶部行，覆盖非全屏内容；
 * 非全屏 APP 需用 meow_ui_statusbar_height() 把内容下移（inset），否则被状态栏盖住。 */

/* 状态栏显隐（默认显示；APP 声明全屏则隐藏——沉浸）。 */
void meow_ui_set_statusbar(int visible);   /* 1=显示(默认) 0=隐藏(全屏) */
int  meow_ui_statusbar_visible(void);

/* 全屏声明：等价 app.json fullscreen:1（外观上隐藏状态栏 + 左缘返回手势/进度条——沉浸）。 */
void meow_ui_set_fullscreen(int on);

/* 状态栏高度（px，供 APP 布局上移内容，避免被盖——status bar inset）；
 * 全屏/隐藏时返回 0。 */
int  meow_ui_statusbar_height(void);

/* ---- 状态栏「上收出屏只留提示线」（collapsed，草案/待定案——本批仅加声明）----
 * 供全屏调用：把状态栏内容上移出屏顶、只留一条「提示线」高度（可下拉还原）。
 * 与 meow_ui_set_fullscreen(1) 的关系：fullscreen 隐藏整条状态栏（沉浸，inset=0）；
 * collapsed 仍视状态栏为「激活」，左缘返回手势（SWIPE_LEFT）与顶部伸缩提示线
 * （meow_ui_swipe_hint）依旧生效，只是其内容上收、仅留提示线——用于「不完全沉浸」，
 * 保留一处可下拉拉出状态栏的入口。顶部下滑热区 meow_ui_statusbar_hotzone() 在全屏时缩小。
 * 实现位置：meow_ui_gfx.c（基座让 on 生效：true→只画提示线/内容上移）；逐帧过渡动画
 * （上收/恢复插值）为待定案，后续代理可经 meow_ui_statusbar_animate(ms) 补齐。 */
void meow_ui_statusbar_set_collapsed(int on);   /* on=1 上收（内容上移出屏、只留提示线）；on=0 恢复 */
int  meow_ui_statusbar_collapsed(void);         /* 当前是否处于「上收」目标（1=是） */
void meow_ui_statusbar_animate(int ms);         /* TBD：上收/恢复过渡时长（ms）；占位，后续代理实现插值 */
/* 当前上收进度（0..MUI_SBAR_H：0=完全展开，28=内容全部上移出屏、仅留提示线）。
 * 供系统进程（launcher）在 App 前台叠加顶条时读取，按「当前可见条高 = 28-offset」
 * 标脏/切齐，实现收合时只 blit 可见条高、其余行保留 App 内容（平滑上收、无残留）。 */
int  meow_ui_statusbar_collapse_offset(void);
/* 上收/恢复过渡是否仍在进行（current offset != target，逐帧推进中）。
 * 供 launcher 在过渡期高频刷新顶条（launch_app 循环据此缩短 sleep），驱动平滑动画；稳定后回 1s 慢刷。 */
int  meow_ui_statusbar_animating(void);

/* 顶部下滑热区（下拉展开状态栏/通知）高度（px）。
 * 状态栏「激活」（含**收合**）时恒=整条状态栏高 MUI_SBAR_H（28）——收合只上收渲染、**不禁用顶部热区**
 * （渲染与热区事件分离，全屏下顶部下滑仍开通知中心）；仅「全屏隐藏」（immersive inset0）时缩小到
 * MEOW_SBAR_HOTZONE_FS（保留一处下拉入口）。返回「可用于起始下拉」的热区高度。 */
int  meow_ui_statusbar_hotzone(void);
#define MEOW_SBAR_HOTZONE_FS   4   /* 全屏时缩小后的顶部热区高度（px，草案值） */

#ifdef __cplusplus
}
#endif
#endif /* MEOW_UI_STATUSBAR_H */