/*
 * 模块名称：UI 定值查看视图模型（ui_w_setview）
 * 模块功能：参数 / 定值 / 控制字 / 软压板**四张视图表**与它们的取数、越界反显——
 *           把"40 项定值怎么分组上屏、Q10 怎么换算成带小数位的显示值"收在一处，
 *           供四个查看页薄跳板（ui_page_view_*）共用；整定页（下一批）复用同一批表，
 *           只是再绑 set/commit/state 三个回调
 * 分层：本模块只读 Drivers/BSP/UI/ui_data.h 的参数快照，**不 include 任何 App 头**
 *       （行表里的 id 是**裸数字** + 注释标注 PS_* 名，因为 prot_set_id_t 属 App 层）
 *       ——id 与 App/algo/prot_set.h 枚举序的一致性由 test/host/ui_data 的主机单测
 *       在两侧头文件同时可见的地方钉住（BSP 侧看不到 App 头，物理上无法自证）
 * 值语义：q10[i] = 工程量 × 1024（App/app/ui_data_feed.c 只搬原值不换算，换算属表现层，
 *       docs/UI设计/UI_数据供给设计说明.md §8），本模块按行表 decimals 换算成
 *       "工程量 × 10^decimals" 交给 ui_w_setlist（其值通道契约）
 * 适用平台：STM32F407ZGTx / PC 模拟器（共用源码）
 * 作者：王建锋
 * 创建日期：2026-10-25
 * 修改记录：
 *     v1.0  2026-10-25  王建锋  创建（道E task-15 批 3；规格 =
 *                               docs/UI设计/页面扩充详细方案.md §3.2.1~§3.2.3/§3.2.6）
 */
#ifndef UI_W_SETVIEW_H
#define UI_W_SETVIEW_H

#ifdef __cplusplus
extern "C" {
#endif

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

#include "ui_w_setlist.h"

/* 四个视图编号 */
typedef enum {
    UI_W_SETVIEW_PARAM = 0,   /* 参数视图 8 行（PT/CT 额定 + 4 个返回系数） */
    UI_W_SETVIEW_SET,         /* 定值视图 18 行（电流/电压/频率/延时） */
    UI_W_SETVIEW_WORD,        /* 控制字视图 4 行（*_TRIP：告警/跳闸） */
    UI_W_SETVIEW_PLATE,       /* 软压板视图 10 行（*_EN + 保护总投：投入/退出） */
    UI_W_SETVIEW_VIEWS        /* 哨兵 = 视图个数（不是有效视图号） */
} ui_w_setview_t;

/*
 * 函数功能：绑定一个查看视图到定值表实例（rows/count/get/bad 一次配齐）
 * 入口参数：a_inst - 页面持有的实例（static，一页一份）  ui_w_setlist_t *
 *           a_view - 视图编号  ui_w_setview_t
 * 返回值：无
 * 限定条件：页面 init_cb 内调用（uiTask 上下文）
 * 函数说明：查看视图与整定视图的**唯一**差别就是这里绑不绑 set/commit/state：
 *           commit=NULL → 组件不画保存行、ENTER 无效（§3.2.6 查看列口径）；
 *           set 契约写"必填"，故绑一个空实现而不是 NULL——组件在只读态确实不会调它，
 *           但把"当前不会调"当成"可以是 NULL"等于把安全性押在下一次重构上
 */
void ui_w_setview_attach(ui_w_setlist_t *a_inst, ui_w_setview_t a_view);

/*
 * 函数功能：按发布序号取参数帧快照（页面 refresh 前调用）
 * 入口参数：无
 * 返回值：无
 * 限定条件：uiTask 上下文（页面绘制链内）
 * 函数说明：序号没变就不重拷（一帧约 184 B；四个查看页共用这一份缓存——同屏只可能
 *           开着一页，缓存互相之间不存在并发读者）
 */
void ui_w_setview_sync(void);

/*
 * 函数功能：参数帧是否已就位
 * 入口参数：无
 * 返回值：1 = 有有效帧可显示；0 = 尚无首帧或读取失败  uint8_t（取 uint8_t 是 BSP 公开
 *         API 的 err-type 约定，不是错误通道；定义处有完整理由）
 * 限定条件：uiTask 上下文；纯查询，无副作用
 * 函数说明：页面据此决定值列打 "--" 还是打换算值——**无数据不许打 0**：
 *           "0.00A" 会被读成"这台装置的定值就是 0"，与"还不知道"是两件事
 */
uint8_t ui_w_setview_ready(void);

/*
 * 函数功能：逐行取数（接框架 refresh；内含 ui_w_setview_sync() 与无帧占位）
 * 入口参数：a_inst  - 已 attach 的实例  ui_w_setlist_t *
 *           a_row   - 全局行下标  uint16_t
 *           a_name  - 名输出缓冲（UI_BUF_STRLEN）  char *
 *           a_value - 值输出缓冲  char *
 * 返回值：无
 * 限定条件：框架绘制链内调用（uiTask）
 * 函数说明：页面**不要**直接调 ui_w_setlist_refresh()——那样会绕过"无帧打 --"
 *           这一步，参数帧还没到就把 0 当成定值显示出去
 */
void ui_w_setview_refresh(ui_w_setlist_t *a_inst, uint16_t a_row,
                          char *a_name, char *a_value);

/*
 * 函数功能：取某视图的行表与行数（供主机单测做结构自测；页面正常不需要调用）
 * 入口参数：a_view - 视图编号  ui_w_setview_t；a_n - 行数输出（不可为 NULL）  uint16_t *
 * 返回值：行表首地址；视图号非法或 a_n 为空返回 NULL  const ui_w_setlist_row_t *
 * 限定条件：只读
 */
const ui_w_setlist_row_t *ui_w_setview_table(ui_w_setview_t a_view, uint16_t *a_n);

/*
 * 函数功能：取 id → 显示小数位查表（供主机单测核对行表与查表一致）
 * 入口参数：a_n - 表长输出（= UI_DATA_SET_N）  uint16_t *
 * 返回值：表首地址  const uint8_t *
 * 限定条件：只读
 */
const uint8_t *ui_w_setview_dec_table(uint16_t *a_n);

#ifdef __cplusplus
}
#endif

#endif /* UI_W_SETVIEW_H */