In the Littlev Graphics Library the basic building blocks of a user interface are the objects. For example:
Click to check all the existing object types.
The objects have basic attributes which are common independently from their type:
You can set/get this attributes with
lv_obj_get_... functions. For example:
To see all the available functions visit the Base object's documentation.
/*Set basic object attributes*/ lv_obj_set_size(btn1, 100, 50); /*Button size*/ lv_obj_set_pos(btn1, 20,30); /*Button position*/
The object types have special attributes. For example a slider have:
For these attributes every object type have unique API functions. For example for a slider:
/*Set slider specific attributes*/ lv_slider_set_range(slider1, 0, 100); /*Set min. and max. values*/ lv_slider_set_value(slider1, 40); /*Set the current value (position)*/ lv_slider_set_action(slider1, my_action); /*Set a callback function*/
A parent can be considered as the container of its children. Every object has exactly one parent object (except screens) but a parent can have unlimited number of children. There is no limitation for the type of the parent but there typically parent (e.g. button) and typical child (e.g. label) objects.
The screen is a special object which has no parent object. Always there is an active screen. By default the library creates and loads one.
To get the currently active screen use the
A screen can be craeted with any object type, for example a basic object or an image to make a wallpaper.
If the position of the parent is changed the children will move with the parent. Therefore all positions are relative to the parent. So the (0;0) coordinates means the objects will remain in the top left hand corner of the parent independently from the position of the parent.
lv_obj_t * par = lv_obj_create(lv_scr_act(), NULL); /*Create a parent object on the current screen*/ lv_obj_set_size(par, 100, 80); /*Set the size of the parent*/ lv_obj_t * obj1 = lv_obj_create(par, NULL); /*Create an object on the previously created parent object*/ lv_obj_set_pos(obj1, 10, 10); /*Set the position of the new object*/
lv_obj_set_pos(par, 50, 50); /*Move the parent. The child will move with it.*/
lv_obj_set_x(obj1, -30); /*Move the child a little bit of the parent*/
In the graphics library objects can be created and deleted dynamically in run-time. It means only the currently created objects consume RAM. For example if you need a chart you can create it only when it is required and delete after it is used.
Every objects type has its own create function with an uniformed prototype. It needs two parameters: a pointer the parent object and optionally a pointer to an other object with the same type. If the second parameter is not NULL then this objects will be copied to the new one. To create a screen give NULL as parent. The return value of the create function is a pointer to the created object. Independently from the object type a common variable type lv_obj_t is used. This pointer can be used later to set or get the attributes of the object. The create functions look like this:
lv_obj_t * lv_type_create(lv_obj_t * parent, lv_obj_t * copy);
There is a common delete function for all object types. It deletes the object and all of its children.
void lv_obj_del(lv_obj_t * obj);
You can delete only the children of an object but leave the object itself "alive":
void lv_obj_clean(lv_obj_t * obj);
The earlier created object (and its children) will drawn earlier (nearer to the background). In other words the lastly created object will be on the top among its siblings. It is very important, the order is calculated among the objects on the same level ("siblings").
Layers can be added easily by creating 2 objects (which can be transparent) firstly 'A' and secondly 'B'. 'A' and every object on it will be in the background and can be covered by 'B' and its children.
/*Create a screen*/ lv_obj_t * scr = lv_obj_create(NULL, NULL); lv_scr_load(scr); /*Load the screen*/ /*Create 2 buttons*/ lv_obj_t * btn1 = lv_btn_create(scr, NULL); /*Create a button on the screen*/ lv_btn_set_fit(btn1, true, true); /*Enable to automatically set the size according to the content*/ lv_obj_set_pos(btn1, 60, 40); /*Set the position of the button*/ lv_obj_t * btn2 = lv_btn_create(scr, btn1); /*Copy the first button*/ lv_obj_set_pos(btn2, 180, 80); /*Set the position of the button*/ /*Add labels to the buttons*/ lv_obj_t * label1 = lv_label_create(btn1, NULL); /*Create a label on the first button*/ lv_label_set_text(label1, "Button 1"); /*Set the text of the label*/ lv_obj_t * label2 = lv_label_create(btn2, NULL); /*Create a label on the second button*/ lv_label_set_text(label2, "Button 2"); /*Set the text of the label*/ /*Delete the second label*/ lv_obj_del(label2);
To set the appearance of the objects styles can be used. A style is a structure variable with attributes like colors, paddings, visibility and others. There is common style type: lv_style_t.
By setting the fields of an lv_style_t structure you can influence the appearance of the objects using that style.
A style have 5 main parts: common, body, text, image and line. An object will use that fields which are relevant for it. For example Lines don't care about the letter_space. To see which fields are used by an object type see their documentation.
The fields of a style structure are the followings:
Every object type have a unique function to set its style or styles.
If the object has only one style - like a label - the
lv_label_set_style(label1, &style) function can be used to set a new style.
If the object has more styles (like a button have 5 styles for each state)
lv_btn_set_style(obj, LV_BTN_STYLE_..., &rel_style) function can be used to set a new style.
The styles and the style properties used by an object type are described in their documentation.
If you modify a style which is used by one or more objects then the objects have to be notified about the style is changed. You have two options to do that:
void lv_obj_refresh_style(lv_obj_t * obj); /*Notify an object about its style is modified*/ void lv_obj_report_style_mod(void * style); /*Notify all object if a style is modified.(NULL to notify all objects)*/
If the style of an object is NULL then its style will be inherited from its parent's style. It makes easier to create consistent design. Don't forget a style describes a lot of properties at the same time. So for example if you set a button's style and create a label on it with NULL style then the label will be rendered according to the buttons styles. In other words the button makes sure its children will look well on it.
Setting the glass style property will prevent inheriting that style. You should use it if the style is transparent so that its children use colors and others from its parent.
There are several built-in styles in the library:
As you can see there is a style for screens, for buttons, plain and pretty styles and transparent styles as well. The lv_style_transp, lv_style_transp_fit and lv_style_transp_tight differ only in paddings: for lv_style_transp_tight all padings are zero, for lv_style_transp_fit only hor and ver paddings are zero.
The built in styles are global lv_style_t variables so you can use them like:
lv_btn_set_style(obj, LV_BTN_STYLE_REL, &lv_style_btn_rel)
You can modify the built-in styles or you can create new styles. When creating new styles it is recommended to firstly copy a built-in style to be sure all fields are initialized with a proper value. The
lv_style_copy(&dest_style, &src_style) can be used to copy styles.
You can animate styles using
lv_style_anim_create(&anim). Before calling this function you have to initialize an lv_style_anim_t variable. The animation will fade a style_1 to style_2
lv_style_anim_t a; /*Will be copied, can be local variable*/ a.style_anim = & style_to_anim; /*Pointer to style to animate*/ a.style_start = & style_1; /*Pointer to the initial style (only pointer saved) */ a.style_end = & style_2; /*Pointer to the target style (only pointer saved) */ a.act_time = 0; /*Set negative to make a delay*/ a.time = 1000; /*Time of animation in milliseconds*/ a.playback = 0; /*1: play the animation backward too*/ a.playback_pause = 0; /*Wait before playback [ms]*/ a.repeat = 0; /*1: repeat the animation*/ a.repeat_pause = 0; /*Wait before repeat [ms]*/ a.end_cb = NULL; /*Call this function when the animation ready*/
The example below demonstrates the above described style usage.
/*Create a style*/ static lv_style_t style1; lv_style_copy(&style1, &lv_style_plain); /*Copy a built-in style to initialize the new style*/ style1.body.main_color = LV_COLOR_WHITE; style1.body.grad_color = LV_COLOR_BLUE; style1.body.radius = 10; style1.body.border.color = LV_COLOR_GRAY; style1.body.border.width = 2; style1.body.border.opa = LV_OPA_50; style1.body.padding.hor = 5; /*Horizontal padding, used by the bar indicator below*/ style1.body.padding.ver = 5; /*Vertical padding, used by the bar indicator below*/ style1.text.color = LV_COLOR_RED; /*Create a simple object*/ lv_obj_t *obj1 = lv_obj_create(lv_scr_act(), NULL); lv_obj_set_style(obj1, &style1); /*Apply the created style*/ lv_obj_set_pos(obj1, 20, 20); /*Set the position*/ /*Create a label on the object. The label's style is NULL by default*/ lv_obj_t *label = lv_label_create(obj1, NULL); lv_obj_align(label, NULL, LV_ALIGN_CENTER, 0, 0); /*Align the label to the middle*/ /*Create a bar*/ lv_obj_t *bar1 = lv_bar_create(lv_scr_act(), NULL); lv_bar_set_style(bar1, LV_BAR_STYLE_INDIC, &style1); /*Modify the indicator's style*/ lv_bar_set_value(bar1, 70); /*Set the bar's value*/
To create styles for your GUI is challenging because you need a deeper understanding of the library and you need to have some designer skills. In addition it takes a lot of time to create so much styles.
To speed up the design part themes are introduced. A theme is a style collection which contains the required styles for every object type. For example 5 styles for buttons to describe their 5 possible states.
Check the Existing themes.
To be more specific a theme is a structure variable which contains a lot of lv_style_t * fields. For buttons:
theme.btn.rel /*Released button style*/ theme.btn.pr /*Pressed button style*/ theme.btn.tgl_rel /*Toggled released button style*/ theme.btn.tgl_pr /*Toggled pressed button style*/ theme.btn.ina /*Inactive button style*/
A theme can initialized by:
lv_theme_xxx_init(hue, font). Where xxx is the name of the theme, hue is a hue value from HSV color space (0..360) and font is the font applied in the theme (NULL to use the LV_FONT_DEFAULT default font)
When a theme is initialized its styles can be used like this:
/*Create a default slider*/ lv_obj_t *slider = lv_slider_create(lv_scr_act(), NULL); lv_slider_set_value(slider, 70); lv_obj_set_pos(slider, 10, 10); /*Initialize the alien theme with a redish hue*/ lv_theme_t *th = lv_theme_alien_init(10, NULL); /*Create a new slider and apply the themes styles*/ slider = lv_slider_create(lv_scr_act(), NULL); lv_slider_set_value(slider, 70); lv_obj_set_pos(slider, 10, 50); lv_slider_set_style(slider, LV_SLIDER_STYLE_BG, th->slider.bg); lv_slider_set_style(slider, LV_SLIDER_STYLE_INDIC, th->slider.indic); lv_slider_set_style(slider, LV_SLIDER_STYLE_KNOB, th->slider.knob);
You can force the library to apply the styles from a theme when you create new objects. To do this use
The color module handles all color related functions like: changing color depth, creating colors from hex code, conversation between color depths, mixing colors etc.
The following variable types are defined by the color module:
The lv_color_t, lv_color1_t lv_color8_t, lv_color16_t and lv_color24_t types have got four fields:
You can set the current color depth in lv_conf.h by setting the LV_COLOR_DEPTH define to 1 (monochrome), 8, 16 or 24.
You can convert a color from the current color depth to an other. The converter functions return with a number so you have to use the full field:
lv_color_t c; c.red = 0x38; c.green = 0x70; c.blue = 0xCC; lv_color1_t c1; c1.full = lv_color_to1(c); /*Return 1 for light colors, 0 for dark colors*/ lv_color8_t c8; c8.full = lv_color_to8(c); /*Give a 8 bit number with the converted color*/ lv_color16_t c16; c16.full = lv_color_to16(c); /*Give a 16 bit number with the converted color*/ lv_color24_t c24; c24.full = lv_color_to24(c); /*Give a 32 bit number with the converted color*/
You can create a color with the current color depth using the LV_COLOR_MAKE macro. It takes 3 arguments (red, green, blue) as 8 bit numbers. For example to create light red color:
my_color = COLOR_MAKE(0xFF, 0x80, 0x80)
Colors can be created from HEX codes too:
my_color = LV_COLOR_HEX(0xFF8080) or
my_color = LV_COLOR_HEX3(0xF88)
Mixing two colors is possible with
mixed_color = lv_color_mix(color1, color2, ratio). Ration can be 0..255. 0 results fully color2, 255 result fully color1.
To describe opacity the lv_opa_t type is created as wrapper to uint8_t. Some defines are also introduced:
You can also use the LV_OPA_* defines in lv_color_mix() as ratio.
The color module defines the most basic colors:
LV_COLOR_BLACK, LV_COLOR_GRAY, LV_COLOR_SILVER, LV_COLOR_WHITE,
LV_COLOR_LIME, LV_COLOR_GREEN, LV_COLOR_OLIVE,
LV_COLOR_BLUE, LV_COLOR_NAVY, LV_COLOR_TAIL, LV_COLOR_CYAN, LV_COLOR_AQUA,
In LittlevGL fonts are bitmaps and other descriptor arrays to store the images of the letters and some additional information. A font is stored in a lv_font_t variable and can be set it in style's text.font field.
There are several built-in fonts which can be enabled in lv_conf.h by USE_LV_FONT_... defines. There are built-in fonts in different sizes:
The built-in fonts exist with multiply character-sets in each size:
The built-in fonts uses the Dejavu font.
The built-in fonts are global variables with names like:
The LittlevGL supports using Unicode letter from UTF-8 coded characters. You need to configure your editor to save the your code/text as UTF-8 (usually this the default) and enable LV_TXT_UTF8 in lv_conf.h. Without enabled LV_TXT_UTF8 only ASCII fonts and symbols can be used (see the symbols below)
After it the texts will be decoded to determine the Unicode values in them. To display the letters your font needs to contain the image (glyph) of the characters. As the built-in fonts show the fonts are stored modularly but you can assign more fonts to create an larger character-set. To do this choose a base font (typically the ASCII font) and add the extensions to it:
lv_font_add(child, parent). Only fonts with same height can be assigned.
The built-in fonts are already added to the same sized ASCII font. For example if USE_LV_FONT_DEJAVU_20 and USE_LV_FONT_DEJAVU_20_SUP are enabled in lv_conf.h then the "abcÁÖÜ" text can be rendered when using lv_font_dejavu_20
The symbol fonts are special fonts which contain symbols instead of letters. There are built-in symbol fonts as well and they are also assigned to the ASCII font with the same size. In a text a symbol can be referenced like SYMBOL_LEFT, SYMBOL_RIGHT etc. You can mix these symbol names with strings:
lv_label_set_text(label1, "Right "SYMBOL_RIGHT);
The symbols can be used without Unicode support as well. (LV_TXT_UTF8 0)
The symbols fonts have 3 groups with the following symbols in them:
/*Create a new style for the label*/ static lv_style_t style; lv_style_copy(&style, &lv_style_plain); style.text.color = LV_COLOR_BLUE; style.text.font = &lv_font_dejavu_40; /*Unicode and symbol fonts already assigned by the library*/ lv_obj_t *label; /*Use ASCII and Unicode letters*/ label = lv_label_create(lv_scr_act(), NULL); lv_obj_set_pos(label, 20, 20); lv_label_set_style(label, &style); lv_label_set_text(label, "aeuois\n" "äéüöíß"); /*Mix text and symbols*/ label = lv_label_create(lv_scr_act(), NULL); lv_obj_set_pos(label, 20, 100); lv_label_set_style(label, &style); lv_label_set_text(label, "Right "SYMBOL_RIGHT);
You can automatically change the value (animate) of a variable between a start and an end value using an animator function with
void func(void * var, int32_t value) prototype. The animation will happen by periodical calling of the animator function with the the corresponding value parameter.
To create an animation you have to initializes an lv_anim_t variable (there is a template in lv_anim.h):
lv_anim_t a; a.var = button1; /*Variable to animate*/ a.start = 100; /*Start value*/ a.end = 300; /*End value*/ a.fp = (anim_fp_t)lv_obj_set_height; /*Function to be used to animate*/ a.path = lv_anim_path_linear; /*Path of animation*/ a.end_cb = NULL; /*Callback when the animation is ready*/ a.act_time = 0; /*Set < 0 to make a delay [ms]*/ a.time = 200; /*Animation length [ms]*/ a.playback = 0; /*1: animate in reverse direction too when the normal is ready*/ a.playback_pause = 0; /*Wait before palyback [ms]*/ a.repeat = 0; /*1: Repeat the animation (with or without playback)*/ a.repeat_pause = 0; /*Wait before repeate [ms]*/ lv_anim_create(&a); /*Start the animation*/
anim_create(&a) will register the animation and immediately applies the start value regardless to the set delay.
You can determinate the path of animation. In most simple case it is linear which means the current value between start and end is changed linearly. A path is function which calculates the next value to set based on the current state of the animation. Currently there are two built in paths:
By default you can set the animation time. But in some cases the animation speed is more practical. The
lv_anim_speed_to_time(speed, start, end) function calculates the required time in milliseconds to reach the end value from a start value with the given speed. The speed is interpreted in unit/sec dimension. For example
anim_speed_to_time(20, 0, 100) will give 5000 milliseconds
You can apply multiple different animations on the same variable at the same time. (For example animate the x and y coordinates with lv_obj_set_x end lv_obj_set_y). But only one animation can exist with a given variable and function pair. Therefore the lv_anim_create() function will delete the already existing variable-function animations.
You can delete an animation by
lv_anim_del(var, func) with providing the animated variable and its animator function.
To iteract with the created object Input devices are required. For example Touch pad, Mouse, Keyboard or even an Encoder. To learn how to add an input device read the Porting guide.
When you register an input device driver the library adds some extra information to it to describe the state of the input device in more detail. When a user action (e.g. a button press) happens and an action (callback) function is triggered always there is an input device which triggered that action. You can get this input device with
lv_indev_t *indev = lv_indev_get_act(). It might be important when you need to know some special information about the input device like the currently pressed point, or dragging an object or not etc.
The input devices have a very simple API:
/*Get the last point on a display input*/ void lv_indev_get_point(lv_indev_t * indev, point_t * point); /*Check if there is dragging on input device or not */ bool lv_indev_is_dragging(lv_indev_t * indev); /*Get the vector of dragging on a input device*/ void lv_indev_get_vect(lv_indev_t * indev, point_t * point); /*Do nothing until the next release*/ void lv_indev_wait_release(lv_indev_t * indev); /*Do nothing until the next release*/ void lv_indev_wait_release(lv_indev_t * indev); /*Reset one or all (use NULL) input devices*/ void lv_indev_reset(lv_indev_t * indev); /*Reset the long pressed state of an input device*/ void lv_indev_reset_lpr(lv_indev_t * indev); /*Set a cursor for a pointer input device*/ void lv_indev_set_cursor(lv_indev_t * indev, lv_obj_t * cur_obj); /*Set a destination group for a keypad input device*/ void lv_indev_set_group(lv_indev_t * indev, lv_group_t * group);
The objects can be grouped in order to easily control them without touch pad or mouse. It allows you to use
to navigate among objects.
Firstly you have to create an object group with
lv_groupt_t *group = lv_group_create() and add objects to it with
lv_group_add_obj(group, obj). In a group always there is a focused object. All the button press will be "sent" to the currently focused obejct.
To navigate among the objects in a group (change the focused obejct) and iteract with them an LV_INDEV_TYPE_KEYPAD typed input device is required. In its read function you can tell the library which key is pressed or released. To learn how to add an input device read the Porting guide.
Besides you have to assign the group to the input device with
There are some special control characters which can be used in the read function:
In some cases (e.g. when a pop up window appears) it is useful to freeze the focus on an object. It means the LV_GROUP_KEY_NEXT/PREV will be ignored. You can do it with
The style of the object in focus is modified by a function. By default it make the object's colors orangish but you can also specify your own style updater function in each group with
void lv_group_set_style_mod_cb(group, style_mod_cb). The style_mod_cb waits an lv_style_t * parameter which is a copy of the focused object's style. In the callback you can mix some colors to the current ones, and modify parameters but is not permitted to set attributes which modifiy the size (like letter_space, padding etc.)
In LittlevGL you can think in graphical objects and don't care hot the drawing happens. You can set the size, position or any attribute of the object an the library will refresh the old (invalid) areas and redraw the new ones. However you should know the basic drawing methods to know which one you should choose.
The unbuffered drawing puts the pixels directly to the display (frame buffer). Therefore during the drawing process some flickering might be visible because firstly the background has to be drawn and then the object on it. For this reason this type is not suitable when scrolling, dragging and animations are used. On the other hand it has the smallest memory footprint because no extra graphics buffer is required.
To use unbuffered drawing set LV_VDB_SIZE to 0 in lv_conf.h and register a disp_map and a disp_fillfunctions
The buffered drawing is similar to double buffering when two screen sized buffers are used (one for rendering and an other to display the last ready frame). However LittlevGL's buffered drawing algorithm uses only one frame buffer an small graphical buffer called Virtual Display Buffer (VDB). For VDB size ~1/10 screen size is typically enough. For a 320 × 240 screen with 16 bit colors it means only 15 kB extra RAM.
With buffered drawing there is no flickering because the image is created firstly in the memory (VDB), therefore scrolling, dragging and animations can be used. In addition it enables the using of other graphical effects like anti-aliasing, transparency (opacity) and shadows.
To use buffered drawing set LV_VDB_SIZE to > 0 in lv_conf.h and register a disp_flush functions.
In buffered mode you can use double VDB to parallelly execute rendering into one VDB and coping pixels to your frame buffer from an other. The copy should use DMA or other hardware acceleration to work the background to let the CPU to do other things. In lv_conf.h the LV_VDB_DOUBLE 1 enables this feature.
Keep in mind it's not sure that the unbuffered drawing is faster. During rendering a pixel is overwritten multiple times (e.g. background, button, text above each other). This way in unbuffered mode the library needs to access the external memory or display controller several times which is slower writing/reading the internal RAM.
The following table summarizes the differences between the two drawing methods:
|Unbuffered drawing||Buffered drawing|
|Memory usage||No extra||>~1/10 screen|
|Font Antialaissing||Lower quality||High quality|
|Screen Antialaissing||Not supported||Supported|
In lv_conf.h you can enable the anti-aliasing of fonts (LV_FONT_ANTIALIAS) or the full scren (LV_ANTIALIAS). The full screen anti-alias is supported only in buffered mode (LV_VDB_SIZE > 0) and the quality of font anti-aliasing is better in buffered mode as well.
The full screen anti-aliasing uses a super sampling algorithm. It means everything is rendered in double size and then filtered to the normal size. The filter takes the average of 2 × 2 adjacent pixels to make a smooth result.
There are static contents (fonts and images) which size can not be doubled by the library so their size will be halved in the result image. To avoid it use double sized fonts and images. Optionally the images can be upscaled by the library too. See Images
Keep in mind the anti-aliasing needs extra computation resources: it required higher fill rate and extra time to filter the reeeasult image. So when choosing the MCU for anti-aliasing consider selecting a better one with higher clock rate and/or GPU. Or use only font anti-aliasing as described below.
Because the text needs anti-aliasing the most there is an option to anti-alias only them. Similarly to screen sized anti-aliasing in this case also double sized fonts need to be used.
The font anti-aliasing has only a little computation overhead so usually it can be used without changing to a better MCU
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:
All Rights Reserved © 2018 Hungary