Overview

As it names shows the Keyboard object provides a keyboard to write text. You can assign a Text area to the Keyboard to put the clicked characters there. To assign the Text area use lv_kb_set_ta(kb, ta).

The keyboard contains an Ok and a Hide button. An ok and a hide action can be specified by lv_kb_set_ok_action(kb, action) and lv_kb_set_hide_action(kb, action) to add callbacks to Ok/Hide clicks. If no action is specified then the buttons will delete the Keyboard.

The assigned Text area's cursor can be managed by the keyboard: when the keyboard is assigned the previous Text area's cursor will be hidden an the new's will be shown. Clicking on Ok or Hide will also hide the cursor. The cursor manager feature is enabled by lv_kb_set_cursor_manage(kb, true). The default is not manage.

The Keyboards have two modes:

  • LV_KB_MODE_TEXT: display letters, number and special characters
  • LV_KB_MODE_NUM: display numbers, +/- sign and dot

To set the mode use lv_kb_set_mode(kb, mode). The default is LV_KB_MODE_TEXT

You can specify a new map (layout) for the keyboard with lv_kb_set_map(kb, map). It works like a the Button matrix so control character can be added to the layout the set button width and other attributes. Keep in mind using following keywords will have the same effect as with the original map: SYMBOL_OK, SYMBOL_CLOSE, SYMBOL_LEFT, SYMBOL_RIGHT, ABC, abc, Enter, Del, #1, +/-

Style usage

The Keyboard works with 6 styles: a background and 5 button styles for each states. You can set the styles with lv_kb_set_style(btn, LV_KB_STYLE_..., &style). The background and the buttons use the style.body properties. The labels use the style.text properties of the button styles.

  • LV_KB_STYLE_BG Background style. Uses all style.body properties including padding Default: lv_style_pretty
  • LV_KB_STYLE_BTN_REL style of the released buttons. Default: lv_style_btn_rel
  • LV_KB_STYLE_BTN_PR style of the pressed buttons. Default: lv_style_btn_pr
  • LV_KB_STYLE_BTN_TGL_REL style of the toggled released buttons. Default: lv_style_btn_tgl_rel
  • LV_KB_STYLE_BTN_TGL_PR style of the toggled pressed buttons. Default: lv_style_btn_tgl_pr
  • LV_KB_STYLE_BTN_INA style of the inactive buttons. Default: lv_style_btn_ina

Notes

Example of Keyboard in Littlev Graphics Library

						/*Create styles for the keyboard*/
static lv_style_t rel_style, pr_style;

lv_style_copy(&rel_style, &lv_style_btn_rel);
rel_style.body.radius = 0;

lv_style_copy(&pr_style, &lv_style_btn_pr);
pr_style.body.radius = 0;

/*Create a keyboard and apply the styles*/
lv_obj_t *kb = lv_kb_create(lv_scr_act(), NULL);
lv_kb_set_cursor_manage(kb, true);
lv_kb_set_style(kb, LV_KB_STYLE_BG, &lv_style_transp_tight);
lv_kb_set_style(kb, LV_KB_STYLE_BTN_REL, &rel_style);
lv_kb_set_style(kb, LV_KB_STYLE_BTN_PR, &pr_style);

/*Create a text area. The keyboard will write here*/
lv_obj_t *ta = lv_ta_create(lv_scr_act(), NULL);
lv_obj_align(ta, NULL, LV_ALIGN_IN_TOP_MID, 0, 10);
lv_ta_set_text(ta, "");

/*Assign the text area to the keyboard*/
lv_kb_set_ta(kb, ta);

lv_obj_t *

lv_kb_create

(lv_obj_t * par, lv_obj_t * copy);

Create a keyboard objects

par pointer to an object, it will be the parent of the new keyboard

copy pointer to a keyboard object, if not NULL then the new object will be copied from it

return pointer to the created keyboard

void

lv_kb_set_ta

(lv_obj_t * kb, lv_obj_t * ta);

Assign a Text Area to the Keyboard. The pressed characters will be put there.

kb pointer to a Keyboard object

ta pointer to a Text Area object to write there

void

lv_kb_set_mode

(lv_obj_t * kb, lv_kb_mode_t mode);

Set a new a mode (text or number map)

kb pointer to a Keyboard object

mode the mode from 'lv_kb_mode_t'

void

lv_kb_set_cursor_manage

(lv_obj_t * kb, bool en);

Automatically hide or show the cursor of the current Text Area

kb pointer to a Keyboard object

en true: show cursor on the current text area, false: hide cursor

void

lv_kb_set_ok_action

(lv_obj_t * kb, lv_action_t action);

Set call back to call when the "Ok" button is pressed

kb pointer to Keyboard object

action a callback with 'lv_action_t' type

void

lv_kb_set_hide_action

(lv_obj_t * kb, lv_action_t action);

Set call back to call when the "Hide" button is pressed

kb pointer to Keyboard object

action a callback with 'lv_action_t' type

void

lv_kb_set_map

(lv_obj_t *kb, const char ** map);

Set a new map for the keyboard

kb pointer to a Keyboard object

map pointer to a string array to describe the map.
See 'lv_btnm_set_map()' for more info.

void

lv_kb_set_style

(lv_obj_t *kb, lv_kb_style_t type, lv_style_t *style);

Set a style of a keyboard

kb pointer to a keyboard object

type which style should be set

style pointer to a style

lv_obj_t *

lv_kb_get_ta

(lv_obj_t * kb);

Assign a Text Area to the Keyboard. The pressed characters will be put there.

kb pointer to a Keyboard object

return pointer to the assigned Text Area object

lv_kb_mode_t

lv_kb_get_mode

(lv_obj_t * kb);

Set a new a mode (text or number map)

kb pointer to a Keyboard object

return the current mode from 'lv_kb_mode_t'

bool

lv_kb_get_cursor_manage

(lv_obj_t * kb);

Get the current cursor manage mode.

kb pointer to a Keyboard object

return true: show cursor on the current text area, false: hide cursor

lv_action_t

lv_kb_get_ok_action

(lv_obj_t * kb);

Get the callback to call when the "Ok" button is pressed

kb pointer to Keyboard object

return the ok callback

lv_action_t

lv_kb_get_hide_action

(lv_obj_t * kb);

Get the callback to call when the "Hide" button is pressed

kb pointer to Keyboard object

return the close callback

lv_style_t *

lv_kb_get_style

(lv_obj_t *kb, lv_kb_style_t type);

Get a style of a keyboard

kb pointer to a keyboard object

type which style should be get

return style pointer to a style

LittlevGL - Open-source Embedded GUI Library

LittlevGL is a free and open-source graphics library providing everything you need to create embedded GUI with easy-to-use graphical elements, beautiful visual effects and low memory footprint.

If you like LittlevGL, please
support its deveopment!


The founder of Littlev Graphics Library (LittlevGL) and related software modules is:
Gábor Kiss-Vámosi
All Rights Reserved ©  2018 Hungary