STM32F4-Base/Drivers/BSP/UI/ui_page_action.c

/*
 * 模块名称：UI 动作确认页（操作页共享实现）实现
 * 模块功能：见 ui_page_action.h 头注释（确认链状态机 + 投递回报 + 表单页自绘）
 * 适用平台：STM32F407ZGTx / PC 模拟器（两端共用）
 * 作者：王建锋
 * 创建日期：2026-10-25
 * 修改记录：
 *     v1.0  2026-10-25  王建锋  创建（道B task-5 三组件之一）
 */

/* 头文件包含区 */
#include <string.h>

#include "ui_page_action.h"

#include "ui_content_page.h"

#include "ui_tokens.h"

/* 私有宏定义区 */

#define AC_PROMPT_Y     44      /* 问句/结果行 放置 y（内容区上三分之一） */
#define AC_STAGE_Y      66      /* 态标行（"二次确认" / "ERR"）放置 y */
#define AC_HINT_Y       110     /* 键提示行 放置 y */

/* 固定文案（用字均已入字体子集：二/次/确/认/取/消/返/回/越/界 及 ASCII） */
#define AC_STAGE2_TXT   "二次确认"
#define AC_HINT_DO      "ENTER=确认  ESC=取消"
#define AC_HINT_BACK    "ENTER=返回"
#define AC_ERR_TXT      "ERR"

/* 私有变量定义区 */

/*
 * 模块单例：内容页框架全局单页（s_open 互斥），同一时刻至多一张操作页，
 * 故钩子经"当前实例指针"取上下文即可成立（头注已载此约束；批 2 各跳板
 * 各自 static 实例、先后开页互不冲突）
 */
static ui_page_action_t *s_act;                 /* 当前实例（NULL = 未在用） */
static content_page_def_t s_desc;               /* 模板描述符（开页时按实例填充） */

/* 私有函数声明区 */

static void ac_draw_centered(lv_layer_t *a_layer, const char *a_text,
                             int32_t a_y, const lv_area_t *a_clip);

/* 函数定义区 */

/*
 * 函数功能：居中绘制单行文本（框架 cp_draw_centered_text 同法，本文件私有一致拷贝）
 * 入口参数：layer - 绘制层      lv_layer_t *
 *           text  - 文本（Flash 字面量）  const char *
 *           y     - 放置 y      int32_t
 *           clip  - 重绘区      const lv_area_t *
 * 返回值：无
 * 限定条件：text 非空；条带（整宽 x0..159，高 UI_TEXT_BAND_H）与 clip 相交才绘制
 */
static void ac_draw_centered(lv_layer_t *a_layer, const char *a_text,
                             int32_t a_y, const lv_area_t *a_clip) {
    lv_area_t t;
    lv_draw_label_dsc_t ld;

    /* 本 LVGL 版 lv_text_get_width：必须传 strlen（0 = 不测量返回 0，
     * 传 -1 越串尾死循环——框架同款注释警示） */
    t.x1 = 0;
    t.x2 = UI_SCREEN_W - 1;
    t.y1 = a_y;
    t.y2 = a_y + UI_TEXT_BAND_H;
    if (!((t.x1 <= a_clip->x2) && (a_clip->x1 <= t.x2) &&
          (t.y1 <= a_clip->y2) && (a_clip->y1 <= t.y2))) {
        return;    /* 不相交（culling） */
    }

    lv_draw_label_dsc_init(&ld);
    ld.base.layer = a_layer;
    ld.text = a_text;
    ld.text_static = 1u;    /* Flash 字面量：不拷内存 */
    ld.color = UI_COL_FG;
    ld.ofs_x = (UI_SCREEN_W -
                (int32_t)lv_text_get_width(a_text, (uint32_t)strlen(a_text), LV_FONT_DEFAULT, 0)) / 2;
    ld.ofs_y = 0;
    lv_draw_label(a_layer, &ld, &t);
}

/*
 * 函数功能：自绘（框架内置区块之后：问句/态标/键提示 三行居中）
 * 入口参数：layer - 绘制层      lv_layer_t *
 *           clip  - 重绘区      const lv_area_t *
 * 返回值：无
 * 限定条件：经描述符 draw_cb 挂接，页面打开中（s_act 有效）
 */
