add: easylvgl,增加Dropdown, Keyboard, Msgbox, Switch 和 Textarea必要的注释

components/easylvgl/binding/luat_lib_easylvgl_dropdown.c

@@ -21,6 +21,20 @@
 
 #define EASYLVGL_DROPDOWN_MT "easylvgl.dropdown"
 
+/**
+ * 创建 Dropdown 组件
+ * @api easylvgl.dropdown(config)
+ * @table config 配置表
+ * @int config.x X 坐标，默认 0
+ * @int config.y Y 坐标，默认 0
+ * @int config.w 宽度，默认 140
+ * @int config.h 高度，默认 40
+ * @table config.options 选项列表（字符串数组）
+ * @int config.default_index 默认选中项索引，默认 -1
+ * @function config.on_change 选中项变化回调
+ * @userdata config.parent 父对象，可覆盖默认屏幕
+ * @return userdata Dropdown 对象，失败返回 nil
+ */
 static int l_easylvgl_dropdown(lua_State *L)
 {
     easylvgl_ctx_t *ctx = NULL;
@@ -47,6 +61,12 @@ static int l_easylvgl_dropdown(lua_State *L)
     return 1;
 }
 
+/**
+ * Dropdown:set_selected(index)
+ * @api dropdown:set_selected(index)
+ * @int index 选中项索引，0 起始
+ * @return nil
+ */
 static int l_dropdown_set_selected(lua_State *L)
 {
     lv_obj_t *dropdown = easylvgl_check_component(L, 1, EASYLVGL_DROPDOWN_MT);
@@ -55,6 +75,11 @@ static int l_dropdown_set_selected(lua_State *L)
     return 0;
 }
 
+/**
+ * Dropdown:get_selected()
+ * @api dropdown:get_selected()
+ * @return int 当前选中项索引
+ */
 static int l_dropdown_get_selected(lua_State *L)
 {
     lv_obj_t *dropdown = easylvgl_check_component(L, 1, EASYLVGL_DROPDOWN_MT);
@@ -63,6 +88,12 @@ static int l_dropdown_get_selected(lua_State *L)
     return 1;
 }
 
+/**
+ * Dropdown:set_on_change(callback)
+ * @api dropdown:set_on_change(callback)
+ * @function callback 选中项改变回调
+ * @return nil
+ */
 static int l_dropdown_set_on_change(lua_State *L)
 {
     lv_obj_t *dropdown = easylvgl_check_component(L, 1, EASYLVGL_DROPDOWN_MT);
@@ -73,6 +104,9 @@ static int l_dropdown_set_on_change(lua_State *L)
     return 0;
 }
 
+/**
+ * Dropdown GC（垃圾回收）
+ */
 static int l_dropdown_gc(lua_State *L)
 {
     easylvgl_component_ud_t *ud = (easylvgl_component_ud_t *)luaL_checkudata(L, 1, EASYLVGL_DROPDOWN_MT);
@@ -91,6 +125,10 @@ static int l_dropdown_gc(lua_State *L)
     return 0;
 }
 
+/**
+ * 注册 Dropdown 元表
+ * @param L Lua 状态
+ */
 void easylvgl_register_dropdown_meta(lua_State *L)
 {
     luaL_newmetatable(L, EASYLVGL_DROPDOWN_MT);
@@ -110,6 +148,9 @@ void easylvgl_register_dropdown_meta(lua_State *L)
     lua_pop(L, 1);
 }
 
