后板第一次提交

lvgl_v8_back/lvgl/docs/others/fragment.md

@@ -0,0 +1,77 @@
+
+# Fragment
+
+Fragment is a concept copied from [Android](https://developer.android.com/guide/fragments).
+
+It represents a reusable portion of your app's UI. A fragment defines and manages its own layout, has its own lifecycle,
+and can handle its own events. Like Android's Fragment that must be hosted by an activity or another fragment, Fragment
+in LVGL needs to be hosted by an object, or another fragment. The fragment’s view hierarchy becomes part of, or attaches
+to, the host’s view hierarchy.
+
+Such concept also has some similarities
+to [UiViewController on iOS](https://developer.apple.com/documentation/uikit/uiviewcontroller).
+
+Fragment Manager is a manager holding references to fragments attached to it, and has an internal stack to achieve
+navigation. You can use fragment manager to build navigation stack, or multi pane application easily.
+
+## Usage
+
+Enable `LV_USE_FRAGMENT` in `lv_conf.h`.
+
+### Create Fragment Class
+
+```c
+struct sample_fragment_t {
+    /* IMPORTANT: don't miss this part */
+    lv_fragment_t base;
+    /* States, object references and data fields for this fragment */
+    const char *title;
+};
+
+const lv_fragment_class_t sample_cls = {
+        /* Initialize something needed */
+        .constructor_cb = sample_fragment_ctor,
+        /* Create view objects */
+        .create_obj_cb = sample_fragment_create_obj,
+        /* IMPORTANT: size of your fragment struct */
+        .instance_size = sizeof(struct sample_fragment_t)
+};
+```
+
+### Use `lv_fragment_manager`
+
+```c
+/* Create fragment instance, and objects will be added to container */
+lv_fragment_manager_t *manager = lv_fragment_manager_create(container, NULL);
+/* Replace current fragment with instance of sample_cls, and init_argument is user defined pointer */
+lv_fragment_manager_replace(manager, &sample_cls, init_argument);
+```
+
+### Fragment Based Navigation
+
+```c
+/* Add one instance into manager stack. View object of current fragment will be destroyed,
+ * but instances created in class constructor will be kept.
+ */
+lv_fragment_manager_push(manager, &sample_cls, NULL);
+
+/* Remove the top most fragment from the stack, and bring back previous one. */
+lv_fragment_manager_pop(manager);
+```
+
+## Example
+
+```eval_rst
+
+.. include:: ../../examples/others/fragment/index.rst
+
+```
+
+## API
+
+```eval_rst
+
+.. doxygenfile:: lv_fragment.h
+  :project: lvgl
+
+```

lvgl_v8_back/lvgl/docs/others/gridnav.md

@@ -0,0 +1,56 @@
+# Grid navigation
+
+Grid navigation (gridnav for short) is a feature that changes the currently focused child object as arrow keys are pressed.
+
+If the children are arranged into a grid-like layout then the up, down, left and right arrows move focus to the nearest sibling
+in the respective direction.
+
+It doesn't matter how the children are positioned, as only the current x and y coordinates are considered.
+This means that gridnav works with manually positioned children, as well as [Flex](/layouts/flex) and [Grid](/layouts/grid) layouts.
+
+Gridnav also works if the children are arranged into a single row or column.
+That makes it useful, for example, to simplify navigation on a [List widget](/widgets/extra/list).
+
+Gridnav assumes that the object to which gridnav is added is part of a [group](/overview/indev.html#groups).
+This way, if the object with gridnav is focused, the arrow key presses are automatically forwarded to the object
+so that gridnav can process the arrow keys.
+
+To move the focus to the next widget of the group use `LV_KEY_NEXT/PREV` or `lv_group_focus_next/prev()` or the `TAB` key on keyboard as usual.
+
+If the container is scrollable and the focused child is out of the view, gridnav will automatically scroll the child into view.
+
+## Usage
+
+To add the gridnav feature to an object use `lv_gridnav_add(cont, flags)`.
+
+`flags` control the behavior of gridnav:
+- `LV_GRIDNAV_CTRL_NONE` Default settings
+- `LV_GRIDNAV_CTRL_ROLLOVER`  If there is no next/previous object in a direction,
+the focus goes to the object in the next/previous row (on left/right keys) or first/last row (on up/down keys
+- `LV_GRIDNAV_CTRL_SCROLL_FIRST` If an arrow is pressed and the focused object can be scrolled in that direction
+then it will be scrolled instead of going to the next/previous object.  If there is no more room for scrolling the next/previous object will be focused normally
+
+`lv_gridnav_remove(cont)` Removes gridnav from an object.
+
+## Focusable objects
+
+An object needs to be clickable or click focusable (`LV_OBJ_FLAG_CLICKABLE` or `LV_OBJ_FLAG_CLICK_FOCUSABLE`)
+and not hidden (`LV_OBJ_FLAG_HIDDEN`) to be focusable by gridnav.
+
+
+## Example
+
+```eval_rst
+
+.. include:: ../../examples/others/gridnav/index.rst
+
+```
+## API
+
+
+```eval_rst
+
+.. doxygenfile:: lv_gridnav.h
+  :project: lvgl
+
+```

lvgl_v8_back/lvgl/docs/others/ime_pinyin.md

@@ -0,0 +1,150 @@
+# Pinyin IME
+
+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.
+
+<details>
+<summary>中文</summary>
+<p>
+            
+`lv_ime_pinyin`为[键盘](/widgets/extra/keyboard)组件提供汉语拼音输入法（中文输入）的功能(后文简称为拼音输入法)，支持26键和9键输入模式。您可以将 `lv_ime_pinyin` 看成是键盘组件的汉语拼音输入法插件。
+ 
+一般情况下，只要是[键盘](/widgets/extra/keyboard)组件能运行的环境 `lv_ime_pinyin` 也能运行。有两个影响因素：字库的大小和词库的大小。
+            
+</p>
+</details>
+
+## Usage
+
+Enable `LV_USE_IME_PINYIN` in `lv_conf.h`.
+
+First use `lv_ime_pinyin_create(lv_scr_act())` to create a Pinyin input method plug-in, then use `lv_ime_pinyin_set_keyboard(pinyin_ime, kb)` to add the `keyboard` you created to the Pinyin input method plug-in.
+You can use `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 at first, you can disable `LV_IME_PINYIN_USE_DEFAULT_DICT` in `lv_conf.h`, which can save a lot of memory space).
+
+The built-in thesaurus is customized based on the **LV_FONT_SIMSUN_16_CJK** font library, which currently only has more than `1,000` most common CJK radicals, so it is recommended to use custom fonts and thesaurus.
+
+In the process of using the Pinyin input method plug-in, you can change the keyboard and dictionary at any time.
+
+<details>
+<summary>中文</summary>
+<p>
+            
+在 `lv_conf.h` 中打开 `LV_USE_IME_PINYIN`。
+            
+首先，使用 `lv_ime_pinyin_create(lv_scr_act())` 函数创建一个拼音输入法插件，
+然后使用 `lv_ime_pinyin_set_keyboard(pinyin_ime, kb)` 函数将您创建的键盘组件添加到插件中。
+
+内置的词库是基于 LVGL 的 **LV_FONT_SIMSUN_16_CJK** 字库定制，这个字库目前只有 `1000` 多个最常见的 CJK 部首，所以建议使用自定义字库和词库。
+
+您可以使用 `lv_ime_pinyin_set_dict(pinyin_ime, your_dict)` 函数来设置使用自定义的词库，如果您一开始就不打算使用内置的词库，建议您在 `lv_conf.h` 中将 `LV_IME_PINYIN_USE_DEFAULT_DICT` 关闭，这可以节省一些内存空间。
+
+</p>
+</details>
+
+## Custom dictionary
+
+If you don't want to use the built-in Pinyin dictionary, you can use the custom dictionary.
+Or if you think that the built-in phonetic dictionary consumes a lot of memory, you can also use a custom dictionary.
+
+Customizing the dictionary is very simple.
+
+First, set `LV_IME_PINYIN_USE_DEFAULT_DICT` to `0` in `lv_conf.h`
+
+Then, write a dictionary in the following format.
+
+<details>
+<summary>中文</summary>
+<p>
+            
+如果您不想使用内置的词库，可以通过下面的方法自定义词库。
+
+自定义词典非常简单。
+首先，在 `lv_conf.h` 将 `LV_IME_PINYIN_USE_DEFAULT_DICT` 设置为 0。
+然后按照下面的格式编写词库。
+
+</p>
+</details>
+
+### Dictionary format
+
+The arrangement order of each pinyin syllable is very important. You need to customize your own thesaurus 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:
+
+<details>
+<summary>中文</summary>
+<p>
+
+**注意**，各个拼音音节的排列顺序非常重要，您需要按照汉语拼音音节表定制自己的词库，可以阅读[这里](https://baike.baidu.com/item/%E6%B1%89%E8%AF%AD%E6%8B%BC%E9%9F%B3%E9%9F%B3%E8%8A%82/9167981)了解[汉语拼音音节](https://baike.baidu.com/item/%E6%B1%89%E8%AF%AD%E6%8B%BC%E9%9F%B3%E9%9F%B3%E8%8A%82/9167981)以及[音节表](https://baike.baidu.com/item/%E6%B1%89%E8%AF%AD%E6%8B%BC%E9%9F%B3%E9%9F%B3%E8%8A%82/9167981#1)。
+
+然后，根据下面的格式编写自己的词库：
+
+</p>
+</details>
+
+```c
+lv_100ask_pinyin_dict_t your_pinyin_dict[] = {
+            { "a", "啊阿呵吖" },
+            { "ai", "埃挨哎唉哀皑蔼矮碍爱隘癌艾" },
+            { "an", "按安暗岸俺案鞍氨胺厂广庵揞犴铵桉谙鹌埯黯" },
+            { "ang", "昂肮盎仰" },
+            { "ao", "凹敖熬翱袄傲奥懊澳" },
+            { "ba", "芭捌叭吧笆八疤巴拔跋靶把坝霸罢爸扒耙" },
+            { "bai", "白摆佰败拜柏百稗伯" },
+            /* ...... */
+            { "zuo", "昨左佐做作坐座撮琢柞"},
+            {NULL, NULL}
+
+```
+
+**The last item** must end with `{null, null}` , or it will not work properly.
+
+### Apply new 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:
+
+<details>
+<summary>中文</summary>
+<p>
+
+按照上面的词库格式编写好自己的词库之后，参考下面的用法，调用 `lv_100ask_pinyin_ime_set_dict(pinyin_ime, your_pinyin_dict)` 函数即可设置和使用新词库：
+
+</p>
+</details>
+
+```c
+    lv_obj_t * pinyin_ime = lv_100ask_pinyin_ime_create(lv_scr_act());
+    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
+
+.. include:: ../../examples/others/ime/index.rst
+
+```
+
+## API
+
+```eval_rst
+
+.. doxygenfile:: lv_ime_pinyin.h
+  :project: lvgl
+
+```

lvgl_v8_back/lvgl/docs/others/imgfont.md

@@ -0,0 +1,25 @@
+# Image font (imgfont)
+Draw image in label or span obj with imgfont.
+This is often used to display Unicode emoji icons in text.
+Supported image formats: determined by LVGL image decoder.
+
+## Usage
+Enable `LV_USE_IMGFONT` in `lv_conf.h`.
+
+To create a new imgfont use `lv_imgfont_create(height, path_cb)`.
+
+`height` used to indicate the size of a imgfont.
+`path_cb` Used to get the image path of the specified unicode.
+
+Use `lv_imgfont_destroy(imgfont)` to destroy a imgfont that is no longer used.
+
+## Example
+```eval_rst
+.. include:: ../../examples/others/imgfont/index.rst
+```
+
+## API
+```eval_rst
+.. doxygenfile:: lv_imgfont.h
+  :project: lvgl
+```

lvgl_v8_back/lvgl/docs/others/index.md

@@ -0,0 +1,17 @@
+# Others
+
+
+```eval_rst
+
+.. toctree::
+   :maxdepth: 1
+
+   snapshot
+   monkey
+   gridnav
+   fragment
+   msg
+   imgfont
+   ime_pinyin
+```
+

lvgl_v8_back/lvgl/docs/others/monkey.md

@@ -0,0 +1,35 @@
+# Monkey
+
+A simple monkey test. Use random input to stress test the application.
+
+## Usage
+
+Enable `LV_USE_MONKEY` in `lv_conf.h`.
+
+First configure monkey, use `lv_monkey_config_t` to define the configuration structure, set the `type` (check [input devices](/overview/indev) for the supported types), and then set the range of `period_range` and `input_range`, the monkey will output random operations at random times within this range. Call `lv_monkey_create` to create monkey. Finally call `lv_monkey_set_enable(monkey, true)` to enable monkey.
+
+If you want to pause the monkey, call `lv_monkey_set_enable(monkey, false)`. To delete the monkey, call `lv_monkey_del(monkey)`.
+
+Note that `input_range` has different meanings in different `type`:
+
+- `LV_INDEV_TYPE_POINTER` No effect, click randomly within the pixels of the screen resolution.
+- `LV_INDEV_TYPE_ENCODER` The minimum and maximum values ​​of `enc_diff`.
+- `LV_INDEV_TYPE_BUTTON` The minimum and maximum values ​​of `btn_id`. Use `lv_monkey_get_indev()` to get the input device, and use `lv_indev_set_button_points()` to map the key ID to the coordinates.
+- `LV_INDEV_TYPE_KEYPAD` No effect, Send random [Keys](/overview/indev).
+
+## Example
+
+```eval_rst
+
+.. include:: ../../examples/others/monkey/index.rst
+
+```
+## API
+
+
+```eval_rst
+
+.. doxygenfile:: lv_monkey.h
+  :project: lvgl
+
+```

lvgl_v8_back/lvgl/docs/others/msg.md

@@ -0,0 +1,97 @@
+# Messaging
+
+Messaging (`lv_msg`) is a classic []publisher subscriber](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern) implementation for LVGL.
+
+## IDs
+Both the publishers and the subscribers needs to know the message identifiers.
+In `lv_msg` these are simple `uint32_t` integers. For example:
+```c
+#define MSG_DOOR_OPENED             1
+#define MSG_DOOR_CLOSED             2
+#define MSG_USER_NAME_CHANGED       100
+#define MSG_USER_AVATAR_CHANGED     101
+```
+
+You can orgnaize the message IDs as you wish.
+
+Both parties also need to know about the format of teh payload. E.g. in the above example
+`MSG_DOOR_OPENED` and `MSG_DOOR_CLOSED` has no payload but `MSG_USER_NAME_CHANGED` can have a `const char *` payload containing the user name, and `MSG_USER_AVATAR_CHANGED` a `const void *` image source with the new avatar image.
+
+
+## Send message
+
+Messages can be sent with `lv_msg_send(msg_id, payload)`. E.g.
+```c
+lv_msg_send(MSG_USER_DOOR_OPENED, NULL);
+lv_msg_send(MSG_USER_NAME_CHANGED, "John Smith");
+```
+
+## Subscribe to a message
+
+`lv_msg_subscribe(msg_id, callback, user_data)` can be used to subscribe to message.
+
+The callback should look like this:
+```c
+
+static void user_name_subscriber_cb(void * s, lv_msg_t * m)
+{
+    /*s: a subscriber obeject, can be used to unscubscribe*/
+    /*m: a message object with the msg_id, payload, and user_data (set durung subscription)*/
+
+    ...do something...
+}
+```
+
+From `lv_msg_t` the followings can be used to get some data:
+- `lv_msg_get_id(m)`
+- `lv_msg_get_payload(m)`
+- `lv_msg_get_user_data(m)`
+
+## Subscribe with an lv_obj
+It's quite typical that an LVGL widget is interested in some messages.
+To make it simpler `lv_msg_subsribe_obj(msg_id, obj, user_data)` can be used.
+If a new message is published with `msg_id` an `LV_EVENT_MSG_RECEIVED` event will be sent to the object.
+
+For example:
+```c
+lv_obj_add_event_cb(user_name_label, user_name_label_event_cb, LV_EVENT_MSG_RECEIVED, NULL);
+lv_msg_subsribe_obj(MSG_USER_NAME_CHANGED, user_name_label, NULL);
+
+...
+
+void user_name_label_event_cb(lv_event_t * e)
+{
+    lv_obj_t * label = lv_event_get_target(e);
+    lv_msg_t * m = lv_event_get_msg(e);
+    lv_label_set_text(label, lv_msg_get_payload(m));
+}
+
+```
+
+### Unsubscribe
+`lv_msg_subscribe` returns a pointer which can be used to unsubscribe:
+```c
+void * s1;
+s1 = lv_msg_subscribe(MSG_USER_DOOR_OPENED, some_callback, NULL);
+
+...
+
+lv_msg_unsubscribe(s1);
+```
+
+## Example
+
+```eval_rst
+
+.. include:: ../../examples/others/msg/index.rst
+
+```
+## API
+
+
+```eval_rst
+
+.. doxygenfile:: lv_msg.h
+  :project: lvgl
+
+```

lvgl_v8_back/lvgl/docs/others/snapshot.md

@@ -0,0 +1,63 @@
+# Snapshot
+
+Snapshot provides APIs to take snapshot image for LVGL object together with its children. The image will look exactly like the object.
+
+## Usage
+
+Simply call API `lv_snapshot_take` to generate the image descriptor which can be set as image object src using `lv_img_set_src`.
+
+
+Note, only below color formats are supported for now:
+ - LV_IMG_CF_TRUE_COLOR_ALPHA
+ - LV_IMG_CF_ALPHA_1BIT
+ - LV_IMG_CF_ALPHA_2BIT
+ - LV_IMG_CF_ALPHA_4BIT
+ - LV_IMG_CF_ALPHA_8BIT
+
+
+### Free the Image
+The memory `lv_snapshot_take` uses are dynamically allocated using `lv_mem_alloc`. Use API `lv_snapshot_free` to free the memory it takes. This will firstly free memory the image data takes, then the image descriptor.
+
+
+Take caution to free the snapshot but not delete the image object. Before free the memory, be sure to firstly unlink it from image object, using `lv_img_set_src(NULL)` and `lv_img_cache_invalidate_src(src)`.
+
+
+Below code snippet explains usage of this API.
+
+```c
+void update_snapshot(lv_obj_t * obj, lv_obj_t * img_snapshot)
+{
+    lv_img_dsc_t* snapshot = (void*)lv_img_get_src(img_snapshot);
+    if(snapshot) {
+        lv_snapshot_free(snapshot);
+    }
+    snapshot = lv_snapshot_take(obj, LV_IMG_CF_TRUE_COLOR_ALPHA);
+    lv_img_set_src(img_snapshot, snapshot);
+}
+```
+
+### Use Existing Buffer
+If the snapshot needs update now and then, or simply caller provides memory, use API `lv_res_t lv_snapshot_take_to_buf(lv_obj_t * obj, lv_img_cf_t cf, lv_img_dsc_t * dsc, void * buf, uint32_t buff_size);` for this case. It's caller's responsibility to alloc/free the memory.
+
+
+If snapshot is generated successfully, the image descriptor is updated and image data will be stored to provided `buf`.
+
+
+Note that snapshot may fail if provided buffer is not enough, which may happen when object size changes. It's recommended to use API `lv_snapshot_buf_size_needed` to check the needed buffer size in byte firstly and resize the buffer accordingly.
+
+## Example
+
+```eval_rst
+
+.. include:: ../../examples/others/snapshot/index.rst
+
+```
+## API
+
+
+```eval_rst
+
+.. doxygenfile:: lv_snapshot.h
+  :project: lvgl
+
+```