/*
 * 模块名称：UI 数值编辑共享组件（ui_w_editor）
 * 模块功能：把"定点整数值（单位 = 10^decimals）的逐位编辑"收成一份可复用实现——
 *           进/退编辑、按光标位 ±1 步进（上加下减）、左右移数字光标（首末环绕）、
 *           ENTER 提交（范围校验：越界拒绝并显示"越界"提示、留在编辑态）；
 *           ESC 不处理（内容页框架恒拦截关页，未提交调整随之丢弃 = 取消）；
 *           编辑光标反显绘制与 ui_page_net_cfg 的字节光标同一画法；
 *           只持渲染与输入抽象，不碰任何数据源——工作值经 ui_w_editor_value()
 *           交回调用方（ui_w_setlist）统一写 RAM 副本
 * 适用范围：Drivers/BSP/UI（列表页骨架几何由调用方传入，组件不自带）
 * 说明：实例化使用（一个实例同一时刻只编一个值），调用方持有 ui_w_editor_t
 *      实例——多个整定页各自独立实例，不跨页串态（同 ui_w_records 的
 *      按实例存态教训）；值一律非负（min >= 0 为使用前提，本工程定值全非负）
 * 作者：王建锋
 * 创建日期：2026-10-25
 * 修改记录：
 *     v1.0  2026-10-25  王建锋  创建（并行分道方案 §5.2 道B task-5：定值整定的
 *                               数值编辑前置能力，规格 = 页面扩充详细方案.md §3.2.7
 *                               编辑交互表 + 页面补齐规划.md §3.2 能力表）
 */
#ifndef UI_W_EDITOR_H
#define UI_W_EDITOR_H

