/*
 * meow_ui_ime.h — SDK 输入法（§5.1，B1）：内置触屏软键盘。
 *
 * 原 meow_ui.h 拆分的一部分（ime 模块）。仅英文 QWERTY / 数字 / 中文拼音（ASCII/NUM/PINYIN）。
 * 输入事件循环/触摸命中优先级见 meow_ui_input.h 相关约定（IME 弹出时吞触摸）。
 */
#ifndef MEOW_UI_IME_H
#define MEOW_UI_IME_H

#include "meow_ui_types.h"

#ifdef __cplusplus
extern "C" {
#endif

/* ============================================================ */
/* §5.1 输入法（IME）—— 内置触屏软键盘（仅英文 QWERTY / 数字，ASCII） */
/* ============================================================ */
/* 输入法模式（尾部追加枚举：ASCII/NUM 值不变，零 ABI 回归）。PINYIN=中文拼音（meow_ui_ime.c）。 */
typedef enum { MEOW_IME_ASCII, MEOW_IME_NUM, MEOW_IME_PINYIN } meow_ime_mode;

typedef struct meow_ime_ctx {
    meow_ime_mode mode;
    char   buf[256];      /* 输入缓冲（初始值可预填） */
    int    maxlen;        /* 最大字符数（含 NUL 预算） */
    void (*on_change)(const char *text, void *ctx);   /* 每次字符变化回调一次 */
    void *ctx;
} meow_ime_ctx;

/* 阻塞：弹出键盘直到关闭（ESC / 点背景取消）；回车=只提交不关闭（内容经 on_change 实时同步）。
 * 关闭路径返回 0（取消）；提交内容经 on_change 回调逐键同步，不依赖返回值回填 buf。 */
int  meow_ui_text_input(meow_ime_ctx *ctx);

/* 非阻塞：返回后 app 在 on_tick 里轮询 meow_ime_active()/meow_ime_text() */
void meow_ui_text_input_async(meow_ime_ctx *ctx);
int  meow_ime_active(void);
const char *meow_ime_text(void);

/* 拼音模式组合态：当前拼音组合串（去声调小写，如 "nihao"）供 App 渲染字段预览；
 * 无组合（或非拼音模式）返回 ""。组合串是 IME 内部态，不写入字段（§4.2）。 */
const char *meow_ime_composition(void);

#ifdef __cplusplus
}
#endif
#endif /* MEOW_UI_IME_H */