feat(ime_pinyin): add API to support 9-key input mode (#3447)

* feat(ime_pinyin): add API to support 9-key input mode

* some optimizations for lv_ime_pinyin

* Update lv_example_ime_pinyin_2.c

* Update src/extra/others/ime/lv_ime_pinyin.h

Co-authored-by: YobeZhou <smilezyb@163.com>
Co-authored-by: Yobe Zhou <33565334+YobeZhou@users.noreply.github.com>
Co-authored-by: Gabor Kiss-Vamosi <kisvegabor@gmail.com>

Kconfig

@@ -1030,14 +1030,22 @@ menu "LVGL configuration"
         config LV_USE_IME_PINYIN
             bool "Enable Pinyin input method"
             default n
+        config LV_IME_PINYIN_USE_K9_MODE
+            bool "Enable Pinyin input method 9 key input mode"
+            depends on LV_USE_IME_PINYIN
+            default n
+        config LV_IME_PINYIN_K9_CAND_TEXT_NUM
+            int "Maximum number of candidate panels for 9-key input mode"
+            depends on LV_IME_PINYIN_USE_K9_MODE
+            default 3
         config LV_IME_PINYIN_USE_DEFAULT_DICT
             bool "Use built-in Thesaurus"
             depends on LV_USE_IME_PINYIN
             default y
             help
-                If you do not use the default thesaurus, be sure to use `lv_ime_pinyin` after setting the thesauruss
+                If you do not use the default thesaurus, be sure to use lv_ime_pinyin after setting the thesauruss
         config LV_IME_PINYIN_CAND_TEXT_NUM
-            int "maximum number of candidate panels"
+            int "Maximum number of candidate panels"
             depends on LV_USE_IME_PINYIN
             default 6
             help

docs/others/ime_pinyin.md

@@ -1,6 +1,6 @@
 # Pinyin IME
 
-Pinyin IME provides API to provide Chinese Pinyin input method (Chinese input) for keyboard object. You can think of `lv_ime_pinyin` as a Pinyin input method plug-in for keyboard objects.
+Pinyin IME provides API to provide Chinese Pinyin input method (Chinese input) for keyboard object, which supports 26 key and 9 key input modes. You can think of `lv_ime_pinyin` as a Pinyin input method plug-in for keyboard objects.
 
 Normally, an environment where [lv_keyboard](/widgets/extra/keyboard) can run can also run `lv_ime_pinyin`. There are two main influencing factors: the size of the font file and the size of the dictionary.
 
@@ -8,7 +8,7 @@ Normally, an environment where [lv_keyboard](/widgets/extra/keyboard) can run ca
 <summary>中文</summary>
 <p>
             
-`lv_ime_pinyin`为[键盘](/widgets/extra/keyboard)组件提供汉语拼音输入法（中文输入）的功能(后文简称为拼音输入法)。您可以将 `lv_ime_pinyin` 看成是键盘组件的汉语拼音输入法插件。
+`lv_ime_pinyin`为[键盘](/widgets/extra/keyboard)组件提供汉语拼音输入法（中文输入）的功能(后文简称为拼音输入法)，支持26键和9键输入模式。您可以将 `lv_ime_pinyin` 看成是键盘组件的汉语拼音输入法插件。
  
 一般情况下，只要是[键盘](/widgets/extra/keyboard)组件能运行的环境 `lv_ime_pinyin` 也能运行。有两个影响因素：字库的大小和词库的大小。
             
@@ -118,6 +118,20 @@ After writing a dictionary according to the above dictionary format, you only ne
     lv_100ask_pinyin_ime_set_dict(pinyin_ime, your_pinyin_dict);
 ```
 
+## Input modes
+
+`lv_ime_pinyin` supports 26 key and 9 key input modes. The mode switching is very simple, just call the function `lv_ime_pinyin_set_mode`. If the second parameter of function `lv_ime_pinyin_set_mode` is' 1 ', switch to 26 key input mode; if it is' 0', switch to 9 key input mode, and the default is' 1 '.
+
+<details>
+<summary>中文</summary>
+<p>
+
+`lv_ime_pinyin` 支持26键和9键输入模式。模式的切换非常简单，只需调用函数 `lv_ime_pinyin_set_mode` 即可。如果函数 `lv_ime_pinyin_set_mode` 的第2个参数为 `1` 则切换到 26 键输入模式，如果为 `0` 则切换到 9 键输入法模式，默认为 `1` 。
+
+</p>
+</details>
+
+
 ## Example
 
 ```eval_rst

examples/others/ime/index.rst

@@ -1,8 +1,12 @@
 
-Simple Pinyin IME example 
+Pinyin IME 26 key input
-"""""""""""""""""""
+"""""""""""""""""""""""""
 
 .. lv_example:: others/ime/lv_example_ime_pinyin_1
   :language: c
 
+Pinyin IME 9 key input
+"""""""""""""""""""""""""
 
+.. lv_example:: others/ime/lv_example_ime_pinyin_2
+  :language: c

examples/others/ime/lv_example_ime_pinyin.h

@@ -26,6 +26,7 @@ extern "C" {
  * GLOBAL PROTOTYPES
  **********************/
 void lv_example_ime_pinyin_1(void);
+void lv_example_ime_pinyin_2(void);
 
 /**********************
  *      MACROS

examples/others/ime/lv_example_ime_pinyin_1.c

@@ -1,5 +1,5 @@
 #include "../../lv_examples.h"
-#if LV_USE_LABEL && LV_USE_TEXTAREA && LV_FONT_SIMSUN_16_CJK  && LV_USE_IME_PINYIN && LV_BUILD_EXAMPLES
+#if LV_USE_LABEL && LV_USE_TEXTAREA && LV_FONT_SIMSUN_16_CJK && LV_USE_IME_PINYIN && LV_BUILD_EXAMPLES
 
 static void ta_event_cb(lv_event_t * e)
 {
@@ -13,7 +13,7 @@ static void ta_event_cb(lv_event_t * e)
             lv_obj_clear_flag(kb, LV_OBJ_FLAG_HIDDEN);
         }
     }
-    else if(code == LV_EVENT_READY || code == LV_EVENT_CANCEL) {
+    else if(code == LV_EVENT_CANCEL) {
         lv_obj_add_flag(kb, LV_OBJ_FLAG_HIDDEN);
         lv_obj_clear_state(ta, LV_STATE_FOCUSED);
         lv_indev_reset(NULL, ta);   /*To forget the last clicked object to make it focusable again*/
@@ -24,7 +24,7 @@ void lv_example_ime_pinyin_1(void)
 {
     lv_obj_t * pinyin_ime = lv_ime_pinyin_create(lv_scr_act());
     lv_obj_set_style_text_font(pinyin_ime, &lv_font_simsun_16_cjk, 0);
-    //lv_ime_pinyin_set_dict(pinyin_ime, your_dict); // Use a custom dictionary. If it is not set, the built-in thesaurus will be used.
+    //lv_ime_pinyin_set_dict(pinyin_ime, your_dict); // Use a custom dictionary. If it is not set, the built-in dictionary will be used.
 
     /* ta1 */
     lv_obj_t * ta1 = lv_textarea_create(lv_scr_act());

examples/others/ime/lv_example_ime_pinyin_2.c

@@ -0,0 +1,58 @@
+#include "../../lv_examples.h"
+#if LV_USE_LABEL && LV_USE_TEXTAREA && LV_FONT_SIMSUN_16_CJK && LV_USE_IME_PINYIN && LV_IME_PINYIN_USE_K9_MODE && LV_BUILD_EXAMPLES
+
+static void ta_event_cb(lv_event_t * e)
+{
+    lv_event_code_t code = lv_event_get_code(e);
+    lv_obj_t * ta = lv_event_get_target(e);
+    lv_obj_t * kb = lv_event_get_user_data(e);
+
+    if(code == LV_EVENT_FOCUSED) {
+        if(lv_indev_get_type(lv_indev_get_act()) != LV_INDEV_TYPE_KEYPAD) {
+            lv_keyboard_set_textarea(kb, ta);
+            lv_obj_clear_flag(kb, LV_OBJ_FLAG_HIDDEN);
+        }
+    }
+    else if(code == LV_EVENT_READY) {
+        lv_obj_add_flag(kb, LV_OBJ_FLAG_HIDDEN);
+        lv_obj_clear_state(ta, LV_STATE_FOCUSED);
+        lv_indev_reset(NULL, ta);   /*To forget the last clicked object to make it focusable again*/
+    }
+}
+
+void lv_example_ime_pinyin_2(void)
+{
+    lv_obj_t * pinyin_ime = lv_ime_pinyin_create(lv_scr_act());
+    lv_obj_set_style_text_font(pinyin_ime, &lv_font_simsun_16_cjk, 0);
+    //lv_ime_pinyin_set_dict(pinyin_ime, your_dict); // Use a custom dictionary. If it is not set, the built-in dictionary will be used.
+
+    /* ta1 */
+    lv_obj_t * ta1 = lv_textarea_create(lv_scr_act());
+    lv_textarea_set_one_line(ta1, true);
+    lv_obj_set_style_text_font(ta1, &lv_font_simsun_16_cjk, 0);
+    lv_obj_align(ta1, LV_ALIGN_TOP_LEFT, 0, 0);
+
+    /*Create a keyboard and add it to ime_pinyin*/
+    lv_obj_t * kb = lv_keyboard_create(lv_scr_act());
+    lv_keyboard_set_textarea(kb, ta1);
+
+    lv_ime_pinyin_set_keyboard(pinyin_ime, kb);
+    lv_ime_pinyin_set_mode(pinyin_ime,
+                           LV_IME_PINYIN_MODE_K9);  // Set to 9-key input mode. Default: 26-key input(k26) mode.
+    lv_obj_add_event_cb(ta1, ta_event_cb, LV_EVENT_ALL, kb);
+
+    /*Get the cand_panel, and adjust its size and position*/
+    lv_obj_t * cand_panel = lv_ime_pinyin_get_cand_panel(pinyin_ime);
+    lv_obj_set_size(cand_panel, LV_PCT(100), LV_PCT(10));
+    lv_obj_align_to(cand_panel, kb, LV_ALIGN_OUT_TOP_MID, 0, 0);
+
+    /*Try using ime_pinyin to output the Chinese below in the ta1 above*/
+    lv_obj_t * cz_label = lv_label_create(lv_scr_act());
+    lv_label_set_text(cz_label,
+                      "嵌入式系统（Embedded System），\n是一种嵌入机械或电气系统内部、具有专一功能和实时计算性能的计算机系统。");
+    lv_obj_set_style_text_font(cz_label, &lv_font_simsun_16_cjk, 0);
+    lv_obj_set_width(cz_label, 310);
+    lv_obj_align_to(cz_label, ta1, LV_ALIGN_OUT_BOTTOM_LEFT, 0, 0);
+}
+
+#endif

lv_conf_template.h

@@ -704,6 +704,12 @@
     /*Set the maximum number of candidate panels that can be displayed*/
     /*This needs to be adjusted according to the size of the screen*/
     #define LV_IME_PINYIN_CAND_TEXT_NUM 6
+
+    /*Use 9 key input(k9)*/
+    #define LV_IME_PINYIN_USE_K9_MODE      1
+    #if LV_IME_PINYIN_USE_K9_MODE == 1
+        #define LV_IME_PINYIN_K9_CAND_TEXT_NUM 3
+    #endif // LV_IME_PINYIN_USE_K9_MODE
 #endif
 
 /*==================

src/extra/others/ime/lv_ime_pinyin.h

@@ -19,29 +19,49 @@ extern "C" {
 /*********************
  *      DEFINES
  *********************/
+#define LV_IME_PINYIN_K9_MAX_INPUT  7
 
 /**********************
  *      TYPEDEFS
  **********************/
+
+typedef enum {
+    LV_IME_PINYIN_MODE_K26,
+    LV_IME_PINYIN_MODE_K9,
+} lv_ime_pinyin_mode_t;
+
+/*Data of pinyin_dict*/
 typedef struct {
     const char * const py;
     const char * const py_mb;
 } lv_pinyin_dict_t;
 
+/*Data of 9-key input(k9) mode*/
+typedef struct {
+    char py_str[7];
+} ime_pinyin_k9_py_str_t;
+
 /*Data of lv_ime_pinyin*/
 typedef struct {
     lv_obj_t obj;
     lv_obj_t * kb;
     lv_obj_t * cand_panel;
     lv_pinyin_dict_t * dict;
+    lv_ll_t k9_legal_py_ll;
     char * cand_str;            /* Candidate string */
-    char * btnm_pinyin_sel[LV_IME_PINYIN_CAND_TEXT_NUM + 3];
+    char   input_char[16];      /* Input box character */
-    char   input_char[16];        /* Input box character */
+#if LV_IME_PINYIN_USE_K9_MODE
+    char   k9_input_str[LV_IME_PINYIN_K9_MAX_INPUT]; /* 9-key input(k9) mode input string */
+    uint16_t k9_py_ll_pos;      /* Current pinyin map pages(k9) */
+    uint16_t k9_legal_py_count; /* Count of legal Pinyin numbers(k9) */
+    uint16_t k9_input_str_len;  /* 9-key input(k9) mode input string max len */
+#endif
     uint16_t ta_count;          /* The number of characters entered in the text box this time */
     uint16_t cand_num;          /* Number of candidates */
-    uint16_t py_page;           /* Current pinyin map pages */
+    uint16_t py_page;           /* Current pinyin map pages(k26) */
     uint16_t py_num[26];        /* Number and length of Pinyin */
     uint16_t py_pos[26];        /* Pinyin position */
+    uint8_t  mode : 1;          /* Set mode, 1: 26-key input(k26), 0: 9-key input(k9). Default: 1. */
 } lv_ime_pinyin_t;
 
 /***********************
@@ -71,6 +91,13 @@ void lv_ime_pinyin_set_keyboard(lv_obj_t * obj, lv_obj_t * kb);
  */
 void lv_ime_pinyin_set_dict(lv_obj_t * obj, lv_pinyin_dict_t * dict);
 
+/**
+ * Set mode, 26-key input(k26) or 9-key input(k9).
+ * @param obj  pointer to a Pinyin input method object
+ * @param mode   the mode from 'lv_ime_pinyin_mode_t'
+ */
+void lv_ime_pinyin_set_mode(lv_obj_t * obj, lv_ime_pinyin_mode_t mode);
+
 
 /*=====================
  * Getter functions
@@ -115,3 +142,4 @@ lv_pinyin_dict_t * lv_ime_pinyin_get_dict(lv_obj_t * obj);
 
 #endif /*LV_USE_IME_PINYIN*/
 
+

src/lv_conf_internal.h

@@ -2288,6 +2288,28 @@
             #define LV_IME_PINYIN_CAND_TEXT_NUM 6
         #endif
     #endif
+
+    /*Use 9 key input(k9)*/
+    #ifndef LV_IME_PINYIN_USE_K9_MODE
+        #ifdef _LV_KCONFIG_PRESENT
+            #ifdef CONFIG_LV_IME_PINYIN_USE_K9_MODE
+                #define LV_IME_PINYIN_USE_K9_MODE CONFIG_LV_IME_PINYIN_USE_K9_MODE
+            #else
+                #define LV_IME_PINYIN_USE_K9_MODE 0
+            #endif
+        #else
+            #define LV_IME_PINYIN_USE_K9_MODE      1
+        #endif
+    #endif
+    #if LV_IME_PINYIN_USE_K9_MODE == 1
+        #ifndef LV_IME_PINYIN_K9_CAND_TEXT_NUM
+            #ifdef CONFIG_LV_IME_PINYIN_K9_CAND_TEXT_NUM
+                #define LV_IME_PINYIN_K9_CAND_TEXT_NUM CONFIG_LV_IME_PINYIN_K9_CAND_TEXT_NUM
+            #else
+                #define LV_IME_PINYIN_K9_CAND_TEXT_NUM 3
+            #endif
+        #endif
+    #endif // LV_IME_PINYIN_USE_K9_MODE
 #endif
 
 /*==================