#ifdef __cplusplus
extern "C" {
#endif

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

#include "lvgl.h"

/* 数值编辑器实例（值用定点整数表达：单位 = 10^decimals，
 * 如 10.24 A / decimals=2 -> 1024）
 * 用法：调用方（页面 / ui_w_setlist）持有实例，进编辑前 begin() 载值与范围，
 *      其余字段清零 = 非编辑态 */
typedef struct {
    int32_t min;              /* 下限（含；单位 10^decimals） */
    int32_t max;              /* 上限（含） */
    int32_t cur;              /* 工作值（编辑中实时变；未提交不回写数据源） */
    uint8_t decimals;         /* 小数位数 0..3 */
    uint8_t editing;          /* 1 = 编辑中 */
    uint8_t bad;              /* 1 = 上次 ENTER 越界被拒（"越界"提示亮，下一次编辑键清除） */
    uint8_t digit;            /* 数字光标：第几个十进制数字字符（0 = 最高位） */
    uint8_t ndigits;          /* 当前值串的数字字符数（begin/步进时重算） */
} ui_w_editor_t;

/*
 * 函数功能：进入编辑（载入初始值与范围，光标落在个位）
 * 入口参数：inst     - 编辑器实例        ui_w_editor_t *
 *           value    - 初始值（单位 10^decimals）  int32_t
 *           min_v    - 下限（含；>= 0）  int32_t
 *           max_v    - 上限（含）        int32_t
 *           decimals - 小数位数 0..3     uint8_t
 * 返回值：无
 * 限定条件：非编辑态调用；编辑中重复调用 = 先复位再进新值的编辑
 */
void ui_w_editor_begin(ui_w_editor_t *a_inst, int32_t a_value,
                       int32_t a_min_v, int32_t a_max_v, uint8_t a_decimals);

/*
 * 函数功能：复位实例（清除编辑态与提示；页面 init_cb 开页时调用）
 * 入口参数：inst - 编辑器实例  ui_w_editor_t *
 * 返回值：无
 * 限定条件：无
 */
void ui_w_editor_reset(ui_w_editor_t *a_inst);

/*
 * 函数功能：查询是否处于编辑态
 * 入口参数：inst - 编辑器实例  const ui_w_editor_t *
 * 返回值：true = 编辑中  bool
 * 限定条件：inst 非空（空按非编辑态处理）
 */
bool ui_w_editor_is_editing(const ui_w_editor_t *a_inst);

/*
 * 函数功能：编辑态按键处理
 * 入口参数：inst - 编辑器实例  ui_w_editor_t *
 *           key  - LVGL 键值   lv_key_t
 * 返回值：1 = 已消费（上下步进 / 左右移光标 / ENTER 提交或拒绝）；
 *                  0 = 未消费（非编辑态调用，或方向键与 ENTER 之外的键）
 *                  （键分发标志非错误通道，取 uint8_t 不用 bool——BSP 公开
 *                  API 约定，见 bsp-err/err-type）
 * 限定条件：非编辑态调用本函数恒返回 false（编辑态把守由调用方负责）
 * 函数说明：1. 上下：当前光标位数字 +1/-1（0 与 9 环绕、无进位——越界由 ENTER 把关）
 *           2. 左右：数字光标首末环绕
 *           3. ENTER：范围校验通过 -> 退出编辑（提交值经 ui_w_editor_value 取回，
 *              写回 RAM 副本由调用方负责）；越界 -> 拒绝退出、置"越界"提示，
 *              下一次任意编辑键先清提示
 *           4. ESC 不到达本函数（内容页框架恒拦截关页 = 取消本次编辑，
 *              工作值随 begin 丢弃，不落任何数据源）
 */
uint8_t ui_w_editor_key(ui_w_editor_t *a_inst, lv_key_t a_key);

/*
 * 函数功能：取工作值
 * 入口参数：inst - 编辑器实例  const ui_w_editor_t *
 * 返回值：当前工作值（单位 10^decimals；inst 为空返回 0——直返数值形态，
 *                  无错误通道）  int32_t
 * 限定条件：编辑中与提交后均可取（提交判定 = 调用方观察 is_editing 变 false）
 */
int32_t ui_w_editor_value(const ui_w_editor_t *a_inst);

/*
 * 函数功能：把当前工作值格式化为显示串（"10.24" / "500"）
 * 入口参数：inst - 编辑器实例        const ui_w_editor_t *
 *           buf  - 输出缓冲（建议 >= UI_BUF_STRLEN）  char *
 *           len  - 缓冲长度（含 NUL）                 uint32_t
 * 返回值：无
 * 限定条件：buf 非空；decimals <= 3
 * 函数说明：与内部绘制共用同一格式化口径（刷新值列与光标定位同串一致）
 */
void ui_w_editor_format(const ui_w_editor_t *a_inst, char *a_buf, uint32_t a_len);

/*
 * 函数功能：把任意定点整数值格式化为显示串（共享格式化单一规则源：
 *           组件内部 ed_format 与本函数同一实现，值列显示与编辑光标天然同串）
 * 入口参数：value    - 定点值（单位 10^decimals；非负）  int32_t
 *           decimals - 小数位数 0..3                     uint8_t
 *           buf      - 输出缓冲                          char *
 *           len      - 缓冲长度（含 NUL）                uint32_t
 * 返回值：无
 * 限定条件：buf 非空
 */
void ui_w_editor_fmt_scaled(int32_t a_value, uint8_t a_decimals, char *a_buf, uint32_t a_len);

/*
 * 函数功能：编辑态自绘（数字光标反显盒 + "越界"提示），在框架内置区块之后调用
 * 入口参数：inst    - 编辑器实例    ui_w_editor_t *
 *           layer   - 绘制层        lv_layer_t *
 *           clip    - 重绘区        const lv_area_t *
 *           row_top - 被编辑行行槽顶 y（调用方按列表骨架 + 当前页窗口换算）  int32_t
 *           text_dy - 行文本垂直偏移（= 描述符 text_dy，通常 0）              int32_t
 *           band_h  - 选中白带高（反显盒高沿用，= 描述符 band_h）             int32_t
 *           value_x - 值列 x（= 描述符 right_x）                              int32_t
 * 返回值：无
 * 限定条件：编辑中才绘制（非编辑态空操作）；被编辑行在当前页窗口内由调用方保证
 * 函数说明：1bpp 极性：反显 = 白底（UI_COL_SEL_BG）盒 + 黑字（UI_COL_SEL_FG）
 *           重画光标位单字符（与 ui_page_net_cfg 编辑光标同法，含 culling；
 *           只画单字符：整串传入会被 LVGL 按盒宽折行溢出到邻行——net_cfg 实测坑）
 */
void ui_w_editor_draw(ui_w_editor_t *a_inst, lv_layer_t *a_layer,
                      const lv_area_t *a_clip, int32_t a_row_top,
                      int32_t a_text_dy, int32_t a_band_h, int32_t a_value_x);

#ifdef __cplusplus
}
#endif

#endif /* UI_W_EDITOR_H */