example(keyboard): add an example to show how to set a new map

fixes #3490

docs/widgets/extra/keyboard.md

@@ -37,11 +37,11 @@ Note that popovers for keys in the top row will draw outside the widget boundari
 The popovers currently are merely a visual effect and don't allow selecting additional characters such as accents yet.
 
 ### New Keymap
-You can specify a new map (layout) for the keyboard with `lv_keyboard_set_map(kb, map)` and `lv_keyboard_set_ctrl_map(kb, ctrl_map)`.
-Learn more about the [Button matrix](/widgets/core/btnmatrix) object.
+You can specify a new map (layout) for the keyboard with `lv_keyboard_set_map(kb, LV_KEYBOARD_MODE_..., kb_map, kb_ctrl);`. See the [Button matrix](/widgets/core/btnmatrix) for more information about creating new maps a ctrls.
+
 Keep in mind that using following keywords will have the same effect as with the original map:
-- `LV_SYMBOL_OK` Apply.
-- `LV_SYMBOL_CLOSE` or `LV_SYMBOL_KEYBOARD` Close.
+- `LV_SYMBOL_OK` Send `LV_EVENT_RADY` to the assigend Text area.
+- `LV_SYMBOL_CLOSE` or `LV_SYMBOL_KEYBOARD` Send `LV_EVENT_CANCEL` to the assigend Text area.
 - `LV_SYMBOL_BACKSPACE` Delete on the left.
 - `LV_SYMBOL_LEFT` Move the cursor left.
 - `LV_SYMBOL_RIGHT` Move the cursor right.

examples/widgets/keyboard/index.rst

@@ -5,3 +5,10 @@ Keyboard with text area
 .. lv_example:: widgets/keyboard/lv_example_keyboard_1
   :language: c
 
+
+Keyboard with custom map
+""""""""""""""""""""""""
+
+.. lv_example:: widgets/keyboard/lv_example_keyboard_2
+  :language: c
+

examples/widgets/keyboard/lv_example_keyboard_2.c

@@ -0,0 +1,51 @@
+#include "../../lv_examples.h"
+#if LV_USE_KEYBOARD && 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) {
+        lv_keyboard_set_textarea(kb, ta);
+        lv_obj_clear_flag(kb, LV_OBJ_FLAG_HIDDEN);
+    }
+
+    if(code == LV_EVENT_DEFOCUSED) {
+        lv_keyboard_set_textarea(kb, NULL);
+        lv_obj_add_flag(kb, LV_OBJ_FLAG_HIDDEN);
+    }
+}
+
+void lv_example_keyboard_2(void)
+{
+    /*Create an AZERTY keyboard map*/
+    static const char * kb_map[] = {"A", "Z", "E", "R", "T", "Y", "U", "I", "O", "P", LV_SYMBOL_BACKSPACE, "\n",
+                                    "Q", "S", "D", "F", "G", "J", "K", "L", "M",  LV_SYMBOL_NEW_LINE, "\n",
+                                    "W", "X", "C", "V", "B", "N", ",", ".", ":", "!", "?", "\n",
+                                    LV_SYMBOL_CLOSE, " ",  " ", " ", LV_SYMBOL_OK, NULL
+                                   };
+
+    /*Set the relative width of the buttons and other controls*/
+    static const lv_btnmatrix_ctrl_t kb_ctrl[] = {4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 6,
+                                                  4, 4, 4, 4, 4, 4, 4, 4, 4, 6,
+                                                  4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4,
+                                                  2, LV_BTNMATRIX_CTRL_HIDDEN | 2, 6, LV_BTNMATRIX_CTRL_HIDDEN | 2, 2
+                                                 };
+
+    /*Create a keyboard and add the new map as USER_1 mode*/
+    lv_obj_t * kb = lv_keyboard_create(lv_scr_act());
+
+    lv_keyboard_set_map(kb, LV_KEYBOARD_MODE_USER_1, kb_map, kb_ctrl);
+    lv_keyboard_set_mode(kb, LV_KEYBOARD_MODE_USER_1);
+
+    /*Create a text area. The keyboard will write here*/
+    lv_obj_t * ta;
+    ta = lv_textarea_create(lv_scr_act());
+    lv_obj_align(ta, LV_ALIGN_TOP_MID, 0, 10);
+    lv_obj_set_size(ta, lv_pct(90), 80);
+    lv_obj_add_state(ta, LV_STATE_FOCUSED);
+
+    lv_keyboard_set_textarea(kb, ta);
+}
+#endif

examples/widgets/lv_example_widgets.h

@@ -77,6 +77,7 @@ void lv_example_img_4(void);
 void lv_example_imgbtn_1(void);
 
 void lv_example_keyboard_1(void);
+void lv_example_keyboard_2(void);
 
 void lv_example_label_1(void);
 void lv_example_label_2(void);