+/**
+ * Dropdown 创建函数（供主模块注册）
+ */
 int easylvgl_dropdown_create(lua_State *L)
 {
     return l_easylvgl_dropdown(L);

components/easylvgl/binding/luat_lib_easylvgl_keyboard.c

@@ -18,6 +18,19 @@
 #define LUAT_LOG_TAG "easylvgl.keyboard"
 #include "luat_log.h"
 
+/**
+ * 创建 Keyboard 组件
+ * @api easylvgl.keyboard(config)
+ * @table config 配置表
+ * @int config.x X 坐标，默认 0
+ * @int config.y Y 坐标，默认 ctx->height-160（或 0）
+ * @int config.w 宽度，默认 ctx->width（或 480）
+ * @int config.h 高度，默认 160
+ * @string config.mode 键盘模式，如 "text"/"upper"/"special"/"numeric"
+ * @boolean config.popovers 是否启用提示弹窗，默认 true
+ * @userdata config.target 关联的 Textarea 对象，可选
+ * @return userdata Keyboard 对象，失败返回 nil
+ */
 static int l_easylvgl_keyboard(lua_State *L) {
     easylvgl_ctx_t *ctx = NULL;
     lua_getfield(L, LUA_REGISTRYINDEX, "easylvgl_ctx");
@@ -42,6 +55,12 @@ static int l_easylvgl_keyboard(lua_State *L) {
     return 1;
 }
 
+/**
+ * Keyboard:set_target(textarea)
+ * @api keyboard:set_target(textarea)
+ * @userdata textarea 目标 Textarea 对象
+ * @return nil
+ */
 static int l_keyboard_set_target(lua_State *L) {
     lv_obj_t *keyboard = easylvgl_check_component(L, 1, EASYLVGL_KEYBOARD_MT);
     lv_obj_t *textarea = easylvgl_check_component(L, 2, EASYLVGL_TEXTAREA_MT);
@@ -49,18 +68,34 @@ static int l_keyboard_set_target(lua_State *L) {
     return 0;
 }
 
+/**
+ * Keyboard:show()
+ * @api keyboard:show()
+ * @return nil
+ */
 static int l_keyboard_show(lua_State *L) {
     lv_obj_t *keyboard = easylvgl_check_component(L, 1, EASYLVGL_KEYBOARD_MT);
     easylvgl_keyboard_show(keyboard);
     return 0;
 }
 
+/**
+ * Keyboard:hide()
+ * @api keyboard:hide()
+ * @return nil
+ */
 static int l_keyboard_hide(lua_State *L) {
     lv_obj_t *keyboard = easylvgl_check_component(L, 1, EASYLVGL_KEYBOARD_MT);
     easylvgl_keyboard_hide(keyboard);
     return 0;
 }
 
+/**
+ * Keyboard:set_on_commit(callback)
+ * @api keyboard:set_on_commit(callback)
+ * @function callback 提交事件回调
+ * @return nil
+ */
 static int l_keyboard_set_on_commit(lua_State *L) {
     lv_obj_t *keyboard = easylvgl_check_component(L, 1, EASYLVGL_KEYBOARD_MT);
     luaL_checktype(L, 2, LUA_TFUNCTION);
@@ -70,6 +105,12 @@ static int l_keyboard_set_on_commit(lua_State *L) {
     return 0;
 }
 
+/**
+ * Keyboard:set_layout(layout)
+ * @api keyboard:set_layout(layout)
+ * @string layout 布局名称
+ * @return nil
+ */
 static int l_keyboard_set_layout(lua_State *L) {
     lv_obj_t *keyboard = easylvgl_check_component(L, 1, EASYLVGL_KEYBOARD_MT);
     const char *layout = luaL_checkstring(L, 2);
@@ -77,6 +118,11 @@ static int l_keyboard_set_layout(lua_State *L) {
     return 0;
 }
 
+/**
+ * Keyboard:get_target()
+ * @api keyboard:get_target()
+ * @return userdata|null 当前关联 Textarea
+ */
 static int l_keyboard_get_target(lua_State *L) {
     lv_obj_t *keyboard = easylvgl_check_component(L, 1, EASYLVGL_KEYBOARD_MT);
     easylvgl_component_meta_t *meta = easylvgl_component_meta_get(keyboard);
@@ -95,6 +141,9 @@ static int l_keyboard_get_target(lua_State *L) {
     return 1;
 }
 
+/**
+ * Keyboard GC（释放资源）
+ */
 static int l_keyboard_gc(lua_State *L) {
     easylvgl_component_ud_t *ud = (easylvgl_component_ud_t *)luaL_checkudata(L, 1, EASYLVGL_KEYBOARD_MT);
     if (ud != NULL && ud->obj != NULL) {
@@ -113,6 +162,10 @@ static int l_keyboard_gc(lua_State *L) {
     return 0;
 }
 
+/**
+ * 注册 Keyboard 元表
+ * @param L Lua 状态
+ */
 void easylvgl_register_keyboard_meta(lua_State *L) {
     luaL_newmetatable(L, EASYLVGL_KEYBOARD_MT);
 
@@ -134,6 +187,9 @@ void easylvgl_register_keyboard_meta(lua_State *L) {
     lua_pop(L, 1);
 }
 
+/**
+ * Keyboard 创建函数（供主模块注册）
+ */
 int easylvgl_keyboard_create(lua_State *L) {
     return l_easylvgl_keyboard(L);
 }

components/easylvgl/binding/luat_lib_easylvgl_msgbox.c

@@ -22,6 +22,10 @@
 
 #define EASYLVGL_MSGBOX_MT "easylvgl.msgbox"
 
+/**
+ * 清理 msgbox Lua 侧关联数据
+ * @param ud 组件用户数据
+ */
 static void easylvgl_msgbox_lua_cleanup(easylvgl_component_ud_t *ud)
 {
     if (ud == NULL || ud->obj == NULL) {
@@ -41,6 +45,19 @@ static void easylvgl_msgbox_lua_cleanup(easylvgl_component_ud_t *ud)
     ud->obj = NULL;
 }
 
+/**
+ * 创建 Msgbox 组件
+ * @api easylvgl.msgbox(config)
+ * @table config 配置表
+ * @string config.title 标题文本，可选
+ * @string config.text 内容文本，可选
+ * @boolean config.auto_center 是否自动居中，默认 true
+ * @int config.timeout 自动关闭时间（毫秒），默认 0
+ * @table config.buttons 按钮标签数组，默认 ["OK"]
+ * @function config.on_action 按钮点击回调
+ * @userdata config.parent 父对象，可选
+ * @return userdata Msgbox 对象，失败返回 nil
+ */
 static int l_easylvgl_msgbox(lua_State *L)
 {
     easylvgl_ctx_t *ctx = NULL;
@@ -66,6 +83,11 @@ static int l_easylvgl_msgbox(lua_State *L)
     return 1;
 }
 
+/**
+ * Msgbox:show()
+ * @api msgbox:show()
+ * @return nil
+ */
 static int l_msgbox_show(lua_State *L)
 {
     lv_obj_t *msgbox = easylvgl_check_component(L, 1, EASYLVGL_MSGBOX_MT);
@@ -73,6 +95,11 @@ static int l_msgbox_show(lua_State *L)
     return 0;
 }
 
+/**
+ * Msgbox:hide()
+ * @api msgbox:hide()
+ * @return nil
+ */
 static int l_msgbox_hide(lua_State *L)
 {
     lv_obj_t *msgbox = easylvgl_check_component(L, 1, EASYLVGL_MSGBOX_MT);
@@ -80,6 +107,12 @@ static int l_msgbox_hide(lua_State *L)
     return 0;
 }
 
+/**
+ * Msgbox:set_on_action(callback)
+ * @api msgbox:set_on_action(callback)
+ * @function callback 操作回调（按键 ID 传参）
+ * @return nil
+ */
 static int l_msgbox_set_on_action(lua_State *L)
 {
     lv_obj_t *msgbox = easylvgl_check_component(L, 1, EASYLVGL_MSGBOX_MT);
@@ -90,6 +123,11 @@ static int l_msgbox_set_on_action(lua_State *L)
     return 0;
 }
 
+/**
+ * Msgbox:release()
+ * @api msgbox:release()
+ * @return nil
+ */
 static int l_msgbox_release(lua_State *L)
 {
     easylvgl_component_ud_t *ud = (easylvgl_component_ud_t *)luaL_checkudata(L, 1, EASYLVGL_MSGBOX_MT);
@@ -99,6 +137,9 @@ static int l_msgbox_release(lua_State *L)
     return 0;
 }
 
+/**
+ * Msgbox GC（Lua 垃圾回收）
+ */
 static int l_msgbox_gc(lua_State *L)
 {
     easylvgl_component_ud_t *ud = (easylvgl_component_ud_t *)luaL_checkudata(L, 1, EASYLVGL_MSGBOX_MT);
@@ -106,6 +147,10 @@ static int l_msgbox_gc(lua_State *L)
     return 0;
 }
 
+/**
+ * 注册 Msgbox 元表
+ * @param L Lua 状态
+ */
 void easylvgl_register_msgbox_meta(lua_State *L)
 {
     luaL_newmetatable(L, EASYLVGL_MSGBOX_MT);
@@ -126,6 +171,9 @@ void easylvgl_register_msgbox_meta(lua_State *L)
     lua_pop(L, 1);
 }
 
+/**
+ * Msgbox 创建函数（供主模块注册）
+ */
 int easylvgl_msgbox_create(lua_State *L)
 {
     return l_easylvgl_msgbox(L);

components/easylvgl/binding/luat_lib_easylvgl_switch.c

@@ -19,6 +19,20 @@
 
 #define EASYLVGL_SWITCH_MT "easylvgl.switch"
 
+/**
+ * 创建 Switch 组件
+ * @api easylvgl.switch(config)
+ * @table config 配置表
+ * @int config.x X 坐标，默认 0
+ * @int config.y Y 坐标，默认 0
+ * @int config.w 宽度，默认 70
+ * @int config.h 高度，默认 40
+ * @boolean config.checked 初始状态，默认 false
+ * @string config.style 预设样式，如 "danger"/"success"
+ * @function config.on_change 状态变更回调
+ * @userdata config.parent 父对象，可选
+ * @return userdata Switch 对象，失败返回 nil
+ */
 static int l_easylvgl_switch(lua_State *L)
 {
     easylvgl_ctx_t *ctx = NULL;
@@ -44,6 +58,12 @@ static int l_easylvgl_switch(lua_State *L)
     return 1;
 }
 
+/**
+ * Switch:set_state(state)
+ * @api switch:set_state(state)
+ * @boolean state 勾选状态
+ * @return nil
+ */
 static int l_switch_set_state(lua_State *L)
 {
     lv_obj_t *sw = easylvgl_check_component(L, 1, EASYLVGL_SWITCH_MT);
@@ -52,6 +72,11 @@ static int l_switch_set_state(lua_State *L)
     return 0;
 }
 
+/**
+ * Switch:get_state()
+ * @api switch:get_state()
+ * @return boolean 当前状态
+ */
 static int l_switch_get_state(lua_State *L)
 {
     lv_obj_t *sw = easylvgl_check_component(L, 1, EASYLVGL_SWITCH_MT);
@@ -60,6 +85,12 @@ static int l_switch_get_state(lua_State *L)
     return 1;
 }
 
+/**
+ * Switch:set_on_change(callback)
+ * @api switch:set_on_change(callback)
+ * @function callback 状态变化回调
+ * @return nil
+ */
 static int l_switch_set_on_change(lua_State *L)
 {
     lv_obj_t *sw = easylvgl_check_component(L, 1, EASYLVGL_SWITCH_MT);
@@ -70,6 +101,9 @@ static int l_switch_set_on_change(lua_State *L)
     return 0;
 }
 
+/**
+ * Switch GC（释放 LVGL 对象）
+ */
 static int l_switch_gc(lua_State *L)
 {
     easylvgl_component_ud_t *ud = (easylvgl_component_ud_t *)luaL_checkudata(L, 1, EASYLVGL_SWITCH_MT);
@@ -84,6 +118,10 @@ static int l_switch_gc(lua_State *L)
     return 0;
 }
 
+/**
+ * 注册 Switch 元表
+ * @param L Lua 状态
+ */
 void easylvgl_register_switch_meta(lua_State *L)
 {
     luaL_newmetatable(L, EASYLVGL_SWITCH_MT);
@@ -103,6 +141,9 @@ void easylvgl_register_switch_meta(lua_State *L)
     lua_pop(L, 1);
 }
 
+/**
+ * Switch 创建函数（供主模块注册）
+ */
 int easylvgl_switch_create(lua_State *L)
 {
     return l_easylvgl_switch(L);

components/easylvgl/binding/luat_lib_easylvgl_textarea.c

@@ -22,6 +22,22 @@
  * Lua 接口定义
  ************************************************************************/
 
+/**
+ * 创建 Textarea 组件
+ * @api easylvgl.textarea(config)
+ * @table config 配置表
+ * @int config.x X 坐标，默认 0
+ * @int config.y Y 坐标，默认 0
+ * @int config.w 宽度，默认 ctx->width - x 或 200
+ * @int config.h 高度，默认 120
+ * @int config.max_len 最大字符数，默认 256
+ * @string config.text 初始文本
+ * @string config.placeholder 占位提示
+ * @function config.on_text_change 文本变更回调
+ * @table config.keyboard 内嵌 Keyboard 配置（table）
+ * @userdata config.parent 父对象，可选
+ * @return userdata Textarea 对象，失败返回 nil
+ */
 static int l_easylvgl_textarea(lua_State *L) {
     easylvgl_ctx_t *ctx = NULL;
     lua_getfield(L, LUA_REGISTRYINDEX, "easylvgl_ctx");
@@ -46,6 +62,12 @@ static int l_easylvgl_textarea(lua_State *L) {
     return 1;
 }
 
+/**
+ * Textarea:set_text(text)
+ * @api textarea:set_text(text)
+ * @string text 文本内容
+ * @return nil
+ */
 static int l_textarea_set_text(lua_State *L) {
     lv_obj_t *textarea = easylvgl_check_component(L, 1, EASYLVGL_TEXTAREA_MT);
     const char *text = luaL_checkstring(L, 2);
@@ -53,6 +75,11 @@ static int l_textarea_set_text(lua_State *L) {
     return 0;
 }
 
+/**
+ * Textarea:get_text()
+ * @api textarea:get_text()
+ * @return string 当前文本
+ */
 static int l_textarea_get_text(lua_State *L) {
     lv_obj_t *textarea = easylvgl_check_component(L, 1, EASYLVGL_TEXTAREA_MT);
     const char *text = easylvgl_textarea_get_text(textarea);
@@ -60,6 +87,12 @@ static int l_textarea_get_text(lua_State *L) {
     return 1;
 }
 
+/**
+ * Textarea:set_cursor(pos)
+ * @api textarea:set_cursor(pos)
+ * @int pos 光标位置
+ * @return nil
+ */
 static int l_textarea_set_cursor(lua_State *L) {
     lv_obj_t *textarea = easylvgl_check_component(L, 1, EASYLVGL_TEXTAREA_MT);
     uint32_t pos = (uint32_t)luaL_checkinteger(L, 2);
@@ -67,6 +100,12 @@ static int l_textarea_set_cursor(lua_State *L) {
     return 0;
 }
 
+/**
+ * Textarea:set_on_text_change(callback)
+ * @api textarea:set_on_text_change(callback)
+ * @function callback 文本变化回调
+ * @return nil
+ */
 static int l_textarea_set_on_change(lua_State *L) {
     lv_obj_t *textarea = easylvgl_check_component(L, 1, EASYLVGL_TEXTAREA_MT);
     luaL_checktype(L, 2, LUA_TFUNCTION);
@@ -76,6 +115,12 @@ static int l_textarea_set_on_change(lua_State *L) {
     return 0;
 }
 
+/**
+ * Textarea:attach_keyboard(keyboard)
+ * @api textarea:attach_keyboard(keyboard)
+ * @userdata keyboard Keyboard 对象
+ * @return nil
+ */
 static int l_textarea_attach_keyboard(lua_State *L) {
     lv_obj_t *textarea = easylvgl_check_component(L, 1, EASYLVGL_TEXTAREA_MT);
     lv_obj_t *keyboard = easylvgl_check_component(L, 2, EASYLVGL_KEYBOARD_MT);
@@ -83,6 +128,11 @@ static int l_textarea_attach_keyboard(lua_State *L) {
     return 0;
 }
 
+/**
+ * Textarea:get_keyboard()
+ * @api textarea:get_keyboard()
+ * @return userdata|null 当前绑定的 Keyboard
+ */
 static int l_textarea_get_keyboard(lua_State *L) {
     lv_obj_t *textarea = easylvgl_check_component(L, 1, EASYLVGL_TEXTAREA_MT);
     lv_obj_t *keyboard = easylvgl_textarea_get_keyboard(textarea);
@@ -94,6 +144,9 @@ static int l_textarea_get_keyboard(lua_State *L) {
     return 1;
 }
 
+/**
+ * Textarea GC（销毁组件）
+ */
 static int l_textarea_gc(lua_State *L) {
     easylvgl_component_ud_t *ud = (easylvgl_component_ud_t *)luaL_checkudata(L, 1, EASYLVGL_TEXTAREA_MT);
     if (ud != NULL && ud->obj != NULL) {
@@ -111,6 +164,10 @@ static int l_textarea_gc(lua_State *L) {
     return 0;
 }
 
+/**
+ * 注册 Textarea 元表
+ * @param L Lua 状态
+ */
 void easylvgl_register_textarea_meta(lua_State *L) {
     luaL_newmetatable(L, EASYLVGL_TEXTAREA_MT);
 
@@ -132,6 +189,9 @@ void easylvgl_register_textarea_meta(lua_State *L) {
     lua_pop(L, 1);
 }
 
+/**
+ * Textarea 创建函数（供主模块注册）
+ */
 int easylvgl_textarea_create(lua_State *L) {
     return l_easylvgl_textarea(L);
 }