static void ac_draw_cb(lv_layer_t *layer, const lv_area_t *clip) {
    if ((s_act == NULL) || (s_act->prompt == NULL)) {
        return;
    }

    /* 行 1：问句（stage 2 换成功结果行） */
    if (s_act->stage == 2u) {
        if (s_act->done_text != NULL) {
            ac_draw_centered(layer, s_act->done_text, AC_PROMPT_Y, clip);
        }
    }
    else {
        ac_draw_centered(layer, s_act->prompt, AC_PROMPT_Y, clip);
    }

    /* 行 2：态标（二次确认 / 投递失败 ERR） */
    if (s_act->stage == 1u) {
        ac_draw_centered(layer, (s_act->err != 0u) ? AC_ERR_TXT : AC_STAGE2_TXT,
                         AC_STAGE_Y, clip);
    }

    /* 行 3：键提示 */
    ac_draw_centered(layer, (s_act->stage == 2u) ? AC_HINT_BACK : AC_HINT_DO,
                     AC_HINT_Y, clip);
}

/*
 * 函数功能：按键处理（确认链状态机）
 * 入口参数：key - LVGL 键值  lv_key_t
 * 返回值：true = 已消费；false = 交回框架（其余键忽略）
 * 限定条件：经描述符 key_cb 挂接（key_intercept=0：LEFT 直接关页 = 取消，
 *           不进本函数；ESC 恒关页框架保证，同样不进本函数）
 * 函数说明：ENTER：stage0 -> stage1（二次确认）；stage1 -> 投递 ok_cb：
 *           接受且有 done_text -> stage2 回报，接受且无 done_text -> 直接关页，
 *           拒收 -> err=1 留在 stage1；stage2 -> 关页返回
 */
static bool ac_key_cb(lv_key_t key) {
    if (key != LV_KEY_ENTER) {
        return false;
    }
    if (s_act == NULL) {
        return false;    /* 防御 */
    }

    if (s_act->stage == 0u) {
        s_act->stage = 1u;
        s_act->err = 0u;
        ui_content_page_invalidate();
        return true;
    }

    if (s_act->stage == 1u) {
        bool ok = false;

        if (s_act->ok_cb != NULL) {
            ok = s_act->ok_cb();    /* 只投递请求，不等待执行结果 */
        }
        if (!ok) {
            s_act->err = 1u;
            ui_content_page_invalidate();
            return true;    /* ERR 显示，再 ENTER 重试 */
        }
        if (s_act->done_text == NULL) {
            ui_content_page_close();    /* 成功即关页回菜单（无回报行形态） */
            return true;
        }
        s_act->stage = 2u;
        s_act->err = 0u;
        ui_content_page_invalidate();
        return true;
    }

    /* stage 2：已回报，ENTER 返回 */
    ui_content_page_close();
    return true;
}

/*
 * 函数功能：开操作页（装载实例 + 复位 + 框架开页）
 */
bsp_err_t ui_page_action_open(ui_page_action_t *a_inst, uint8_t a_perm) {
    if ((a_inst == NULL) || (a_inst->ok_cb == NULL) || (a_inst->prompt == NULL)) {
        return BSP_ERR_PARAM;
    }
    if (ui_content_page_is_open() != false) {
        return BSP_ERR_STATE;    /* 框架单页互斥的显式化（失败原因对跳板可判） */
    }

    s_act = a_inst;
    s_act->stage = 0u;    /* 每次进入固定从一次确认开始 */
    s_act->err = 0u;

    (void)memset(&s_desc, 0, sizeof(s_desc));
    s_desc.id = "action";
    s_desc.title = (a_inst->title != NULL) ? a_inst->title : a_inst->prompt;
    s_desc.hide_deco = 1u;         /* 表单/操作页形态：无浅 V（用户密钥页先例） */
    s_desc.hide_footer = 1u;       /* 无页脚页码 */
    s_desc.selectable = 0u;        /* 无行列表 */
    s_desc.key_intercept = 0u;     /* LEFT 不拦截：关页 = 取消 */
    s_desc.draw_cb = ac_draw_cb;
    s_desc.key_cb = ac_key_cb;

    if (ui_content_page_open(&s_desc, a_perm) == false) {
        s_act = NULL;    /* 开页失败不残留实例（钩子不会再被调） */
        return BSP_ERR_NO_SPACE;
    }
    return BSP_OK;
}