# Pinyin IME (/widgets/ime_pinyin)



Pinyin IME provides an API to provide Chinese Pinyin input method (Chinese
input) for a Keyboard Widget, which supports both 26-key and 9-key input modes.
You can think of `lv_ime_pinyin` as a Pinyin input method plug-in for
the Keyboard Widget.

Normally, an environment where [Keyboard (lv\_keyboard)](/widgets/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.

Usage [#usage]

Enable <ApiLink name="LV_USE_IME_PINYIN" /> in `lv_conf.h`.

First use <ApiLink name="lv_ime_pinyin_create" display="lv_ime_pinyin_create(lv_screen_active())" /> to create a Pinyin
input-method plug-in, then use
<ApiLink name="lv_ime_pinyin_set_keyboard" display="lv_ime_pinyin_set_keyboard(pinyin_ime, kb)" /> to add the Keyboard Widget
you created to the Pinyin input method plug-in. You can use
<ApiLink name="lv_ime_pinyin_set_dict" display="lv_ime_pinyin_set_dict(pinyin_ime, your_dict)" /> to use a custom
dictionary.  If you don't want to use the built-in dictionary,
you can disable <ApiLink name="LV_IME_PINYIN_USE_DEFAULT_DICT" /> in `lv_conf.h`,
which can save a lot of memory space.

The built-in dictionary is customized based on the characters in the
**LV\_FONT\_SOURCE\_HAN\_SANS\_SC\_16\_CJK** font library, which currently has only
1,000 of the most common CJK radicals, so it is recommended to use a custom font
and a custom dictionary.

In the process of using the Pinyin input method plug-in, you can change
the Keyboard and dictionary at any time.

Custom Dictionary [#custom-dictionary]

If you don't want to use the built-in Pinyin dictionary, or if you feel that the
built-in phonetic dictionary consumes too much memory, you can use a custom dictionary.

Customizing the dictionary is very simple.

First, set <ApiLink name="LV_IME_PINYIN_USE_DEFAULT_DICT" /> to `0` in `lv_conf.h`

Then, write a dictionary in the following format.

Dictionary format [#dictionary-format]

The arrangement order of each pinyin syllable is very important. If you
need to customize your own dictionary according to the Hanyu Pinyin
syllable table, you can read
[here](https://baike.baidu.com/item/%E6%B1%89%E8%AF%AD%E6%8B%BC%E9%9F%B3%E9%9F%B3%E8%8A%82/9167981)
to learn about the Hanyu Pinyin syllables and the syllable table.

Then, write your own dictionary according to the following format:

```c title=" " lineNumbers=1
lv_pinyin_dict_t your_pinyin_dict[] = {
            { "a", "啊阿呵吖" },
            { "ai", "埃挨哎唉哀皑蔼矮碍爱隘癌艾" },
            { "an", "按安暗岸俺案鞍氨胺厂广庵揞犴铵桉谙鹌埯黯" },
            { "ang", "昂肮盎仰" },
            { "ao", "凹敖熬翱袄傲奥懊澳" },
            { "ba", "芭捌叭吧笆八疤巴拔跋靶把坝霸罢爸扒耙" },
            { "bai", "白摆佰败拜柏百稗伯" },
            /* ...... */
            { "zuo", "昨左佐做作坐座撮琢柞"},
            {NULL, NULL}
};
```

**The last item** must be `{NULL, NULL}`, or it will not work
properly.

Using a custom dictionary [#using-a-custom-dictionary]

After writing a dictionary according to the above dictionary format, you
only need to call this function to set up and use your dictionary:

```c title=" " lineNumbers=1
lv_obj_t * pinyin_ime = lv_ime_pinyin_create(lv_screen_active());
lv_ime_pinyin_set_dict(pinyin_ime, your_pinyin_dict);
```

Modes [#modes]

lv\_ime\_pinyin has the following modes:

* <ApiLink name="LV_IME_PINYIN_MODE_K26" />: Pinyin 26-key input mode
* <ApiLink name="LV_IME_PINYIN_MODE_K9" />: Pinyin 9-key input mode
* <ApiLink name="LV_IME_PINYIN_MODE_K9_NUMBER" />: Numeric keypad mode

The Keyboard's `TEXT`-mode layout contains buttons to change mode.

To set the mode manually, use <ApiLink name="lv_ime_pinyin_set_mode" display="lv_ime_pinyin_set_mode(pinyin_ime, mode)" />.
The default mode is <ApiLink name="LV_IME_PINYIN_MODE_K26" />.

Examples [#examples]

Pinyin IME 26 key input [#pinyin-ime-26-key-input]

<LvglExample name="lv_example_ime_pinyin_1" path="others/ime/lv_example_ime_pinyin_1" />

Pinyin IME 9 key input [#pinyin-ime-9-key-input]

<LvglExample name="lv_example_ime_pinyin_2" path="others/ime/lv_example_ime_pinyin_2" />

API [#api]